Skip to content

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

6.7 KB
Raw Blame
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;
};