Release: scenes, title cards, transitions, B-roll and padding

README.md

@@ -58,6 +58,22 @@ For podcasts:
   transcript selection; render 9:16 / 1:1 / 16:9 with a positionable crop
   and big word-by-word captions.
 
+Shaping the episode:
+
+- **Scenes** — split at the playhead (**S**) or before any sentence, then
+  name, cut or merge whole scenes. **Suggest scenes** proposes topic
+  changes for review, landed on detected camera cuts; or build scenes
+  from your chapters.
+- **Title cards** — intro, chapter, quote and outro cards between scenes,
+  previewed live and rendered into the export.
+- **Transitions** — dip to black/white, crossfade into a card, and fades
+  in and out of the episode, without shifting anything's timing.
+- **B-roll** — upload images and clips, then cover a transcript selection
+  full screen or picture-in-picture.
+
+Every edit, including bulk ones like "remove all filler words" or applying
+suggested scenes, is a single undo step (**⌘Z** / **⇧⌘Z**).
+
 AI models only ever return text and sentence picks, never timestamps or
 edits: times always come from the transcript's own word timestamps, and
 every response is validated before use. See the

claude.md

@@ -634,6 +634,91 @@ it; `plan.ts` then crops/scales to the clip frame, and captions are
 re-cut into 3-4 word Shorts cues laid out for that frame (the ASS script
 resolution must match the output aspect, or libass stretches glyphs).
 
+## Scenes and title cards
+
+Scenes are derived, never stored: the ranges between `split` operations
+(`lib/timeline/scenes.ts`); a split at exactly 0 only names the first
+scene. New splits snap to the middle of a gap between words.
+
+A `card` operation inserts a full-screen title card (template, title,
+subtitle, 1-10s, solid color) before the content at its source time `at`
+-- a scene start, 0 for an intro, the duration for an outro. Cards add
+time that isn't in the source, so there are three clocks: source, edited
+(cuts removed, `cuts.ts`) and **program** (edited plus cards,
+`lib/timeline/program.ts`, duplicated client/server). Code that already
+works in edited time (captions, chapters, transcript export) shifts into
+program time through `editedToProgramTime`, so cuts and cards compose
+without knowing about each other. A card whose whole scene is cut is
+dropped with it. Clips skip cards.
+
+Rendering: each card is an ffmpeg `color` source at the source's size and
+frame rate, joined with the same xfade chain as cuts; all card text is
+one generated `.ass` file (`lib/cards/ass.ts`) burned in over the program
+before captions and the logo. User text only ever reaches ffmpeg inside
+that file, and the API refuses braces, backslashes and control
+characters. The preview can't insert frames into a `<video>`, so
+`useCardPlayback.ts` pauses the video where a card plays, shows
+`CardPreview` (same layout percentages, `lib/cards/layout.ts`) on its own
+clock, then resumes.
+
+A `transition` operation styles the join into the scene starting at its
+`at` (both joins around that scene's card, if it has one): dip to black,
+dip to white, or crossfade (only with a card -- between two stretches of
+footage that follow each other in the source it shows nothing, so it
+falls back to a cut). At 0 it fades the episode in, at the end it fades
+it out. **Transitions never change the program's length**, so captions
+and chapters need no adjusting: a dip fades each side's own edge
+(`fade`/`afade`, audio capped at 0.3s next to speech) and keeps the
+usual join, and a crossfade's overlap is added to the card's rendered
+length (`plan.ts#layoutProgram`). The preview draws them with
+`TransitionOverlay` from the pure `transition-look.ts`, on its own
+animation-frame loop; audio fades aren't previewed.
+
+**Scene padding**: a `pad` operation (`at` = a scene start, `size`
+2-25% per side, `color` '#RRGGBB') shrinks that scene's footage and
+centres it on a solid border; the output size never changes. Scenes are
+matched and the latest pad wins like transitions
+(`program.ts#placePads`); a padded scene's edges become ordinary cut
+joins in the program, so its length doesn't change either. Rendered per
+segment after the grade (`plan.ts#buildPadFilter`: scale, then `pad`
+back to the source size, so xfade inputs still match); card, B-roll,
+caption and logo layers are unaffected, and clips skip it. Merging a
+scene removes its padding. The preview (`PaddingLayer`) scales the
+`<video>` over the border color on its own animation-frame loop.
+
+In the transcript, clicking a word sets a cursor before it and `/`
+starts a new scene there (`useEditorShortcuts`, via `gapBefore` +
+`splitAt`); with no cursor `/` splits at the playhead like `S`.
+
+**Scene suggestions** are explicit buttons that only ever propose:
+"Suggest scenes" (gpt-4o-mini, sentence indices and titles only --
+`lib/ai/scenes.ts`, validated by `lib/scenes/suggest.ts`: whole
+sentences, the first scene at 0, at least 45s apart, boundaries in the
+silence before a sentence) and "From chapters" (client-side, no AI).
+Shot-change detection (`lib/ffmpeg/shots.ts`, a `shots` TranscriptionJob
+storing its times in `resultJson`) scores frames at 320px wide; a
+suggestion within 1.5s of a cut -- and not inside a word -- moves onto
+it. The user reviews the list and Apply adds the kept splits (and
+optional numbered chapter cards) as one undo step, renaming a split
+already within 1s instead of adding a sliver.
+
+**B-roll**: `media` assets (many per project, stored under a unique
+prefix, with name/size/length columns) placed by `overlay` operations:
+an asset shown from `start` to `end` in source time (so it follows cuts),
+full screen (scaled to fill, cropped) or picture-in-picture (32% wide,
+4% inset, a chosen corner). Placed on program time like captions
+(`program.ts#placeOverlays`), composited as extra ffmpeg inputs after the
+join and grade, before any clip reframe, card text, captions and logo --
+an image looped for its slot, a video trimmed from its offset holding its
+last frame. B-roll audio is never used. It plays in clips too.
+
+**ffmpeg 9 xfade gotchas** (`plan.ts`, measured on 9.0.2): every segment
+must be pinned to the source's frame rate with `fps=` (without it xfade
+drops the start of each later segment), must not get a `settb` after
+that (brings the bug back), and every segment but the last is padded
+with `tpad` clone frames (a segment a frame short of its computed length
+otherwise ends the whole chain at that join).
+
 ---
 
 # 13. Architecture (local-first)
@@ -901,6 +986,14 @@ GET    /api/projects/:id/clips
 POST   /api/projects/:id/clips/highlights        (GPT-5.6 Luna picks; replaces earlier AI picks)
 POST   /api/projects/:id/clips                   PATCH/DELETE /api/projects/:id/clips/:clipId
 (render a clip: POST /api/projects/:id/render with {clipId})
+
+GET    /api/projects/:id/media                    (media library: images and clips for B-roll)
+POST   /api/projects/:id/media?filename=          (raw body, image/png|jpeg|webp or video/*; probed, refused if unreadable)
+GET    /api/projects/:id/media/:assetId/file      DELETE /api/projects/:id/media/:assetId (409 while B-roll uses it)
+
+POST   /api/projects/:id/scenes/shots            (202 + jobId; background shot-change detection)
+GET    /api/projects/:id/scenes/shots            (latest detection)   GET /api/projects/:id/scenes/shots/:jobId
+POST   /api/projects/:id/scenes/suggest          (gpt-4o-mini scene suggestions for review; never applied server-side)
 ```
 
 (No `POST /api/projects/:id/ai/edit` — the free-text AI command bar this

client/src/components/editor/AiToolsPanel.tsx

@@ -19,7 +19,7 @@ export function AiToolsPanel() {
   const setSilenceGaps = useTranscriptStore((s) => s.setSilenceGaps);
 
   const projectId = useProjectStore((s) => s.id);
-  const addCut = useTimelineStore((s) => s.addCut);
+  const addCuts = useTimelineStore((s) => s.addCuts);
 
   const allWords = useMemo(
     () => transcript?.segments.flatMap((seg) => seg.words) ?? [],
@@ -43,11 +43,11 @@ export function AiToolsPanel() {
 
   const handleRemoveFillerWords = () => {
     const fillerWordIdSet = new Set(fillerWordIds);
-    for (const word of allWords) {
-      if (fillerWordIdSet.has(word.id)) {
-        addCut(padCutStart(word.start, allWords), word.end, "filler word");
-      }
-    }
+    addCuts(
+      allWords
+        .filter((word) => fillerWordIdSet.has(word.id))
+        .map((word) => ({ start: padCutStart(word.start, allWords), end: word.end, reason: "filler word" }))
+    );
     setFillerWordIds([]);
   };
 
@@ -58,9 +58,7 @@ export function AiToolsPanel() {
 
   const handleRemoveSilences = () => {
     if (!silenceGaps) return;
-    for (const gap of silenceGaps) {
-      addCut(gap.start, gap.end, "long pause");
-    }
+    addCuts(silenceGaps.map((gap) => ({ start: gap.start, end: gap.end, reason: "long pause" })));
     setSilenceGaps(null);
   };
 

client/src/components/editor/CardEditor.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { usePlayerStore } from "@/stores/player-store";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { CARD_BACKGROUNDS } from "@/lib/cards/layout";
+import {
+  CARD_MAX_SECONDS,
+  CARD_MIN_SECONDS,
+  CARD_SUBTITLE_MAX,
+  CARD_TEMPLATES,
+  CARD_TITLE_MAX,
+  type CardOperation,
+  type CardTemplate,
+} from "@/types/edit-operation";
+
+const TEMPLATE_LABELS: Record<CardTemplate, string> = {
+  title: "Title",
+  chapter: "Chapter",
+  quote: "Quote",
+  outro: "Outro",
+};
+
+const SUBTITLE_PLACEHOLDER: Record<CardTemplate, string> = {
+  title: "Subtitle (optional)",
+  chapter: "Label above, e.g. Part 2",
+  quote: "Who said it (optional)",
+  outro: "e.g. Subscribe for more",
+};
+
+/** Card text goes into an ASS file at export: no override-tag characters or line breaks (the API refuses them too). */
+function cleanCardText(text: string): string {
+  return Array.from(text)
+    .filter((ch) => {
+      const code = ch.charCodeAt(0);
+      return code >= 0x20 && code !== 0x7f && !"{}\\".includes(ch);
+    })
+    .join("");
+}
+
+/**
+ * Edits one title card. Changes stay in a local draft, previewed live over
+ * the player (player store's cardDraft), and are saved as a single
+ * operation replacement -- one undo step -- when the editor is closed.
+ */
+export function CardEditor({
+  card,
+  onSave,
+  onDelete,
+  onClose,
+}: {
+  card: CardOperation;
+  onSave: (next: CardOperation) => void;
+  onDelete: () => void;
+  onClose: () => void;
+}) {
+  const [draft, setDraft] = useState(card);
+  const setCardDraft = usePlayerStore((s) => s.setCardDraft);
+
+  useEffect(() => {
+    setCardDraft(draft);
+  }, [draft, setCardDraft]);
+  useEffect(() => () => setCardDraft(null), [setCardDraft]);
+
+  const update = (patch: Partial<CardOperation>) => setDraft((d) => ({ ...d, ...patch }));
+  const title = draft.title.trim();
+  const changed = JSON.stringify(draft) !== JSON.stringify(card);
+
+  const done = () => {
+    if (changed && title) {
+      const subtitle = draft.subtitle?.trim();
+      onSave({ ...draft, title, subtitle: subtitle || undefined });
+    }
+    onClose();
+  };
+
+  return (
+    <div className="flex flex-col gap-2.5 rounded-md border border-border bg-muted/40 p-2.5">
+      <div className="grid grid-cols-4 gap-1">
+        {CARD_TEMPLATES.map((template) => (
+          <button
+            key={template}
+            type="button"
+            onClick={() => update({ template })}
+            className={`rounded border px-1 py-1 text-[0.7rem] ${
+              draft.template === template
+                ? "border-primary bg-primary/15 text-primary"
+                : "border-border text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {TEMPLATE_LABELS[template]}
+          </button>
+        ))}
+      </div>
+      <Input
+        autoFocus
+        value={draft.title}
+        maxLength={CARD_TITLE_MAX}
+        placeholder="Title"
+        aria-label="Card title"
+        onChange={(e) => update({ title: cleanCardText(e.target.value) })}
+        onKeyDown={(e) => e.key === "Enter" && done()}
+        className="h-8 text-xs"
+      />
+      <Input
+        value={draft.subtitle ?? ""}
+        maxLength={CARD_SUBTITLE_MAX}
+        placeholder={SUBTITLE_PLACEHOLDER[draft.template]}
+        aria-label="Card subtitle"
+        onChange={(e) => update({ subtitle: cleanCardText(e.target.value) })}
+        onKeyDown={(e) => e.key === "Enter" && done()}
+        className="h-8 text-xs"
+      />
+      <label className="flex items-center gap-2 text-muted-foreground">
+        <span className="w-14 shrink-0">Duration</span>
+        <input
+          type="range"
+          min={CARD_MIN_SECONDS}
+          max={CARD_MAX_SECONDS}
+          step={0.5}
+          value={draft.duration}
+          onChange={(e) => update({ duration: Number(e.target.value) })}
+          className="min-w-0 flex-1 accent-primary"
+        />
+        <span className="w-8 text-right font-mono tabular-nums">{draft.duration}s</span>
+      </label>
+      <div className="flex items-center gap-1.5">
+        <span className="w-14 shrink-0 text-muted-foreground">Color</span>
+        {CARD_BACKGROUNDS.map((color) => (
+          <button
+            key={color}
+            type="button"
+            onClick={() => update({ background: color })}
+            title={color}
+            className={`size-5 rounded-full border ${
+              draft.background.toUpperCase() === color ? "ring-2 ring-primary ring-offset-1 ring-offset-card" : "border-border"
+            }`}
+            style={{ backgroundColor: color }}
+          />
+        ))}
+        <input
+          type="color"
+          value={draft.background}
+          onChange={(e) => update({ background: e.target.value.toUpperCase() })}
+          aria-label="Custom card color"
+          className="size-5 cursor-pointer rounded-full border border-border bg-transparent p-0"
+        />
+      </div>
+      <div className="flex justify-between">
+        <Button variant="ghost" size="xs" className="text-destructive hover:text-destructive" onClick={onDelete}>
+          Delete card
+        </Button>
+        <Button size="xs" onClick={done} disabled={!title}>
+          Done
+        </Button>
+      </div>
+    </div>
+  );
+}

client/src/components/editor/EditorHydrator.tsx

@@ -5,6 +5,7 @@ import { useProjectStore } from "@/stores/project-store";
 import { useTranscriptStore } from "@/stores/transcript-store";
 import { useTimelineStore } from "@/stores/timeline-store";
 import { useCaptionStyleStore } from "@/stores/caption-style-store";
+import { useMediaStore } from "@/stores/media-store";
 import { EditorLayout } from "@/components/editor/EditorLayout";
 import type { Transcript } from "@/types/transcript";
 import type { EditOperation } from "@/types/edit-operation";
@@ -44,12 +45,14 @@ export function EditorHydrator({
   const setTranscript = useTranscriptStore((s) => s.setTranscript);
   const hydrateTimeline = useTimelineStore((s) => s.hydrate);
   const hydrateCaptionStyle = useCaptionStyleStore((s) => s.hydrate);
+  const loadMedia = useMediaStore((s) => s.load);
 
   useEffect(() => {
     hydrateProject(project);
     setTranscript(transcript);
     hydrateTimeline(project.id, operations);
     hydrateCaptionStyle(project.id, project.burnInCaptions, project.captionStyle);
+    void loadMedia(project.id);
     // Only re-hydrate when navigating to a different project.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [project.id]);

client/src/components/editor/EditorLayout.tsx

@@ -10,6 +10,7 @@ import { ExportButton } from "@/components/editor/ExportButton";
 import { ProjectNameField } from "@/components/editor/ProjectNameField";
 import { GithubLink } from "@/components/GithubLink";
 import { usePlayerStore } from "@/stores/player-store";
+import { useEditorShortcuts } from "@/components/editor/useEditorShortcuts";
 
 export function EditorLayout({ videoUrl }: { videoUrl: string }) {
   // Matches the preview's aspect box to the source video's own aspect ratio
@@ -18,6 +19,7 @@ export function EditorLayout({ videoUrl }: { videoUrl: string }) {
   // editor for non-16:9 video that the actual ffmpeg export never had,
   // since export doesn't touch aspect ratio at all.
   const aspectRatio = usePlayerStore((s) => s.aspectRatio);
+  useEditorShortcuts();
 
   return (
     <div className="flex h-screen flex-col gap-3 p-3">