Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
import type { CSSProperties } from "react";
import type { ThumbnailPerson } from "../../utils/thumbnail-layout";
// Rolls into hours past 3600s: podcast timestamps ran past "78:31" without it.
export const fmt = (s: number) => {
const t = Math.max(0, s);
const hours = Math.floor(t / 3600);
const minutes = Math.floor((t % 3600) / 60);
const seconds = Math.floor(t % 60);
const mm = String(minutes).padStart(2, "0");
const ss = String(seconds).padStart(2, "0");
return hours > 0 ? `${hours}:${mm}:${ss}` : `${minutes}:${ss}`;
};
/** "guest at 0:12, host at 0:41": where each face on a pair thumbnail came from. */
export function describePeople(people: ThumbnailPerson[]): string {
return people
.map((p) => {
const who = p.role ?? `${p.side} person`;
return p.source_time == null ? who : `${who} at ${fmt(p.source_time)}`;
})
.join(", ");
}
export const fmtMs = (s: number) =>
`${fmt(s)}.${String(Math.floor((s % 1) * 1000)).padStart(3, "0")}`;
// Kept in sync with the .section-label CSS class so section headers look
// identical whether set via this object or the class.
export const labelStyle: CSSProperties = {
fontSize: 11,
fontWeight: 700,
letterSpacing: "0.8px",
textTransform: "uppercase",
color: "var(--text2)",
marginBottom: 10,
display: "block",
};
// Scripts with no case distinction whose letters Unicode nonetheless assigns
// an uppercase mapping for display styling (Georgian Mkhedruli -> Mtavruli).
// Kept in sync with remotion/src/text.ts and backend/utils/text.py's
// safe_upper. This is the same fix for the studio's live caption/thumbnail
// preview, so it doesn't show a different alphabet than the final render.
const CASELESS_SCRIPT_RANGES: Array<[number, number]> = [
[0x10a0, 0x10ff], // Georgian (Mkhedruli, Asomtavruli)
[0x1c90, 0x1cbf], // Georgian Extended (Mtavruli)
[0x2d00, 0x2d2f], // Georgian Supplement
];
function isCaselessScriptChar(ch: string): boolean {
const cp = ch.codePointAt(0) ?? 0;
return CASELESS_SCRIPT_RANGES.some(([lo, hi]) => cp >= lo && cp <= hi);
}
export function safeUpper(text: string): string {
if (!text) return text;
let hasCaseless = false;
for (const ch of text) {
if (isCaselessScriptChar(ch)) {
hasCaseless = true;
break;
}
}
if (!hasCaseless) return text.toUpperCase();
return Array.from(text)
.map((ch) => (isCaselessScriptChar(ch) ? ch : ch.toUpperCase()))
.join("");
}
export class ApiError extends Error {
constructor(
message: string,
readonly status: number,
) {
super(message);
this.name = "ApiError";
}
}
async function request<T>(path: string, opts: RequestInit, jsonHeaders: boolean): Promise<T> {
const res = await fetch(`/api${path}`, {
...opts,
headers: jsonHeaders
? { "Content-Type": "application/json", ...opts.headers }
: opts.headers,
});
const text = await res.text();
let body: unknown;
let plainText: string | undefined;
if (text) {
try {
body = JSON.parse(text);
} catch {
plainText = text;
body = text;
}
}
const errorField = body instanceof Object && "error" in body ? body.error : undefined;
const messageField = body instanceof Object && "message" in body ? body.message : undefined;
if (!res.ok || errorField) {
const msg = plainText || errorField || messageField || `HTTP ${res.status}`;
throw new ApiError(String(msg), res.status);
}
// SAFETY: each caller names T as the JSON its /api route returns.
return body as T;
}
/** JSON request against /api. Throws ApiError on non-2xx or `{ error }` bodies. */
export function api<T = any>(path: string, opts: RequestInit = {}): Promise<T> {
return request<T>(path, opts, true);
}
/** Multipart upload (FormData body); skips the JSON content-type header. */
export function upload<T = any>(path: string, form: FormData): Promise<T> {
return request<T>(path, { method: "POST", body: form }, false);
}
export function timeAgo(iso: string): string {
const ms = Date.now() - new Date(iso).getTime();
const h = ms / 3_600_000;
if (h < 1) return `${Math.max(1, Math.round(h * 60))}m ago`;
if (h < 24) return `${Math.round(h)}h ago`;
return new Date(iso).toLocaleDateString();
}
export const basename = (p: string) => (p || "").split(/[/\\]/).pop() || "";
interface AssetReference {
name: string;
path: string;
type?: string;
}
/**
* Resolves a persisted asset name or absolute path back to its registered name.
* Preview URLs must use the asset route; the video source route intentionally
* rejects arbitrary image paths.
*/
export function resolveAssetName(
assets: AssetReference[],
reference: string,
type?: string,
): string | null {
if (!reference) return null;
return assets.find(
(asset) =>
(!type || asset.type === type) &&
(asset.name === reference || asset.path === reference),
)?.name ?? null;
}
interface TranscriptSegmentLike {
start?: number;
end?: number;
text?: string;
speaker?: string | null;
}
interface TranscriptLike {
transcript?: string;
text?: string;
segments?: TranscriptSegmentLike[];
}
export type TranscriptFormat = "readable" | "timestamped";
function isFiniteSecond(value: number | undefined): value is number {
return Number.isFinite(value);
}
interface TranscriptParagraph {
start: number;
speaker: string | null;
text: string;
}
const cleanTranscriptText = (value: string | null | undefined): string =>
value ? value.replace(/\s+/g, " ").trim() : "";
const endsSentence = (value: string): boolean => /[.!?…][\]})"']?$/.test(value);
function friendlySpeaker(value: string | null | undefined): string | null {
const speaker = cleanTranscriptText(value);
if (!speaker) return null;
const machineLabel = speaker.match(/^speaker[_-]+0*(\d+)$/i);
if (machineLabel) return `Speaker ${Number(machineLabel[1]) + 1}`;
return speaker.replace(/_/g, " ");
}
function paragraphsFromPlainText(value: string): TranscriptParagraph[] {
const text = cleanTranscriptText(value);
if (!text) return [];
const sentences = text.split(/(?<=[.!?…])\s+/).filter(Boolean);
const paragraphs: TranscriptParagraph[] = [];
let buffer = "";
for (const sentence of sentences) {
buffer = buffer ? `${buffer} ${sentence}` : sentence;
if (buffer.length >= 420 || sentences.length === 1) {
paragraphs.push({ start: 0, speaker: null, text: buffer });
buffer = "";
}
}
if (buffer) paragraphs.push({ start: 0, speaker: null, text: buffer });
return paragraphs;
}
function transcriptParagraphs(transcript: TranscriptLike | null | undefined): TranscriptParagraph[] {
const segments = Array.isArray(transcript?.segments)
? transcript.segments.filter((segment) => cleanTranscriptText(segment?.text))
: [];
if (!segments.length) {
return paragraphsFromPlainText(transcript?.transcript || transcript?.text || "");
}
const paragraphs: TranscriptParagraph[] = [];
let current: TranscriptParagraph | null = null;
let previousEnd: number | null = null;
const flush = () => {
if (current?.text) paragraphs.push(current);
current = null;
};
for (const segment of segments) {
const text = cleanTranscriptText(segment.text);
const segmentStart: number = isFiniteSecond(segment.start) ? segment.start : previousEnd ?? 0;
const segmentEnd: number = isFiniteSecond(segment.end) ? segment.end : segmentStart;
const speaker = friendlySpeaker(segment.speaker);
const speakerChanged = current !== null && current.speaker !== speaker;
const longPause = current !== null && previousEnd !== null && segmentStart - previousEnd >= 2.5;
if (speakerChanged || longPause) flush();
if (!current) current = { start: segmentStart, speaker, text };
else current.text = `${current.text} ${text}`;
previousEnd = segmentEnd;
if ((current.text.length >= 420 && endsSentence(current.text)) || current.text.length >= 900) {
flush();
}
}
flush();
return paragraphs;
}
/** Produces copy-ready paragraphs from Whisper or imported transcript data. */
export function formatTranscriptText(
transcript: TranscriptLike | null | undefined,
format: TranscriptFormat = "readable",
): string {
return transcriptParagraphs(transcript)
.map((paragraph) => {
const heading = format === "timestamped"
? `[${fmt(paragraph.start)}]${paragraph.speaker ? ` ${paragraph.speaker}` : ""}`
: paragraph.speaker;
return heading ? `${heading}\n${paragraph.text}` : paragraph.text;
})
.join("\n\n");
}
// A render result's clip_index counts the clips submitted to the renderer, which
// for an agent-driven export is not the studio's clip order. The server stamps
// every row with the bounds of the clip it rendered; match a result to a clip on
// those instead of on position.
export const clipBoundsKey = (start?: number, end?: number): string | null =>
start !== undefined && end !== undefined
? `${start.toFixed(2)}:${end.toFixed(2)}`
: null;
export const resultBoundsKey = (row?: ClipResultRow | null): string | null =>
row ? clipBoundsKey(row.source_start_second, row.source_end_second) : null;
interface ClipResultRow {
status?: string;
output_path?: string;
source_start_second?: number;
source_end_second?: number;
}
interface ClipIdentity {
clip_id?: string;
start_second?: number;
end_second?: number;
}
// A suggestion's position shifts whenever an agent deletes or inserts a clip, so
// anything the studio computes per clip is keyed by identity instead. Sessions
// persisted before clips carried a clip_id fall back to their bounds, which also
// makes a re-timed clip drop its stale score.
export const clipKey = (clip: ClipIdentity): string =>
clip.clip_id || clipBoundsKey(clip.start_second, clip.end_second) || "";
type EnergyLevel = "high" | "medium" | "low";
interface EnergyEntry {
score: number;
level: EnergyLevel;
}
interface EnergyMap {
[clipKey: string]: EnergyEntry;
}
const energyLevel = (score: number): EnergyLevel =>
score >= 7 ? "high" : score >= 4 ? "medium" : "low";
/** Maps the backend's positional segment scores onto the clips they were measured for. */
export function buildEnergyMap(
scores: ReadonlyArray<number | null | undefined>,
clips: ClipIdentity[],
): EnergyMap {
const map: EnergyMap = {};
scores.forEach((score, i) => {
const clip = clips[i];
if (!clip || score === null || score === undefined) return;
const key = clipKey(clip);
if (key) map[key] = { score, level: energyLevel(score) };
});
return map;
}
export function dropEnergy(map: EnergyMap, clip: ClipIdentity): EnergyMap {
const key = clipKey(clip);
if (!key || !(key in map)) return map;
const next = { ...map };
delete next[key];
return next;
}
/** Keeps the keyboard cursor on a row that exists after the clip list changes. */
export const clampClipIndex = (idx: number | null, length: number): number | null =>
idx === null || length === 0 ? null : Math.min(idx, length - 1);
/**
* The result for `clip`, or undefined if it has not been rendered. Rows written
* before the server stamped bounds (a restored session) carry no key, so they
* still land by position.
*/
export function findClipResult<T extends ClipResultRow>(
results: (T | undefined)[],
clip: { start_second?: number; end_second?: number },
positionalIdx: number,
): T | undefined {
const key = clipBoundsKey(clip.start_second, clip.end_second);
if (key) {
const keyed = results.find((row) => resultBoundsKey(row) === key);
if (keyed) return keyed;
}
const row = results[positionalIdx];
return row && !resultBoundsKey(row) ? row : undefined;
}
/**
* Body for the combined POST /api/ui-state sync. Transcript rides in this
* same request whenever it changed, rather than a request of its own:
* after silence removal, videoPath and transcript update together in one
* render, and splitting them into separate fetches raced on the server. A
* videoPath-only request landing after the transcript-only one looked
* exactly like a bare set_video (videoPath with no transcript), which
* clears the transcript server-side as if it were stale. One request can't
* race with itself.
*/
export function buildUiStateSyncPayload<S extends object, X>(
syncable: S,
filePath: string,
transcript: X,
transcriptChanged: boolean,
): { _source: "ui"; filePath: string } & S & { transcript?: X } {
return {
_source: "ui",
filePath,
...syncable,
...(transcriptChanged && { transcript }),
};
}