Transcript-to-Chapters Pipeline

Turns a timestamped transcript into chapter markers that actually render.

THE SILENT FAILURE. YouTube enforces its chapter rules by IGNORING your chapters, not by rejecting them. First chapter must start at 00:00, there must be at least three, each at least 10 seconds. Break any one and YouTube simply renders nothing — no error, no warning. The creator sees timestamps sitting in their description and assumes it worked. Naive splitters break all three constantly: they start at the first detected topic rather than zero, emit two chapters for a short video, and emit sub-10-second chapters around quick topic changes.

When the input CANNOT satisfy the rules — too short, too few topics — this REFUSES with a reason rather than emitting markers that will silently not render. Segments below the minimum are merged into their neighbour rather than dropped. Timestamps over an hour switch to HH:MM:SS correctly, which is a classic off-by-one that produces markers the platform ignores.

Title generation is caller-injected with a deterministic offline fallback, so tests need no API key.

VERIFIED: 64 tests, 10 deliberate defects applied to the real source, 8 caught and 2 proved to change no observable behaviour (a defensive assertion that only fires if the merge itself is buggy, and a guard the duration gate above it already makes unreachable) — the proofs ship in mutations.json. Every mutation was observed FAILING before the source was restored — a test never seen to fail is a decoration.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function buildChapters( segments: TranscriptSegment[], options: BuildChaptersOptions = {}, ): BuildChaptersResult;
  export function toYouTubeDescription(chapters: Chapter[]): string;
  export function formatTimestamp(totalSeconds: number): string;
  export function validateSegments(segments: TranscriptSegment[]): void;

  export type TitleFn = (span: { start: number;
  export type RefusalCode = "video_too_short" | "too_few_topics_after_merge";
  export type BuildChaptersResult = | { ok: true;