Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

9.2 KB
Raw Blame
export interface Word {
  word: string;
  start: number;
  end: number;
  confidence?: number;
  speaker?: string;
  /**
   * Worth reading even by somebody scrolling past with the sound off: a
   * number, a name, the word the sentence was built to land on.
   *
   * It rides on the word rather than arriving as a list of indices, because
   * every caption style chunks and splits the array before drawing it and an
   * index into the original would be wrong by then.
   */
  emphasis?: boolean;
}

export interface CaptionStyle {
  name: "hormozi" | "karaoke" | "subtle" | "branded" | "outline";
  fontSize: number;
  fontFamily: string;
  color: string;
  activeColor: string;
  /**
   * What an emphasised word is coloured. Falls back to activeColor, so a
   * style that never sets one still marks emphasis rather than dropping it.
   */
  emphasisColor?: string;
  uppercase: boolean;
  wordsPerChunk: number;
  marginBottom: number;
  /**
   * What a pill behind the words is filled with.
   *
   * Black until a show says otherwise, because a caption is read over footage
   * and black is the one fill that works over all of it. A show that has told
   * us what its text sits on gets that instead, so the pill over a card is the
   * card rather than a hole cut in it.
   */
  background?: string;
  /**
   * What the words are outlined in, when they are outlined rather than boxed.
   *
   * A pill guarantees legibility by covering the shot. An outline guarantees
   * it by making every letter carry its own contrast, which leaves the frame
   * whole. Drawn behind the fill, so a heavy stroke thickens the letter rather
   * than eating it.
   */
  stroke?: string;
}

export type CaptionPosition = "auto" | "upper" | "center" | "lower";

export type LogoPosition =
  | "top-left"
  | "top-center"
  | "top-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

/**
 * The logo's box, in unscaled units.
 *
 * Watermark draws it and the branded captions keep clear of it, and those are
 * two files. Shared here so a logo that moves cannot leave the caption margin
 * guarding the place it used to be.
 */
export const LOGO_INSET = 180;
export const LOGO_EDGE = 108;
export const LOGO_WIDTH = 255;
export const LOGO_HEIGHT = 126;
export const LOGO_CAPTION_GAP = 24;

/**
 * The part of the frame the app it plays in has already spent.
 *
 * A vertical clip is never watched on its own. YouTube draws a title, a handle
 * and a link chip across the bottom of it, an action rail up the right, and a
 * progress bar under both. TikTok and Reels draw the same furniture in the
 * same two places. None of it is ours and all of it is opaque, so anything we
 * put there is not a card that came out badly, it is a card nobody ever saw.
 *
 * Measured off a Shorts screenshot rather than guessed. On a 9:19.5 phone a
 * viewer's chrome starts 1498 down a 1920 frame and the rail runs from x 817
 * to the edge. The bottom leaves 38 clear of that line, which is as low as
 * the words go before the app starts eating them.
 */
export const SAFE = {
  top: 200,
  bottom: 460,
  left: 120,
  right: 280,
} as const;

/**
 * The same reservation for a frame nobody scrolls past.
 *
 * A landscape clip plays in a player, not in a feed. There is no handle, no
 * title and no action rail drawn over it; there is a scrubber that appears on
 * hover and the edges of a screen it might be letterboxed on. Reserving the
 * phone's 460 here would spend a quarter of the frame guarding against
 * furniture that is not there.
 */
export const SAFE_WIDE = {
  top: 90,
  bottom: 150,
  left: 120,
  right: 120,
} as const;

/**
 * Which reservation this frame is owed, read off its own shape.
 *
 * Portrait is the feed and gets the full chrome. Anything square or wider is
 * a player and gets the margin a broadcast would use. The composition knows
 * its size, so nothing has to be told which platform it is for.
 */
export const safeFor = (width: number, height: number) =>
  (width < height ? SAFE : SAFE_WIDE);

/**
 * How much of the width a phone throws away.
 *
 * A 9:16 file on a 9:19.5 screen is filled to the height and cropped at the
 * sides, so the outer ninth of the frame is off-screen before any chrome is
 * drawn. `SAFE.left` and `SAFE.right` already cover it; this is the number
 * they were derived from, kept so the derivation is checkable.
 */
export const DEVICE_SIDE_CROP = 96;

export interface CaptionProps {
  words: Word[];
  style: CaptionStyle;
  fps: number;
  durationInFrames: number;
  videoSrc: string;
  logoSrc?: string;
  faceY?: number | null; // normalized 0-1 (0=top, 1=bottom)
}

/**
 * The caption stack, in falling-back order.
 *
 * DM Sans draws Latin and nothing else, so the Noto families behind it are
 * what a Georgian or Russian show is actually rendered in. The browser picks
 * per glyph, so a Latin clip never leaves DM Sans.
 */
export const FONT = "'DM Sans', 'Noto Sans', 'Noto Sans Georgian', sans-serif";

/** A show's own font, ahead of the stack that covers what it cannot draw. */
export const fontStack = (family?: string | null): string =>
  family ? `'${family.replace(/'/g, "")}', ${FONT}` : FONT;

// Caption geometry (font sizes, margins, insets) is authored for a 1920-tall
// vertical canvas. Multiply pixel values by this factor so a shorter canvas
// (16:9 = 1080 tall, 1:1 = 1080 tall) gets a proportional lower-third instead
// of vertical-tuned captions floating mid-frame. Vertical → factor 1.0.
export const REFERENCE_HEIGHT = 1920;
export const captionScale = (height: number): number => height / REFERENCE_HEIGHT;

/**
 * How many lines of caption everything else gets out of the way of.
 *
 * Reserving for the tallest caption costs a card some height on every clip
 * and costs it nothing on the clip where it matters.
 */
export const CAPTION_LINES = 3;

/**
 * The band the captions own, in reference units.
 *
 * Read off the style rather than fixed, because a style's size and margin are
 * the only things that decide it. Lives here because four things need to
 * clear it: the card, the name card, the logo and the chip, and a number
 * copied into four files is a number that drifts in three of them.
 */
export const captionZone = (style: CaptionStyle) =>
  style.marginBottom + style.fontSize * CAPTION_LINES * 1.2 + 36;

export const STYLES = {
  hormozi: {
    name: "hormozi",
    fontSize: 90,
    fontFamily: FONT,
    color: "#FFFFFF",
    activeColor: "#FFFF00",
    emphasisColor: "#3B9CFF",
    uppercase: true,
    wordsPerChunk: 3,
    marginBottom: 400,
  },
  karaoke: {
    name: "karaoke",
    fontSize: 80,
    fontFamily: FONT,
    color: "rgba(255,255,255,0.4)",
    activeColor: "#FFFFFF",
    emphasisColor: "#3B9CFF",
    uppercase: false,
    wordsPerChunk: 5,
    marginBottom: 400,
  },
  subtle: {
    name: "subtle",
    fontSize: 64,
    fontFamily: FONT,
    color: "#FFFFFF",
    activeColor: "#FFFFFF",
    emphasisColor: "#7FD1FF",
    uppercase: false,
    wordsPerChunk: 6,
    marginBottom: 200,
  },
  branded: {
    name: "branded",
    fontSize: 100,
    fontFamily: FONT,
    color: "#FFFFFF",
    activeColor: "#FFFFFF",
    emphasisColor: "#3B9CFF",
    uppercase: false,
    wordsPerChunk: 3,
    marginBottom: 420,
  },
  /**
   * A whole sentence at a time, outlined, over an uncovered frame.
   *
   * The one every serious interview channel converges on, because it is the
   * only caption that stays readable without taking anything from the shot.
   * More words per chunk than the rest: the point is a line somebody reads,
   * not a word that lands.
   */
  outline: {
    name: "outline",
    fontSize: 96,
    fontFamily: FONT,
    color: "#FFFFFF",
    activeColor: "#FFFFFF",
    emphasisColor: "#3B9CFF",
    stroke: "#000000",
    uppercase: false,
    wordsPerChunk: 7,
    marginBottom: 460,
  },
} satisfies Record<string, CaptionStyle>;

export const styleNamed = (name: string): CaptionStyle | undefined =>
  new Map<string, CaptionStyle>(Object.entries(STYLES)).get(name);

/**
 * The caption styles, in the show's own colours.
 *
 * A style ships with a palette because it has to look like something before
 * anybody has picked anything. Left at that, every clip carried two accents:
 * the show's on the card and the style's in the captions, a yellow sweep under
 * a green figure, and a colour that means two things means neither.
 *
 * Each style keeps its character and loses its palette. Hormozi is the loud
 * one, so the word being spoken takes the accent; the quieter three set the
 * spoken word in ink and spend the accent only on a word worth reading with
 * the sound off. The pill becomes the show's surface, which is what makes a
 * caption over a card read as part of it.
 */
export const brandCaptions = (
  style: CaptionStyle,
  brand?: { accent: string; ink: string; surface: string } | null,
): CaptionStyle => {
  if (!brand) return style;

  return {
    ...style,
    color: style.name === "karaoke"
      ? `color-mix(in oklab, ${brand.ink} 40%, transparent)`
      : brand.ink,
    activeColor: style.name === "hormozi" ? brand.accent : brand.ink,
    emphasisColor: brand.accent,
    background: `color-mix(in oklab, ${brand.surface} 85%, transparent)`,
    // Opaque, unlike the pill: a stroke at 85% is a grey halo, not an edge.
    ...(style.stroke && { stroke: brand.surface }),
  };
};