@lalalic/markcut 2.2.9 → 2.4.0

package/AGENTS.md

@@ -39,7 +39,7 @@ See [docs/markdown-strict-descriptive.md](docs/markdown-strict-descriptive.md) f
 | `folder` | Internal container (series/parallel) |
 | `image` | Still photo with fit mode |
 | `video` | Video clip with startFrom/endAt trimming, playbackRate |
-| `audio` | Soundtrack/SFX with foreground ducking, loop |
+| `audio` | Soundtrack/SFX with foreground ducking |
 | `component` | External React component by componentName + props |
 | `effect` | CSS keyframe animation wrapper (fadeIn, zoomIn, bounceIn, etc.) |
 | `include` | Embed external video JSON (file, URL, or data URI) |
@@ -134,8 +134,8 @@ All types share base fields from `BaseShape`: `id`, `name`, `title`, `descriptio
 | `folder` | Group children | `isSeries`, `transition`, `children[]` |
 | `scene` | Storyboard node (alias for folder) | `name`, `description`, `script`, `children[]` |
 | `image` | Still photo | `src`, `fit` (contain/cover/fill) |
-| `video` | Video clip | `src`, `volume`, `playbackRate`, `loop` |
-| `audio` | Soundtrack/SFX | `src`, `volume`, `foreground` (ducks parent), `loop` |
+| `video` | Video clip | `src`, `volume`, `playbackRate` |
+| `audio` | Soundtrack/SFX | `src`, `volume`, `foreground` (ducks parent) |
 | `subtitle` | Text overlay | `src` (text/VTT) or `cues[]`, `fontSize`, `style` |
 | `component` | React component | `componentName`, `props`, `src` (remote ESM) |
 | `effect` | CSS animation wrapper | `animation`, `customKeyframes`, `children[]` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "2.2.9",
+  "version": "2.4.0",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"

package/skills/markcut/SKILL.md

@@ -23,11 +23,6 @@ see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full detail
 ### Video Variants
 - define variants for different video configurations, such as different languages, aspects, platforms
 
-
-### Templates
-- Templates in ``docs/templates/`` provide ready-to-use video structures for `orchestrator` agents, use them as starting point to create your own videos.
-
-
 ### Viral Story requires
 - **Hooks** : why should the viewer watch this?
 - **Conflict** : what challenges or obstacles do the characters face?
@@ -36,11 +31,22 @@ see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full detail
 - **Call to action** : what should the viewer do next?
 - **Open ending** : does the story leave room for interpretation or continuation?
 
+### TTS, TTI, TTV, STT media generation
+markcut implements a **media generation pipeline** to generate TTS, TTI, TTV, STT media automatically. 
+- `npx @lalalic/markcut --show-clis` to see the default CLIs for TTS, TTI, TTV, STT media generation.
+- `orchestrator` agent DONT generate media directly
+
 ## 3. CLI
 
 ```bash
 npx @lalalic/markcut <command> [options]
 npx @lalalic/markcut --help # get overall information
+npx @lalalic/markcut --show-clis # get command specific information
+npx @lalalic/markcut preview <file> # assemble and preview the video with a local server, and chat to edit the video and auto refresh
+npx @lalalic/markcut render <file> # render the video to mp4
+npx @lalalic/markcut vision <folder> # vision understanding medias in folder
+npx @lalalic/markcut vision <folder> --label # full pipeline vision understanding medias in folder, and provide ui to label the medias with text, time ranges
+
 ```
 
 ---
@@ -60,8 +66,6 @@ some common issues (photo or video can't be displayed, audio missing), take belo
 | Topic | File |
 |-------|------|
 | Markdown descriptive format (primary authoring format) | [docs/markdown-descriptive.md](docs/markdown-descriptive.md) |
-| Label system (browse, label, export labels.json) | [docs/label-mode.md](docs/label-mode.md) |
-| Player servers (label + edit mode) | [docs/edit-mode.md](docs/edit-mode.md) |
 
 
 ## common used components
@@ -79,4 +83,6 @@ some common issues (photo or video can't be displayed, audio missing), take belo
   - audio cut off
   - video cut off
   - subtitle mismatch
-  - sync issues between audio, video, and subtitles
+  - sync issues between audio, video, and subtitles
+- don't set duration for script or stream's duration depending on audio script
+  - markcut resolver will automatically calculate the duration based on the audio script length

package/skills/markcut/docs/markdown-descriptive.md

@@ -165,7 +165,6 @@ For compatibility, `import { Name } from "spec"` also works and produces the sam
 | `foreground` | bool; ducks parent video audio while playing | audio |
 | `spots` | number[] beat timestamps | rhythm |
 | `fit` | `contain\|cover\|fill` | image |
-| `loop` | int >1 | audio |
 | `playbackRate` | number | video |
 | `jsx` | usage JSX expression (`"<ComA value={42} />"`); compiled at runtime with registered imports in scope | component |
 | `effects` | `[name, name(params...)]` e.g. `[fadeIn, bounceIn(1, ease-out, 2)]` | any leaf/container | Apply animations directly — no wrapper node needed |
@@ -226,7 +225,7 @@ When: moving footage. Required: `src` + (`duration` or `endAt`).
 
 When: voiceover, BGM, SFX, TTS narration. Required: `src` + (`duration` or `endAt`).
 
-`- audio src:bgm.mp3 duration:6 volume:0.4 loop:2`
+`- audio src:bgm.mp3 duration:6 volume:0.4 isBackground`
 
 ### Narration / TTS
 
@@ -760,16 +759,16 @@ markcut verify courseware.md
 # best practices
 ~~~ example - avoid audio cut
 - parallel
-  - image|video background:true
+  - image|video isBackground:true
   - audio|script 
 ~~~
 
 ~~~ example - global streams
 #video
-- audio background:true loop:true src:bgm.mp3
-- component background:true loop:true jsx:"<Logo />" style:"position:fixed;top:10px;left:10px;width:100px;height:100px;"
+- audio isBackground:true src:bgm.mp3
+- component isBackground:true jsx:"<Logo />" style:"position:fixed;top:10px;left:10px;width:100px;height:100px;"
 - parallel title:"lip sync" style:"position:fixed;bottom:100px;right:100px;width:100px;height:100px;"
-  - video src:background.mp4 loop:true background:true
+  - video src:background.mp4 isBackground:true
   - video src:lip_sync.mp4
 ~~~
 
@@ -803,3 +802,13 @@ And now it's <span class="emoji-dead">dead</span>.
 ```
 ~~~
 
+~~~ example - sync vision and audio, taking care of transition timing, dynamic audio duration
+#video
+layout:series transition:fade transitionTime:1.2
+
+## hello layout:parallel
+  - image src:vision.jpg isBackground:true  # set vision as background let script/audio play in front determine the duration of the scene
+  - script "..."                            # don't set duration for script/audio, markcut resolver will determine the duration of the scene based on the final audio length
+    start:1.2                               # let vision play for 1.2s before the script/audio start, so that the transition effect can be completed
+
+~~~

package/src/descriptive/compiler.ts

@@ -527,7 +527,6 @@ function compileLeaf(node: Exclude<DescriptiveNode, DescriptiveContainer | Descr
         src: node.src,
         volume: node.volume ?? 1,
         foreground: node.foreground,
-        loop: node.loop,
         speaker: node.speaker,
       };
       return { stream, duration: end };
@@ -1182,8 +1181,13 @@ export function resolveVariantOverrides(
 export function compileDescriptiveRoot(input: DescriptiveRoot, options: CompileOptions = {}): Root {
   const root: DescriptiveRoot = typeof input === "string" ? JSON.parse(input) : input;
 
-  const resolved = resolveTransition(root.layout ? root.transition ?? root.layout : root.transition, root.transitionTime);
-  const rootKind: "series" | "parallel" | "transitionSeries" = root.layout === "parallel" ? "parallel" : "series";
+  const resolved = resolveTransition(
+    root.layout === "transitionSeries" ? (root.transition ?? "fade") : root.transition,
+    root.transitionTime,
+  );
+  const rootKind: "series" | "parallel" | "transitionSeries" =
+    root.layout === "parallel" ? "parallel" :
+    root.layout === "transitionSeries" ? "transitionSeries" : "series";
 
   const googleMapsApiKey = options.googleMapsApiKey ?? "";
   const ctx: CompileContext = {
@@ -1215,8 +1219,8 @@ export function compileDescriptiveRoot(input: DescriptiveRoot, options: CompileO
     stylesheet: input.stylesheet,
     subtitle: input.subtitle,
     isSeries: rootKind !== "parallel",
-    transition: rootKind === "transitionSeries" ? resolved.name : undefined,
-    transitionTime: rootKind === "transitionSeries" ? resolved.time : 0.5,
+    transition: root.transition || root.layout === "transitionSeries" ? resolved.name : undefined,
+    transitionTime: root.transition || root.layout === "transitionSeries" ? resolved.time : 0.5,
     children: children.map((c) => c.stream),
     durationInSeconds: duration,
   };

package/src/descriptive/markdown.ts

@@ -221,7 +221,6 @@ function parseNodeLine(content: string, lineNum?: number): DescriptiveNode {
         endAt: attrs.endAt as any,
         volume: attrs.volume as any,
         foreground: attrs.foreground as any,
-        loop: attrs.loop as any,
         instruction: attrs.instruction as any,
         script: attrs.script as any,
         visible: attrs.visible as any,
@@ -633,6 +632,9 @@ function applyRootAttrs(root: DescriptiveRoot, attrs: Record<string, unknown>):
       case "metadata":
         root.metadata = String(v);
         break;
+      case "seed":
+        root.seed = Number(v);
+        break;
       case "stylesheet":
         root.stylesheet = String(v);
         break;

package/src/descriptive/resolve.ts

@@ -986,7 +986,8 @@ export async function resolveAll(
 
   // Step 3: Generate images/videos from prompts before probing durations.
   // Use root.seed if set; otherwise inherit from options (for includes).
-  const generationSeed = result.seed ?? options.seed;
+  // Auto-generate a random seed so {seed} in the CLI template always gets a value.
+  const generationSeed = result.seed ?? options.seed ?? Math.floor(Math.random() * 2_147_483_647);
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,

package/src/player/browser.tsx

@@ -136,14 +136,16 @@ function PlayerApp() {
       .catch(() => {});
   }, []);
 
-  // Update active scene from currentTime
+  // Update active scene from currentTime.
+  // Iterate backward so the latest scene whose start <= currentTime wins —
+  // during transition overlaps, the newer scene takes precedence.
   React.useEffect(() => {
     const scenes = (window as any).__scenes;
     if (!scenes) return;
     let found = "";
-    for (const s of scenes) {
-      if (currentTime >= s.start && currentTime < s.end) {
-        found = s.name || "";
+    for (let i = scenes.length - 1; i >= 0; i--) {
+      if (currentTime >= scenes[i].start) {
+        found = scenes[i].name || "";
         break;
       }
     }
@@ -213,14 +215,28 @@ function PlayerApp() {
   }, [ready, data, startAt, fps]);
 
   // ── onFrameUpdate: track current time ───────────────────────────────
+  // Remotion Player 4.x dispatches `frameupdate` events via the player ref's
+  // EventTarget API — there is no `onFrameUpdate` prop. Subscribe in an effect.
   const handleFrameUpdate = React.useCallback((frame: number) => {
     currentFrameRef.current = frame;
-    // Throttle state updates to ~2fps for scene tracking
+    // Throttle state updates lightly for scene tracking
     setCurrentTime(prev => {
-      const newTime = frame / (data?.fps ?? 30);
-      return Math.abs(newTime - prev) > 0.5 ? newTime : prev;
+      const newTime = frame / fps;
+      return Math.abs(newTime - prev) > 0.1 ? newTime : prev;
     });
-  }, [data?.fps]);
+  }, [fps]);
+
+  // Subscribe to frameupdate events on the player ref (after it mounts)
+  React.useEffect(() => {
+    const p = playerRef.current;
+    if (!p || typeof (p as any).addEventListener !== "function") return;
+    const listener = (e: any) => {
+      const frame = e?.detail?.frame;
+      if (typeof frame === "number") handleFrameUpdate(frame);
+    };
+    (p as any).addEventListener("frameupdate", listener);
+    return () => (p as any).removeEventListener("frameupdate", listener);
+  }, [ready, data, handleFrameUpdate]);
 
   // Keyboard shortcuts
   React.useEffect(() => {
@@ -233,14 +249,17 @@ function PlayerApp() {
     function seekRelative(deltaSec: number) {
       const p = playerRef.current;
       if (!p) return;
-      const frame = p.getCurrentFrame() + Math.round(deltaSec * fps);
-      p.seekTo(Math.max(0, frame));
+      const frame = Math.max(0, p.getCurrentFrame() + Math.round(deltaSec * fps));
+      p.seekTo(frame);
+      setCurrentTime(frame / fps);
     }
 
     function seekPercent(pct: number) {
       const p = playerRef.current;
       if (!p) return;
-      p.seekTo(Math.round(pct * durationInFrames));
+      const frame = Math.round(pct * durationInFrames);
+      p.seekTo(frame);
+      setCurrentTime(frame / fps);
     }
 
     function showHelp() {
@@ -439,7 +458,6 @@ function PlayerApp() {
           clickToPlay={false}
           doubleClickToFullscreen={true}
           autoPlay={autoPlay}
-          onFrameUpdate={handleFrameUpdate}
         />
       </div>
 
@@ -448,8 +466,9 @@ function PlayerApp() {
         currentTime={currentTime}
         onSeek={(t) => {
           if (playerRef.current) {
-            const frame = Math.round(t * (data?.fps ?? 30));
+            const frame = Math.round(t * fps);
             playerRef.current.seekTo(frame);
+            setCurrentTime(t);
           }
         }}
       />

package/src/player/bundle/player.js

@@ -30520,7 +30520,7 @@ function VideoLeaf({ stream: stream2 }) {
   const startFrom = stream2.startFrom ?? 0;
   const endAt = stream2.endAt ?? totalDur;
   const volume = stream2.volume ?? 1;
-  const playbackRate = stream2.loop ? 1 : Math.min(1, toPlaybackRate((endAt - startFrom) / (end - start)));
+  const playbackRate = Math.min(1, toPlaybackRate((endAt - startFrom) / (end - start)));
   const streamStyle = cssJS(stream2.style);
   const hasAnimation = "animation" in streamStyle;
   return /* @__PURE__ */ (0, import_jsx_runtime78.jsx)(
@@ -30580,7 +30580,7 @@ function AudioLeaf({ stream: stream2 }) {
   const startFrom = stream2.startFrom ?? 0;
   const endAt = stream2.endAt ?? totalDur;
   const volume = stream2.volume ?? 1;
-  const playbackRate = stream2.loop ? 1 : toPlaybackRate((endAt - startFrom) / (end - start));
+  const playbackRate = toPlaybackRate((endAt - startFrom) / (end - start));
   return /* @__PURE__ */ (0, import_jsx_runtime79.jsx)(
     Sequence,
     {
@@ -30597,7 +30597,6 @@ function AudioLeaf({ stream: stream2 }) {
           endAt: Math.floor(startFrom * fps) + Math.floor((endAt - startFrom) * fps / playbackRate),
           muted: volume === 0 || !!ctx?.foreground,
           volume,
-          loop: (stream2.loop ?? 1) > 1,
           playbackRate,
           showInTimeline: false
         }
@@ -45891,15 +45890,41 @@ function supportHtml(text) {
   });
   return el;
 }
+function stripHtml(text) {
+  return text.replace(/<[^>]*>/g, "").trim();
+}
+function groupConsecutiveCues(cues) {
+  const groups = [];
+  let current2 = [];
+  for (const cue of cues) {
+    const plain = stripHtml(cue.text);
+    if (current2.length === 0) {
+      current2.push(cue);
+    } else {
+      const prevPlain = stripHtml(current2[current2.length - 1].text);
+      if (plain === prevPlain) {
+        current2.push(cue);
+      } else {
+        groups.push(current2);
+        current2 = [cue];
+      }
+    }
+  }
+  if (current2.length > 0) groups.push(current2);
+  return groups;
+}
 function CueFrame({
   cue,
   fps,
   CaptionComponent,
-  subtitle
+  subtitle,
+  cueGroup
 }) {
-  const durationInFrames = Math.max(1, Math.floor((cue.endAt - cue.startFrom) * fps));
-  const from = Math.floor(cue.startFrom * fps);
-  const captionText = React46.useMemo(() => supportHtml(cue.text), [cue.text]);
+  const group = cueGroup ?? [cue];
+  const startFrom = group[0].startFrom;
+  const endAt = group[group.length - 1].endAt;
+  const durationInFrames = Math.max(1, Math.floor((endAt - startFrom) * fps));
+  const from = Math.floor(startFrom * fps);
   const textStyle = React46.useMemo(
     () => ({
       ...DEFAULT_TEXT_STYLE,
@@ -45909,7 +45934,33 @@ function CueFrame({
     }),
     [subtitle.fontSize, subtitle.fontFamily, subtitle.fontStyle]
   );
-  return /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(Sequence, { layout: "none", durationInFrames, from, children: /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(CaptionComponent, { text: captionText, style: textStyle }) });
+  return /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(Sequence, { layout: "none", durationInFrames, from, children: /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(
+    GroupedCueInner,
+    {
+      group,
+      fps,
+      CaptionComponent,
+      textStyle
+    }
+  ) });
+}
+function GroupedCueInner({
+  group,
+  fps,
+  CaptionComponent,
+  textStyle
+}) {
+  const frame = useCurrentFrame();
+  const currentTime = frame / fps;
+  let activeCue = group[group.length - 1];
+  for (const c3 of group) {
+    if (currentTime >= c3.startFrom && currentTime < c3.endAt) {
+      activeCue = c3;
+      break;
+    }
+  }
+  const captionText = React46.useMemo(() => supportHtml(activeCue.text), [activeCue.text]);
+  return /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(CaptionComponent, { text: captionText, style: textStyle });
 }
 function SubtitleOverlay({ subtitle }) {
   const { fps } = useVideoConfig();
@@ -45955,15 +46006,17 @@ function SubtitleOverlay({ subtitle }) {
   }, [subtitle.src]);
   if (!cues) return null;
   const boxCss = subtitle.style ? cssJS(subtitle.style) : {};
-  return /* @__PURE__ */ (0, import_jsx_runtime88.jsx)("div", { className: `${subtitle.type || "default"} subtitle-overlay`, style: { ...DEFAULT_BOX_STYLE, ...boxCss }, children: cues.map((cue, i3) => /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(
+  const cueGroups = React46.useMemo(() => groupConsecutiveCues(cues), [cues]);
+  return /* @__PURE__ */ (0, import_jsx_runtime88.jsx)("div", { className: `${subtitle.type || "default"} subtitle-overlay`, style: { ...DEFAULT_BOX_STYLE, ...boxCss }, children: cueGroups.map((group, gi) => /* @__PURE__ */ (0, import_jsx_runtime88.jsx)(
     CueFrame,
     {
-      cue,
+      cue: group[0],
+      cueGroup: group,
       fps,
       CaptionComponent,
       subtitle
     },
-    `${i3}-${cue.startFrom}-${cue.endAt}`
+    `g${gi}-${group[0].startFrom}-${group[group.length - 1].endAt}`
   )) });
 }
 
@@ -59804,15 +59857,13 @@ var video = base.extend({
   volume: external_exports.number().min(0).max(1).default(1),
   playbackRate: external_exports.number().optional(),
   width: external_exports.number().default(1080),
-  height: external_exports.number().default(1920),
-  loop: external_exports.number().int().min(1).optional().describe(">1 = loop count")
+  height: external_exports.number().default(1920)
 });
 var audio = base.extend({
   type: external_exports.literal("audio").default("audio"),
   src: external_exports.string().optional(),
   volume: external_exports.number().min(0).max(1).default(1),
   foreground: external_exports.boolean().optional().describe("ducks parent video audio while playing"),
-  loop: external_exports.number().int().min(1).optional().describe(">1 = loop count"),
   speaker: external_exports.string().optional().describe("speaker name for multi-turn dialogue; set by resolveDialogue")
 });
 var image = base.extend({
@@ -60361,8 +60412,8 @@ function SceneThumbnails({ currentTime, onSeek }) {
   }, []);
   if (scenes.length === 0) return null;
   let activeIdx = -1;
-  for (let i3 = 0; i3 < scenes.length; i3++) {
-    if (currentTime >= scenes[i3].start && currentTime < scenes[i3].end) {
+  for (let i3 = scenes.length - 1; i3 >= 0; i3--) {
+    if (currentTime >= scenes[i3].start) {
       activeIdx = i3;
       break;
     }
@@ -60498,9 +60549,9 @@ function PlayerApp() {
     const scenes = window.__scenes;
     if (!scenes) return;
     let found = "";
-    for (const s2 of scenes) {
-      if (currentTime >= s2.start && currentTime < s2.end) {
-        found = s2.name || "";
+    for (let i3 = scenes.length - 1; i3 >= 0; i3--) {
+      if (currentTime >= scenes[i3].start) {
+        found = scenes[i3].name || "";
         break;
       }
     }
@@ -60555,10 +60606,20 @@ function PlayerApp() {
   const handleFrameUpdate = React55.useCallback((frame) => {
     currentFrameRef.current = frame;
     setCurrentTime((prev) => {
-      const newTime = frame / (data2?.fps ?? 30);
-      return Math.abs(newTime - prev) > 0.5 ? newTime : prev;
+      const newTime = frame / fps;
+      return Math.abs(newTime - prev) > 0.1 ? newTime : prev;
     });
-  }, [data2?.fps]);
+  }, [fps]);
+  React55.useEffect(() => {
+    const p2 = playerRef.current;
+    if (!p2 || typeof p2.addEventListener !== "function") return;
+    const listener = (e) => {
+      const frame = e?.detail?.frame;
+      if (typeof frame === "number") handleFrameUpdate(frame);
+    };
+    p2.addEventListener("frameupdate", listener);
+    return () => p2.removeEventListener("frameupdate", listener);
+  }, [ready, data2, handleFrameUpdate]);
   React55.useEffect(() => {
     if (!ready || !playerRef.current) return;
     const FWD_SECONDS = 5;
@@ -60567,13 +60628,16 @@ function PlayerApp() {
     function seekRelative(deltaSec) {
       const p2 = playerRef.current;
       if (!p2) return;
-      const frame = p2.getCurrentFrame() + Math.round(deltaSec * fps);
-      p2.seekTo(Math.max(0, frame));
+      const frame = Math.max(0, p2.getCurrentFrame() + Math.round(deltaSec * fps));
+      p2.seekTo(frame);
+      setCurrentTime(frame / fps);
     }
     function seekPercent(pct) {
       const p2 = playerRef.current;
       if (!p2) return;
-      p2.seekTo(Math.round(pct * durationInFrames));
+      const frame = Math.round(pct * durationInFrames);
+      p2.seekTo(frame);
+      setCurrentTime(frame / fps);
     }
     function showHelp() {
       console.log(`%c\u{1F3AC} MarkCut Player Shortcuts
@@ -60746,8 +60810,7 @@ function PlayerApp() {
             allowFullscreen: true,
             clickToPlay: false,
             doubleClickToFullscreen: true,
-            autoPlay,
-            onFrameUpdate: handleFrameUpdate
+            autoPlay
           }
         ) }),
         /* @__PURE__ */ (0, import_jsx_runtime95.jsx)(
@@ -60756,8 +60819,9 @@ function PlayerApp() {
             currentTime,
             onSeek: (t) => {
               if (playerRef.current) {
-                const frame = Math.round(t * (data2?.fps ?? 30));
+                const frame = Math.round(t * fps);
                 playerRef.current.seekTo(frame);
+                setCurrentTime(t);
               }
             }
           }

package/src/player/components/SceneThumbnails.tsx

@@ -35,9 +35,12 @@ export function SceneThumbnails({ currentTime, onSeek }: SceneThumbnailsProps) {
 
   if (scenes.length === 0) return null;
 
+  // With transition overlaps, scenes can overlap in time (scene[i].end > scene[i+1].start).
+  // Iterate backward so the latest scene whose start <= currentTime wins — i.e., as
+  // soon as the next scene starts (during a transition), it becomes the active one.
   let activeIdx = -1;
-  for (let i = 0; i < scenes.length; i++) {
-    if (currentTime >= scenes[i].start && currentTime < scenes[i].end) {
+  for (let i = scenes.length - 1; i >= 0; i--) {
+    if (currentTime >= scenes[i].start) {
       activeIdx = i;
       break;
     }

package/src/player/pipeline.mjs

@@ -259,7 +259,6 @@ function compileLeaf(node2, ctx, parentKind) {
         src: node2.src,
         volume: node2.volume ?? 1,
         foreground: node2.foreground,
-        loop: node2.loop,
         speaker: node2.speaker
       };
       return { stream, duration: end };
@@ -709,8 +708,11 @@ function resolveVariantOverrides(root, variantChain) {
 }
 function compileDescriptiveRoot(input, options = {}) {
   const root = typeof input === "string" ? JSON.parse(input) : input;
-  const resolved = resolveTransition(root.layout ? root.transition ?? root.layout : root.transition, root.transitionTime);
-  const rootKind = root.layout === "parallel" ? "parallel" : "series";
+  const resolved = resolveTransition(
+    root.layout === "transitionSeries" ? root.transition ?? "fade" : root.transition,
+    root.transitionTime
+  );
+  const rootKind = root.layout === "parallel" ? "parallel" : root.layout === "transitionSeries" ? "transitionSeries" : "series";
   const googleMapsApiKey = options.googleMapsApiKey ?? "";
   const ctx = {
     defaults: {
@@ -736,8 +738,8 @@ function compileDescriptiveRoot(input, options = {}) {
     stylesheet: input.stylesheet,
     subtitle: input.subtitle,
     isSeries: rootKind !== "parallel",
-    transition: rootKind === "transitionSeries" ? resolved.name : void 0,
-    transitionTime: rootKind === "transitionSeries" ? resolved.time : 0.5,
+    transition: root.transition || root.layout === "transitionSeries" ? resolved.name : void 0,
+    transitionTime: root.transition || root.layout === "transitionSeries" ? resolved.time : 0.5,
     children: children.map((c) => c.stream),
     durationInSeconds: duration
   };
@@ -10131,7 +10133,6 @@ function preserveVariantAttrs(node2, attrs) {
     "duration",
     "startFrom",
     "endAt",
-    "loop",
     "width",
     "height",
     "fit",
@@ -10264,7 +10265,6 @@ function parseNodeLine(content3, lineNum) {
         endAt: attrs.endAt,
         volume: attrs.volume,
         foreground: attrs.foreground,
-        loop: attrs.loop,
         instruction: attrs.instruction,
         script: attrs.script,
         visible: attrs.visible,
@@ -10594,6 +10594,9 @@ function applyRootAttrs(root, attrs) {
       case "metadata":
         root.metadata = String(v);
         break;
+      case "seed":
+        root.seed = Number(v);
+        break;
       case "stylesheet":
         root.stylesheet = String(v);
         break;
@@ -11148,7 +11151,7 @@ async function resolveAll2(root, options = {}) {
     variant: options.variants?.[0] ?? "video"
   });
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
-  const generationSeed = result.seed ?? options.seed;
+  const generationSeed = result.seed ?? options.seed ?? Math.floor(Math.random() * 2147483647);
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,
@@ -11205,6 +11208,7 @@ async function resolveAndCompile(data, options = {}) {
     ttsCli: options.ttsCli,
     sttCli: options.sttCli,
     subtitleOutputDir: options.subtitleOutputDir,
+    seed: options.seed,
     variants: options.variants
   });
   const compiled = compileDescriptiveRoot(resolved, {

package/src/player/pipeline.ts

@@ -36,6 +36,9 @@ export interface ResolveAndCompileOptions {
   /** Separate output dir for the merged subtitles.vtt (e.g., per-variant).
    *  Per-clip VTTs stay in scriptOutputDir; defaults to scriptOutputDir. */
   subtitleOutputDir?: string;
+  /** Global seed for reproducible TTI/TTV generation. Applied when the CLI
+   *  template contains {seed}. Overrides root.seed if set. */
+  seed?: number;
   /** Variant chain to apply to include nodes (e.g. ["zh", "tiktok"]).
    *  When set, included .md files are parsed with variant awareness. */
   variants?: string[];
@@ -90,6 +93,7 @@ export async function resolveAndCompile(
     ttsCli: options.ttsCli,
     sttCli: options.sttCli,
     subtitleOutputDir: options.subtitleOutputDir,
+    seed: options.seed,
     variants: options.variants,
   });
 

package/src/player/server-shared.mjs

@@ -35,24 +35,33 @@ export function extractScenes(root) {
 
   // Format 1: scenes as direct children of root
   if (root.children?.length && !root.children.find(c => c.name === "scenes" || c.id === "scenes")) {
-    let offset = 0;
+    const overlap = root.transition ? (root.transitionTime ?? 0.5) : 0;
+    let offset = 0; // cumulative scene durations (without transition overlap)
     for (const s of root.children) {
       if (!(s.type === "folder" || s.type === "scene" || s.children?.length)) continue;
       if (s.isBackground) continue;
+      // Use durationInSeconds (set by compiler) as the definitive duration.
+      // Fall back to leaf end-start for backward compatibility.
       const leaf = (s.children || []).find(c => c.src && (c.type === "image" || c.type === "video"));
-      const src2 = leaf || s;
-      const dur = (src2.end ?? 5) - (src2.start ?? 0);
+      let dur = s.durationInSeconds;
+      if (!dur || dur <= 0) {
+        const src2 = leaf || s;
+        dur = (src2.end ?? 5) - (src2.start ?? 0);
+      }
+      // Account for transition overlap: scene i starts at offset - i*overlap
+      const transitionOffset = scenes.length * overlap;
+      const start = Math.max(0, offset - transitionOffset);
       scenes.push({
         name: s.name || s.id || "scene",
-        start: offset,
-        end: offset + dur,
+        start,
+        end: start + dur,
         duration: dur,
         src: leaf?.src || "",
         mediaType: leaf?.type || "unknown",
       });
       offset += dur;
     }
-    totalDuration = offset;
+    totalDuration = offset - Math.max(0, (scenes.length - 1)) * overlap;
   }
 
   // Format 2: scenes wrapped in a "scenes" folder

package/src/schema/index.ts

@@ -104,7 +104,6 @@ export const video = base.extend({
   playbackRate: z.number().optional(),
   width: z.number().default(1080),
   height: z.number().default(1920),
-  loop: z.number().int().min(1).optional().describe(">1 = loop count"),
 });
 export type Video = z.infer<typeof video>;
 
@@ -113,7 +112,6 @@ export const audio = base.extend({
   src: z.string().optional(),
   volume: z.number().min(0).max(1).default(1),
   foreground: z.boolean().optional().describe("ducks parent video audio while playing"),
-  loop: z.number().int().min(1).optional().describe(">1 = loop count"),
   speaker: z.string().optional().describe("speaker name for multi-turn dialogue; set by resolveDialogue"),
 });
 export type Audio = z.infer<typeof audio>;

package/src/types/Audio.tsx

@@ -24,7 +24,7 @@ export function AudioLeaf({ stream }: { stream: Audio }) {
   const startFrom = stream.startFrom ?? 0;
   const endAt = stream.endAt ?? totalDur;
   const volume = stream.volume ?? 1;
-  const playbackRate = stream.loop ? 1 : toPlaybackRate((endAt - startFrom) / (end - start));
+  const playbackRate = toPlaybackRate((endAt - startFrom) / (end - start));
   return (
     <Sequence
       name={stream.src ?? "audio"}
@@ -39,7 +39,6 @@ export function AudioLeaf({ stream }: { stream: Audio }) {
         endAt={Math.floor(startFrom * fps) + Math.floor(((endAt - startFrom) * fps) / playbackRate)}
         muted={volume === 0 || !!ctx?.foreground}
         volume={volume}
-        loop={(stream.loop ?? 1) > 1}
         playbackRate={playbackRate}
         showInTimeline={false}
       />

package/src/types/Subtitle.tsx

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { cancelRender, continueRender, delayRender, Sequence, staticFile, useVideoConfig } from "remotion";
+import { cancelRender, continueRender, delayRender, Sequence, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
 import * as Subtitles from "remotion-subtitle";
 import { cssJS, parseVTT, type Cue } from "../utils/index";
 import type { SubtitleOverlay as SubtitleOverlayConfig } from "../schema/index";
@@ -89,28 +89,79 @@ function supportHtml(text: string): any {
   return el;
 }
 
+/**
+ * Strip HTML tags from text, returning the plain text content.
+ * Used to compare cue texts ignoring word-level highlighting markup.
+ */
+function stripHtml(text: string): string {
+  return text.replace(/<[^>]*>/g, "").trim();
+}
+
+/**
+ * Group consecutive cues that share the same plain-text content.
+ * This is the pattern used by word-level highlighting VTT where each
+ * cue contains the full sentence but wraps a different word in HTML
+ * (e.g. `<u>` or `<span style="...">`).
+ *
+ * Grouping them into a single CueFrame keeps the caption component
+ * mounted across word transitions, eliminating the flash that occurs
+ * when each cue unmounts/remounts its own Sequence.
+ */
+function groupConsecutiveCues(cues: Cue[]): Cue[][] {
+  const groups: Cue[][] = [];
+  let current: Cue[] = [];
+
+  for (const cue of cues) {
+    const plain = stripHtml(cue.text);
+    if (current.length === 0) {
+      current.push(cue);
+    } else {
+      const prevPlain = stripHtml(current[current.length - 1]!.text);
+      if (plain === prevPlain) {
+        current.push(cue);
+      } else {
+        groups.push(current);
+        current = [cue];
+      }
+    }
+  }
+  if (current.length > 0) groups.push(current);
+  return groups;
+}
+
 /**
  * Renders a single cue inside a <Sequence> so Remotion only evaluates it
  * during the cue's active time window — matching the qili-ai pattern.
  * This avoids per-frame cue lookups and lets the caption component mount
  * once per cue rather than re-creating on every frame.
+ *
+ * When a cue group has multiple entries (same plain text, different HTML
+ * highlighting), the component uses useCurrentFrame() to select the
+ * active cue's text dynamically — keeping the caption component mounted
+ * across word transitions and preventing flash.
  */
 function CueFrame({
   cue,
   fps,
   CaptionComponent,
   subtitle,
+  cueGroup,
 }: {
   cue: Cue;
   fps: number;
   CaptionComponent: React.FC<{ text: any; style?: React.CSSProperties }>;
   subtitle: SubtitleOverlayConfig;
+  /** Optional full group of cues sharing the same plain text. When provided,
+   * the Sequence spans the entire group and highlights change dynamically. */
+  cueGroup?: Cue[];
 }) {
-  const durationInFrames = Math.max(1, Math.floor((cue.endAt - cue.startFrom) * fps));
-  const from = Math.floor(cue.startFrom * fps);
+  const group = cueGroup ?? [cue];
+  const startFrom = group[0]!.startFrom;
+  const endAt = group[group.length - 1]!.endAt;
+
+  const durationInFrames = Math.max(1, Math.floor((endAt - startFrom) * fps));
+  const from = Math.floor(startFrom * fps);
 
-  // Stable reference: compute once per cue, not every frame
-  const captionText = React.useMemo(() => supportHtml(cue.text), [cue.text]);
   const textStyle: React.CSSProperties = React.useMemo(
     () => ({
       ...DEFAULT_TEXT_STYLE,
@@ -123,17 +174,56 @@ function CueFrame({
 
   return (
     <Sequence layout="none" durationInFrames={durationInFrames} from={from}>
-      <CaptionComponent text={captionText} style={textStyle} />
+      <GroupedCueInner
+        group={group}
+        fps={fps}
+        CaptionComponent={CaptionComponent}
+        textStyle={textStyle}
+      />
     </Sequence>
   );
 }
 
+/**
+ * Inner component that renders inside the single Sequence.
+ * Uses useCurrentFrame() to pick which cue's HTML text to display
+ * based on the current time, keeping the caption component mounted
+ * across word transitions.
+ */
+function GroupedCueInner({
+  group,
+  fps,
+  CaptionComponent,
+  textStyle,
+}: {
+  group: Cue[];
+  fps: number;
+  CaptionComponent: React.FC<{ text: any; style?: React.CSSProperties }>;
+  textStyle: React.CSSProperties;
+}) {
+  const frame = useCurrentFrame();
+  const currentTime = frame / fps;
+
+  // Find the active cue based on current time
+  let activeCue = group[group.length - 1]!;
+  for (const c of group) {
+    if (currentTime >= c.startFrom && currentTime < c.endAt) {
+      activeCue = c;
+      break;
+    }
+  }
+
+  const captionText = React.useMemo(() => supportHtml(activeCue.text), [activeCue.text]);
+
+  return <CaptionComponent text={captionText} style={textStyle} />;
+}
+
 /**
  * Root-level subtitle overlay. Renders a single VTT file as captions over
  * the entire video. VTT cue timestamps are absolute (seconds from video start),
  * matching useCurrentFrame() / fps directly.
  *
- * Each cue is rendered as a separate <Sequence> (qili-ai pattern) so Remotion
+ * Each cue is rendered as a separate <Sequence> so Remotion
  * only mounts/evaluates the caption component during its active time window.
  * This avoids per-frame computation for inactive cues.
  *
@@ -202,12 +292,17 @@ export function SubtitleOverlay({ subtitle }: { subtitle: SubtitleOverlayConfig
 
   const boxCss = subtitle.style ? (cssJS(subtitle.style) as React.CSSProperties) : {};
 
+  // Group consecutive cues with same plain text (word-level highlighting pattern)
+  // so the caption component stays mounted across word transitions — no flash.
+  const cueGroups = React.useMemo(() => groupConsecutiveCues(cues), [cues]);
+
   return (
     <div className={`${subtitle.type || "default"} subtitle-overlay`} style={{ ...DEFAULT_BOX_STYLE, ...boxCss }}>
-      {cues.map((cue, i) => (
+      {cueGroups.map((group, gi) => (
         <CueFrame
-          key={`${i}-${cue.startFrom}-${cue.endAt}`}
-          cue={cue}
+          key={`g${gi}-${group[0]!.startFrom}-${group[group.length - 1]!.endAt}`}
+          cue={group[0]!}
+          cueGroup={group}
           fps={fps}
           CaptionComponent={CaptionComponent}
           subtitle={subtitle}

package/src/types/Video.tsx

@@ -23,7 +23,7 @@ export function VideoLeaf({ stream }: { stream: Video }) {
   const startFrom = stream.startFrom ?? 0;
   const endAt = stream.endAt ?? totalDur;
   const volume = stream.volume ?? 1;
-  const playbackRate = stream.loop ? 1 : Math.min(1, toPlaybackRate((endAt - startFrom) / (end - start)));
+  const playbackRate = Math.min(1, toPlaybackRate((endAt - startFrom) / (end - start)));
   const streamStyle = cssJS(stream.style);
   const hasAnimation = "animation" in streamStyle;
   return (

package/skills/markcut/docs/edit-mode.md

@@ -1,220 +0,0 @@
-# Watch Mode
-
-> `preview <file.md> --edit` — live editing loop with AI-assisted JSON editing.
-
-Edit mode gives you a browser player that **automatically reloads** when the source file changes, plus an **edit input** that calls an AI coding agent (pi) to make changes on your behalf.
-
-Generated artifacts (TTS audio, compiled includes, component bundles) are
-stored under `.markcut/` next to the source file — see [SKILL.md](../SKILL.md) for the full layout.
-
-## Quickstart
-
-```bash
-cd remotion-engine
-npm run preview -- sample-visual.json --edit
-# → Browser opens, terminal blocks until you close it
-```
-
-## Architecture
-
-```
-┌─────────────┐     HTTP      ┌──────────────────┐    spawn     ┌──────────┐
-│   Browser   │◄──────────────►│  player/server   │◄────────────►│  pi CLI  │
-│  (Chrome)   │     SSE        │   .mjs (Node)    │  one-shot    │ (agent)  │
-└──────┬──────┘                └────────┬─────────┘              └──────────┘
-       │                                │
-       │  POST /api/edit                │  fs.watchFile
-       │  {text: "make text bigger"}    │  (poll every 500ms)
-       │                                │
-       │  GET /api/video-data           ▼
-       │  ← stream tree JSON    ┌──────────────┐
-       │                        │ stream tree  │
-       │  EventSource           │ .json (file) │
-       │  /api/events           └──────────────┘
-       │  ← {type:"reload"}           ▲
-       │                              │
-       │  window.dispatchEvent        │ pi edits
-       │  ("refresh-player")          │ this file
-       │                              │
-```
-
-## File: `src/player/server.mjs`
-
-### Server startup (`cli.mjs` → `server.mjs`)
-
-```
-node src/render/cli.mjs preview file.json --edit --port 3031
-```
-
-1. `cli.mjs` spawns `server.mjs` with `--edit` flag
-2. `server.mjs` parses `file.json` to build a recursive tree description
-3. Starts `fs.watchFile(file.json, {interval:500})` — polls every 500ms for changes
-4. Starts HTTP server on specified port
-5. Auto-opens browser via `open http://localhost:PORT`
-
-### Page served
-
-The HTML page loads two scripts:
-
-| Script | Source | Role |
-|--------|--------|------|
-| `player.js` | Bundled esbuild output from `src/player/browser.tsx` | Renders the stream tree using `@remotion/player` with `MarkCut` |
-| Inline script | Generated by `getHtml()` in `server.mjs` | Watch-mode UI controls (close button, edit input, SSE) |
-
-### Edit flow
-
-```
-Browser                          Server                          pi CLI
-  │                                │                              │
-  │── POST /api/edit ────────────► │                              │
-  │   {text: "make text bigger"}   │                              │
-  │                                │── spawn("pi", ["-p", prompt])│
-  │                                │   prompt includes:           │
-  │                                │   • full tree description   │
-  │                                │     (recursive, any depth)  │
-  │                                │   • edit history             │
-  │                                │   • knowledge (all stream   │
-  │                                │     types, components,      │
-  │                                │     schema, styling guide)  │
-  │                                │   • edit request             │
-  │                                │                              │
-  │                                │   pi can edit ANY field on  │
-  │                                │   ANY node in the tree      │
-  │                                │                              ├── edits file.json
-  │                                │                              └── exits
-  │                                │◄── exit code 0              │
-  │◄── {done:true, output:"..."} ──┤                              │
-  │                                │                              │
-  │ suppressReload = true          │                              │
-  │ header shows "Changed text..." │                              │
-  │                                │                              │
-  │  (fs.watchFile fires SSE       │                              │
-  │   but suppressReload=true      │                              │
-  │   so it's ignored)             │                              │
-  │                                │                              │
-  │ after 4s:                      │                              │
-  │ dispatchEvent("refresh-player")│                              │
-  │ → player re-fetches /api/data  │                              │
-  │ → re-renders with new JSON     │                              │
-```
-
-### Key design decisions
-
-**Why in-place refresh instead of `location.reload()`?**
-- Timeline playback continues uninterrupted
-- Status text persists until next edit
-- No page flash
-
-**Why `suppressReload`?**
-- SSE fires ~500ms after pi edits the file
-- API response arrives at the same time
-- `suppressReload` flag ignores the SSE event during edit
-- The client reloads itself after showing the summary
-
-## File: `src/player/browser.tsx`
-
-The bundled player app:
-
-1. Fetches `/api/video-data` on mount
-2. Renders the stream tree using `@remotion/player` with `MarkCut`
-3. Listens for `"refresh-player"` custom DOM event
-4. On refresh event: re-fetches data, re-renders in-place
-
-## File: `src/render/cli.mjs`
-
-The CLI routes `--edit` flag to the player server:
-
-```javascript
-if (args.edit) {
-  const serverArgs = ["src/player/server.mjs", file, "--edit", `--port=${port}`];
-  const child = spawn("node", serverArgs, { cwd: ROOT, stdio: "inherit" });
-  // ...blocks until server exits...
-}
-```
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/video-data` | GET | Returns the raw stream tree JSON file |
-| `/api/scenes` | GET | Returns parsed scenes array with timing |
-| `/api/video-info` | GET | Returns scenes + totalDuration + mode flags |
-| `/api/edit` | POST | Accepts `{text}` → spawns pi to edit the JSON → file watcher triggers → SSE reload |
-| `/api/shutdown` | POST | Kills the server process, unblocking the agent |
-| `/api/events` | GET | SSE stream — sends `{type:"reload"}` when file changes |
-| `/api/labels` | GET/POST | (label mode only) Save/load scene labels |
-
-## The pi prompt
-
-Each edit call sends a structured prompt with a **recursive tree description** instead of a flat scene list:
-
-```
-You are editing sample-visual.json, a Remotion stream tree JSON.
-
-The stream tree (indentation shows nesting; timing in seconds):
-  root "root" (1080×1920, 30fps, series, transition:fade)
-    folder "scene-1" (parallel)
-      component GradientBackground {type:"radial",animated:true,noise:true} [05s, bg]
-      component AnimatedHeadline {"text":"Hello Remotion",...} [0.54.5s]
-    folder "scene-2" (parallel)
-      component GradientBackground {type:"linear",animated:true} [05s, bg]
-      subtitle "This text is styled with CSS" fontSize:52 [0.54.5s]
-    ...
-
-Previous edits:
-1. make scene 1 headline text orange
-
-Edit request: make scene 1 headline text bigger
-
---- Knowledge ---
-You can edit ANY field on ANY node in the JSON...
-Stream types: root, folder, video, audio, image, subtitle, component, effect, rhythm, map
-...
-IMPORTANT: Read the full existing JSON file before editing. Only edit the JSON file. You can change, add, or remove any field on any node. Output ONLY a one-line summary of what specific change you made.
-```
-
-The tree description walks the JSON recursively, showing:
-- **Nesting depth** via indentation
-- **Type** and **id/name** of each node
-- **Key fields** (dimensions, fps, theme, series/parallel, transitions)
-- **Timing** from leaf span (`[start→end]`)
-- **isBackground** flag (`[bg]`)
-- **Component props** and node-specific fields (fontSize, fit, style, volume, etc.)
-
-This means pi can edit **any aspect of the JSON** ÔÇö not just scene props. Nested folders, effects, rhythms, maps, actions, styles, themes, global stylesheets, audio config ÔÇö everything is visible and editable.
-
-## Session context
-
-The server maintains `editHistory[]` — every edit is appended. On each call, previous edits are included so pi knows what was done before:
-
-```
-Previous edits:
-1. make scene 1 headline text orange
-2. change background from radial to linear gradient
-3. add 3D angle to device mockup in scene 4
-```
-
-This gives pi enough context to make coherent changes across multiple edit rounds.
-
-## Close / tab-close
-
-| Action | What happens |
-|--------|-------------|
-| Click **✕** | `sendBeacon("/api/shutdown")` → server exits → agent unblocks |
-| Close **tab** | SSE connection drops → 3s grace → server exits |
-| Close **browser** | Same as tab close |
-
-## Label mode (`--label`)
-
-`preview <file.json> --label` starts the same player but with a **label input** instead of the edit input. Labels are saved to `labels.json` next to the source file. No AI editing, no file watching.
-
-## Build
-
-The browser bundle is built with esbuild:
-
-```bash
-bash scripts/build-player.sh
-# → src/player/bundle/player.js
-```
-
-The bundle includes React, @remotion/player, MarkCut, all 13 built-in components, themes, templates, and the duration utility. It is served as a static file by the player server.

package/skills/markcut/docs/label-mode.md

@@ -1,112 +0,0 @@
-# Label System
-
-Interactive media labeling before understanding clips in json stream tree.
-The stream tree follow rules, see [docs/json-descriptive.md](docs/json-descriptive.md) for full details .
-
-## Overview
-
-The label player lets you load a stream tree, browse its clips, and attach descriptive labels to each clip's media. 
-The output is an updated `labels.json` file with `description` fields populated.
-
-## Usage
-
-```bash
-# Label from a stream tree JSON or labels.json
-npx markcut preview labels.json --label
-
-# Specify port
-npx markcut preview labels.json --label --port 3031
-```
-
-### Labels Persistence
-The stream tree follow rules, see [docs/json-descriptive.md](docs/json-descriptive.md) for full details .
-Labels are saved to the source file.
-
-```json
-{
-  "root": {
-    "id": "root",
-    "type": "root",
-    "children": [
-      {
-        "id": "scene-1",
-        "type": "folder",
-        "children": [
-          {
-            "id": "scene-1-media",
-            "type": "image",
-            "src": "/media/photo.jpg",
-            "start": 0, "end": 5,
-            "description": "Best group shot from the campfire"
-          }
-        ]
-      },
-      {
-        "id": "scene-2",
-        "type": "folder",
-        "children": [
-          {
-            "id": "scene-2-media",
-            "type": "video",
-            "src": "/media/clip.mp4",
-            "start": 0, "end": 5,
-            "description": "Sunset timelapse — use for intro"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-The `description` field on each media leaf node holds the label text.
-
-## Workflow
-
-```
-Stream tree JSON (labels.json)
-       │
-       ▼
-─── preview --label ───→ Browse & label clips
-       │                        │
-       │                        ▼
-       │                  Updated labels.json
-       │                        │
-       ▼                        ▼
-    Use in Storyboard ──────→ Assemble → Render
-```
-
-1. **Prepare** a stream tree JSON with scenes
-2. **Label** with `preview --label` to add descriptions to each scene
-3. **Export** labels are saved alongside the source file
-4. **Use** the labeled scenes in your storyboard or assembly workflow
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/video-data` | GET | Returns the raw stream tree JSON |
-| `/api/video-info` | GET | Returns scenes array with timing + totalDuration |
-| `/api/labels` | GET | Returns the current stream tree with descriptions |
-| `/api/labels` | POST | Saves updated descriptions ({descriptions: {index: "text"}}) |
-| `/api/shutdown` | POST | Kills the server |
-| `/api/events` | GET | SSE events (reload on file change) |
-
-## Implementation
-
-Source: `src/player/server.mjs` (unified server, use `--label` flag)
-UI controls: `src/player/components/LabelControls.tsx` (React component)
-
-- Built on Node.js `http` module (no Express dependency)
-- Serves bundled `player.js` (esbuild output from `src/player/browser.tsx`)
-- Labels saved atomically to disk on each POST
-- Supports stream tree JSON, descriptive JSON, and markdown input
-- React components in `src/player/components/` replace the old HTML-based `ui/` directory
-
-## Reference
-
-| Topic | Link |
-|-------|------|
-| Storyboard (video planning) | [storyboard.md](storyboard.md) |
-| Stream tree types | `SKILL.md` |
-| Dynamic components | [dynamic-components.md](dynamic-components.md) |