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 { Block, Gap, Layout } from "./scene";
import type { Motion } from "./motion";
interface CardBase {
/** Seconds on the clip's own clock. */
start: number;
end: number;
accent?: string;
background?: string;
motion?: Motion;
/**
* Whether the speaker stays on screen above the card.
*
* Drawn unless a card says null. A podcast card that drops the person is the
* news-explainer reflex this format is not: the moment is somebody saying
* something, and cutting their face out mid-sentence throws away the only
* thing the clip has.
*
* Null is for the card that earns the whole frame, like a screenshot nobody
* could read at half the height.
*/
speaker?: null;
/**
* Whether the card is a surface laid over the shot or ink written on it.
*
* "panel" is the default and the safe one: an opaque band, legible over any
* footage because none of it shows through. "over" keeps the whole shot and
* writes into it, which is what an interview channel does when the frame
* has room to spare. It costs the guarantee: a card written over a bright
* kitchen needs the scrim to do work a panel did for free, so it is a
* choice somebody makes about a shot rather than a default.
*/
place?: "panel" | "over";
}
/**
* What a card can say.
*
* Four kinds rather than a free-form layout, because a card is only worth
* taking the frame for when it says something the talking head cannot: a
* number, a claim, a list, or the sentence itself set large enough to read
* at arm's length. Anything past that is a slide deck.
*/
export type Card =
| (CardBase & {
kind: "stat";
/** The number, and only the number. */
value: string;
eyebrow?: string;
caption?: string;
})
| (CardBase & {
kind: "headline";
eyebrow?: string;
lead: string;
/**
* The payload words, set apart from the lead.
*
* Coloured where they stand when they are in the lead, appended when
* they are not. See the text block for why both.
*/
emphasis?: string | string[];
sub?: string;
})
| (CardBase & { kind: "bullets"; eyebrow?: string; items: string[] })
/**
* Two or three things measured against each other.
*
* Emphasis rather than a colour per bar: the story is that one of them is
* the point, and giving every bar its own hue buries the one that is. The
* subject wears the accent, the rest are context.
*/
| (CardBase & {
kind: "compare";
eyebrow?: string;
rows: { label: string; value: number; display?: string; subject?: boolean }[];
})
/** One thing, before and after. A dumbbell, in two steps of one hue. */
| (CardBase & {
kind: "change";
eyebrow?: string;
label?: string;
from: { value: string; note?: string };
to: { value: string; note?: string };
})
/** One ratio against its whole. A meter, never a two-slice pie. */
| (CardBase & {
kind: "share";
eyebrow?: string;
/** 0 to 1. */
value: number;
display?: string;
caption?: string;
})
/** A name nobody in the audience necessarily knows, with its mark. */
| (CardBase & {
kind: "entity";
eyebrow?: string;
name: string;
note?: string;
/** Logo or photograph. A URL the renderer can reach, or a bundle path. */
src?: string;
})
| (CardBase & { kind: "quote"; text: string; attribution?: string })
/**
* Blocks, arranged. The kind that is not a kind.
*
* Everything above is a layout somebody drew once and named. This is the
* same atoms with the arrangement left open, so a moment that does not
* happen to be a figure or a list still gets a card built for it rather
* than the nearest preset with the wrong shape.
*/
| (CardBase & {
kind: "scene";
layout?: Layout;
gap?: Gap;
blocks: Block[];
})
| (CardBase & {
kind: "image";
/** A URL the renderer can reach, or a path inside the bundle. */
src: string;
/**
* "fit" shows the whole picture, which is what a screenshot needs: a
* cropped headline is not evidence of anything. "fill" covers the frame
* and is for a photograph, where the edges carry nothing.
*/
fit?: "fit" | "fill";
/**
* Whether the file takes the whole frame rather than a band of it.
*
* Only ever honoured once the card has given up the speaker, because a
* cutaway that leaves the person on screen is a smaller picture with
* extra steps. A band too short to read falls back to this on its own:
* a letterbox slit of a photograph says nothing while still costing the
* frame it sits in.
*/
bleed?: boolean;
caption?: string;
})
/**
* Footage in the band under the speaker.
*
* The split every phone already knows: the person talking above, the thing
* they are talking about below. It is the one card that shows rather than
* states, which is why it earns the frame where a slide would not.
*
* Silent, always, and not negotiable. The moment is somebody speaking, and
* a second soundtrack under them is what makes a clip unwatchable rather
* than merely busy.
*
* Footage shorter than the card's own window runs out inside it: there is
* no looping here, because the only component that can seek frame-perfectly
* during a render cannot loop, and a preview that loops where the render
* does not is a preview that lies. The window is the agreement.
*/
| (CardBase & {
kind: "video";
/** A URL the renderer can reach, or a path inside the bundle. */
src: string;
/**
* "fill" crops to the band, which is what footage wants. "fit" shows
* the whole frame for a screen recording, where the edges are content.
*/
fit?: "fit" | "fill";
/** Where in the file to start, in seconds. */
startAt?: number;
/** The whole frame rather than the band. See the image card. */
bleed?: boolean;
caption?: string;
});
/**
* The card in front at this moment, or none.
*
* A later card wins an overlap rather than the array order deciding it,
* because the planner writes cards in the order they were found and two
* windows that touch would otherwise flicker between them frame by frame.
* The window is half-open so a card ending where the next begins is a cut,
* not a frame showing both.
*/
export const cardAt = (cards: Card[], seconds: number): Card | null => {
let found: Card | null = null;
for (const card of cards) {
if (seconds >= card.start && seconds < card.end) {
if (!found || card.start >= found.start) found = card;
}
}
return found;
};