Skip to content

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

7.0 KB
Raw Blame
export function maxClipSeconds(format?: string): number {
  return format === "horizontal" ? 300 : 180;
}

/** A range bound as it arrives from a request or tool call, before it is checked. */
export type RangeBound = number | string | null | undefined;

function isFiniteBound(value: RangeBound): value is number {
  return Number.isFinite(value);
}

/** Returns an error message, or null when the range is renderable. */
export function validateClipRange(
  start: RangeBound,
  end: RangeBound,
  format?: string,
): string | null {
  if (!isFiniteBound(start) || !isFiniteBound(end)) {
    return "start_second and end_second must be numbers";
  }

  if (start < 0) return "start_second must be >= 0";

  if (end <= start) return "end_second must be greater than start_second";
  const maxDur = maxClipSeconds(format);

  if (end - start > maxDur) {
    return `Clip too long (${Math.round(end - start)}s). Max ${maxDur} seconds.`;
  }

  return null;
}

// Suggestions aren't bound to a format yet, so allow up to the longest
// renderable duration plus trim headroom.
const MAX_SUGGESTION_SECONDS = 600;

export function validateSuggestionRange(start: RangeBound, end: RangeBound): string | null {
  if (!isFiniteBound(start) || !isFiniteBound(end)) {
    return "start_second and end_second must be numbers";
  }

  if (start < 0) return "start_second must be >= 0";

  if (end <= start) return "end_second must be greater than start_second";

  if (end - start > MAX_SUGGESTION_SECONDS) {
    return `Suggested range too long (${Math.round(end - start)}s). Max ${MAX_SUGGESTION_SECONDS} seconds.`;
  }

  return null;
}

// ---------------------------------------------------------------------------
// Context checks: does this clip make sense to someone who never heard the
// episode? A moment can be perfectly cut and still be unwatchable because it
// opens on an answer whose question stayed behind the cut.
// ---------------------------------------------------------------------------

const MIN_PAYOFF_WORDS = 5;

// Japanese and Chinese do not space-delimit, so every payoff in them counts as
// one "word" however long it runs. A character floor stands in there.
const MIN_PAYOFF_CHARS = 12;

/** Values that mean "the viewer needs to know nothing going in". */
const SELF_CONTAINED = new Set([
  "",
  "-",
  "n/a",
  "na",
  "none",
  "no context",
  "no context needed",
  "nothing",
  "nothing needed",
]);

/**
 * First words that point backwards at something said before the cut. This is a
 * backstop, not the primary gate: the model declares `standalone` itself, and
 * this list only catches the case where it declared "nothing" but cut into the
 * middle of an exchange anyway.
 */
const ORPHAN_OPENERS = new Set([
  "absolutely", "also", "and", "anyway", "because", "but", "cause", "exactly",
  "he", "her", "his", "however", "instead", "it", "meanwhile", "no", "nope",
  "ok", "okay", "otherwise", "plus", "right", "she", "sure", "that", "their",
  "them", "they", "those", "though", "totally", "well", "which", "yeah", "yep",
  "yes",
]);

/**
 * "so" is the one opener that swings both ways. "So actually, did you try that"
 * and "So if you look at the numbers" start a thought; "So that's why we quit"
 * points back. Flag it only when the word after it is itself backward-pointing,
 * rather than rejecting every clip that opens on a speaker gathering themselves.
 */
const SO_POINTS_BACK = new Set([
  "he", "his", "it", "its", "she", "that", "their", "them", "they", "this",
  "those", "we",
]);

/**
 * Two-word starts that read as self-contained despite a flagged first word,
 * e.g. "So many founders quit" or "It takes ten years".
 */
const SELF_CONTAINED_STARTS = new Set([
  "it costs", "it takes", "it turns", "no idea", "no matter", "no one",
]);

/** Lowercase, punctuation-stripped, single-spaced. Unicode-aware: a Georgian
 * or Japanese payoff has to survive this, not normalize down to nothing. */
function normalize(text: string): string {
  return text
    .toLowerCase()
    .replace(/[^\p{L}\p{N}'\s]/gu, " ")
    .replace(/\s+/gu, " ")
    .trim();
}

function wordCount(text: string): number {
  const n = normalize(text);

  return n ? n.split(" ").length : 0;
}

function isTooThin(payoff: string): boolean {
  const normalized = normalize(payoff);

  return normalized.includes(" ")
    ? wordCount(payoff) < MIN_PAYOFF_WORDS
    : normalized.length < MIN_PAYOFF_CHARS;
}

export function isSelfContained(standalone: string): boolean {
  return SELF_CONTAINED.has(normalize(standalone));
}

/** Returns the backward-pointing opener, or null when the clip starts clean. */
export function findOrphanOpener(previewText: string | null | undefined): string | null {
  if (!previewText) return null;
  const words = normalize(previewText).split(" ").filter(Boolean);

  if (!words.length) return null;

  if (SELF_CONTAINED_STARTS.has(words.slice(0, 2).join(" "))) return null;

  // "I mean" is only a stall when the sentence leads with it.
  if (words[0] === "i" && words[1] === "mean") return "i mean";

  if (words[0] === "so") {
    // "that's" and "they're" have to match "that" and "they".
    const next = (words[1] ?? "").replace(/'(s|d|ll|re|ve)$/, "");

    return SO_POINTS_BACK.has(next) ? `so ${next}` : null;
  }

  return ORPHAN_OPENERS.has(words[0]) ? words[0] : null;
}

export interface SuggestionContext {
  title?: string | null;
  payoff?: string | null;
  standalone?: string | null;
  context_line?: string | null;
  preview_text?: string | null;
}

/** Returns an error message, or null when the clip carries its own context. */
export function validateSuggestionContext(s: SuggestionContext): string | null {
  const payoff = s.payoff?.trim() ?? "";

  if (!payoff) {
    return "payoff is required: one sentence, second person, on what the viewer walks away with.";
  }

  if (isTooThin(payoff)) {
    return `payoff is too thin ("${payoff}"). Write a full sentence on what the viewer walks away with.`;
  }

  if (s.title && normalize(s.title) === normalize(payoff)) {
    return "payoff just restates the title. Say what the viewer gets, not what the clip is called.";
  }

  const standalone = s.standalone?.trim() ?? "";

  if (!standalone) {
    return 'standalone is required: what the viewer must already know to follow this clip, or "nothing".';
  }

  // context_line is not consulted here on purpose. Nothing burns it into the
  // video yet, so treating it as coverage would pass clips whose viewer still
  // has no setup, which is the exact failure these checks exist to catch. It
  // stays on the suggestion as editor metadata until the renderer draws it.
  if (!isSelfContained(standalone)) {
    return (
      `standalone says the viewer needs to know "${standalone}". Move start_second back ` +
      "so the clip itself contains that setup on camera. A context_line does not cover it: " +
      "nothing renders it yet."
    );
  }

  const orphan = findOrphanOpener(s.preview_text);

  if (orphan) {
    return (
      `preview_text opens on "${orphan}", which points at something said before the cut. ` +
      "Move start_second back so the question is inside the clip."
    );
  }

  return null;
}