@lalalic/markcut 2.2.4 → 2.2.6

package/package.json

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

package/skills/markcut/SKILL.md

@@ -28,6 +28,14 @@ see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full detail
 - 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?
+- **Resolution** : how are the conflicts resolved?
+- **Emotion** : what feelings are evoked in the viewer?
+- **Call to action** : what should the viewer do next?
+- **Open ending** : does the story leave room for interpretation or continuation?
+
 ## 3. CLI
 
 ```bash

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

@@ -284,7 +284,7 @@ voices:{"Ray":"--voice en-US-GuyNeural","Alice":"--voice en-US-JennyNeural"}
 Alice: I'm working on something exciting"
 ```
 
-Since values are raw CLI flags, they naturally support voice cloning, rate, pitch, and any edge-tts feature:
+Since values are raw CLI flags, they naturally support voice cloning, rate, pitch:
 
 ```md
 voices:{"Ray":"--voice en-US-GuyNeural --rate +20%","Clone":"--voice clone-xxx --pitch +5Hz"}
@@ -757,45 +757,49 @@ markcut verify courseware.md
 - `@remotion/shapes` — render shapes like arrows, circles, rectangles, etc
 - `@remotion/starburst` — render starburst animations
 
-## Example
-
-```md
----
-width: 1080
-height: 1920
-fps: 30
----
-# video
-layout:series
-~~~js imports
-export { StatCounter } from "stat-counter"
-export { Logo } from "github:myorg/design-system#Logo"
-
-export function Greeting({ name }) {
-  return <div style={{color: '#fff', fontSize: 28, textAlign: 'center'}}>Hello {name}!</div>
-}
+# best practices
+~~~ example - avoid audio cut
+- parallel
+  - image|video background:true
+  - audio|script 
 ~~~
 
-## Hook
-layout:parallel
-- script "Set location and emotional tone"
-- image src:cover.jpg duration:2
+~~~ 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;"
+- 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:lip_sync.mp4
+~~~
 
-## Journey
-layout:transitionSeries transition:fade transitionTime:0.4
-- script "Move through moments"
-- video src:clips/arrival.mp4 startFrom:0 endAt:3.5
-- video src:clips/fire.mp4 startFrom:1 endAt:4
+~~~ example - styling VTT captions
+```vtt
+000:00:00.000 --> 00:00:05.000
+It's a <span style="color:#ff6b6b;font-weight:bold">Bear</span>.
 
-## Stat
-layout:parallel
-- component duration:2 jsx:"<StatCounter value={42} label='S-mores' />"
+000:00:05.000 --> 00:00:10.000
+And now it's <span class="emoji-dead">dead</span>.
 
-## Logo
-layout:parallel
-- component duration:1 jsx:"<Logo />"
+000:00:10.000 --> 00:00:15.000
+<span class="bong">Bong!</span>
+```
 
-## Route
-layout:parallel
-- map duration:3 travelMode:DRIVING waypoints:[37.7749,-122.4194,"SF";34.0522,-118.2437,"LA"]
+#root
+```css stylesheet
+.emoji-dead {
+  font-family: "Funny Emoji", sans-serif;
+  font-size: 48px;
+}
+.bong {
+  color: #ff6b6b;
+  font-weight: bold;
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  animation: bong 1s ease-in-out infinite;
+}
 ```
+~~~
+

package/skills/markcut/docs/templates/courseware/TEMPLATE.md

@@ -39,7 +39,7 @@ Layout of this template package:
 
 ```
 # video                          ← root: width:1920 height:1080 fps:30 layout:series
-│                                  subtitle:{fontSize:"20px"} tts:"<edge-tts CLI template>"
+│                                  subtitle:{fontSize:"20px"}
 ├── ## Hook                      ← 3–5s attention grabber, fixed duration
 ├── ## Slides                    ← layout:transitionSeries transition:fade(0.5)
 │   ├── ### TitleSlide           ← transitionSeries, bullet-reveal (1 beat)
@@ -199,10 +199,9 @@ See markcut docs for available effect types: `fadeIn`, `zoomIn`, `bounceIn`, `sl
 
 Guide TTS pronunciation for more natural speech using SSML-style cues in the script text:
 - **Pause**: use `—` (em dash) or `...` for natural breath pauses
-- **Emphasis**: capitalize key terms or use `*asterisks*` (edge-tts interprets these as emphasis)
 - **Rate**: set `tts.rate:+10%` on the root config line for faster pacing, or `tts:{"--rate +10%"}` per scene
 - **Phonetic spelling**: for jargon ("Snyk" = "snik", "Grafana" = "gruh-fah-nuh"), add parenthetical pronunciation on first use: `Snyk (pronounced "snik")` 
-- **Language mix**: for bilingual content, switch edge-tts voice per language using the `# <lang>` variant block
+- **Language mix**: for bilingual content, switch tts voice per language using the `# <lang>` variant block
 
 ## 3. Authoring rules — the professional bar
 

package/skills/markcut/docs/templates/deep-dive/TEMPLATE.md

@@ -34,8 +34,7 @@ flowchart LR
 ## 0. Prerequisites
 
 - `npx @lalalic/markcut` runnable
-- TTS CLI (default: `edge-tts`)
-- `ffmpeg`/`ffprobe` on PATH
+- `ffmpeg`/`ffprobe/exiftool` on PATH
 - Web search capability (for research phase)
 - ITT/TTV CLI (for `src:auto` visuals) — optional but recommended
 - For reviewer: image-understanding capability, STT CLI
@@ -50,7 +49,7 @@ flowchart LR
 | Tone | no | `analytical` | `analytical` (neutral, evidence-driven), `opinionated` (strong thesis, persuasive), `philosophical` (open-ended, reflective), `investigative` (detective-like, reveals) |
 | Target duration | no | 8 min | 3–20 min. Longer formats need deeper scene breakdown |
 | Depth | no | `moderate` | `overview` (surface-level, broad), `moderate` (some depth, 3-5 angles), `deep` (thorough, 5-10 angles, academic-level) |
-| Voice | no | en: `en-US-GuyNeural` | edge-tts voice per language |
+| Voice | no |  | mlx-audio voice per language |
 | BGM style | no | `ambient` | background music mood. Optional — deep dives can work without BGM |
 
 **Core rule: Every factual claim must be supported by a source.** If you cannot find a source for a claim, either qualify it ("some argue that...", "it's believed that...") or remove it. Cite sources on screen (see §3).
@@ -63,7 +62,7 @@ A deep dive is not a lecture and not a highlight reel — it's a **narrative jou
 
 ```
 # video                          ← root: width:1920 height:1080 fps:30 layout:series
-│                                  subtitle:{fontSize:"24px"} tts:"<edge-tts CLI>"
+│                                  subtitle:{fontSize:"24px"}
 │                                  transition:fade(0.5)
 ├── ## Hook                      ← 15–30s. The question, the contradiction, the mystery
 ├── ## Context                   ← 30–60s. Background the audience needs

package/skills/markcut/docs/templates/illustrated-book/TEMPLATE.md

@@ -34,10 +34,7 @@ flowchart LR
 ## 0. Prerequisites
 
 - `npx @lalalic/markcut` runnable
-- TTS CLI (default: `edge-tts`) — narration voice, warm and expressive
-- ITT CLI (for `src:auto` illustration generation) — **strongly recommended**, illustrations are the core of this format
-- `ffmpeg`/`ffprobe` on PATH
-- For reviewer: image-understanding capability, STT CLI
+- `ffmpeg`/`ffprobe`/`exiftool` on PATH
 
 ## 1. Inputs — collect before starting
 
@@ -49,7 +46,7 @@ flowchart LR
 | Art style | **yes** | — | the illustration style for ALL pages. Must be consistent. Examples: "watercolor, soft pastels, children's book illustration style", "ink wash painting, traditional Chinese style", "digital painting, studio Ghibli inspired, warm lighting", "woodcut print style, high contrast black and white", "vintage botanical illustration, sepia tones". This single style string is injected into every TTI prompt. |
 | Language | no | en | narration and on-screen text language |
 | Reading pace | no | `moderate` | `slow` (3-4s per line, ~10s per spread), `moderate` (2-3s per line, ~7s per spread), `fast` (1.5-2s per line, ~5s per spread) |
-| Voice | no | en: `en-US-JennyNeural` | edge-tts voice. Prefer warm, expressive voices for storytelling |
+| Voice | no |  | mlx-audio voice. Prefer warm, expressive voices for storytelling |
 | BGM mood | no | `ambient` | optional background music. "soft piano", "ambient nature", "lullaby", or "none" |
 | Pages | no | auto | target number of spreads/pages. Auto-calculated from text if not set |
 
@@ -62,7 +59,6 @@ flowchart LR
 ```
 # video                          ← root: width:1920 height:1080 fps:30 layout:series
 │                                  subtitle:{fontSize:"40px",fontFamily:"Georgia,serif"}
-│                                  tts:"<edge-tts CLI>"
 │                                  transition:fade(0.5)
 ├── - audio isBackground:true src:bgm.mp3 volume:0.08 (optional)
 │

package/skills/markcut/docs/templates/short-film/TEMPLATE.md

@@ -33,9 +33,7 @@ flowchart LR
 ## 0. Prerequisites
 
 - `npx @lalalic/markcut` runnable
-- TTS CLI (default: `edge-tts`) — voiceover narration or character voices
-- ITT CLI (for `src:auto` scene generation) — **critical**, every scene is AI-generated
-- `ffmpeg`/`ffprobe` on PATH
+- `ffmpeg`/`ffprobe`/`exiftool` on PATH
 - For reviewer: image-understanding capability, STT CLI
 
 ## 1. Inputs — collect before starting
@@ -48,7 +46,7 @@ flowchart LR
 | Tone | no | `serious` | `serious` (somber, weighty), `noir` (dark, mysterious), `melancholic` (sad, reflective), `hopeful` (bittersweet, uplifting) |
 | Language | no | en | narration and on-screen text language |
 | Target duration | no | 7 min | 5–10 min |
-| Voice(s) | no | en: `en-US-GuyNeural` | edge-tts voice(s). For multiple characters, provide a list: {narrator, character1, character2} |
+| Voice(s) | no |  | mlx-audio voice(s). For multiple characters, provide a list: {narrator, character1, character2} |
 | Music mood | no | `cinematic` | score style: cinematic, ambient, noir jazz, minimal piano, tense. BGM is **recommended but not mandatory** — silence is a valid cinematic choice |
 | Aspect ratio | no | `16:9` | `16:9` (standard), `2.35:1` (cinemascope — add black bars in stylesheet), `4:3` (vintage) |
 
@@ -60,7 +58,7 @@ flowchart LR
 
 ```
 # video                          ← root: width:1920 height:1080 fps:30 layout:series
-│                                  tts:"<edge-tts CLI — narrator voice>"
+│                                 
 │                                  transition:fade(0.5)
 ├── - audio isBackground:true foreground:true src:score.mp3 volume:0.12
 ├── - audio isBackground:true src:ambient.mp3 volume:0.05  (optional, diegetic ambience)

package/skills/markcut/docs/templates/short-video/TEMPLATE.md

@@ -34,7 +34,6 @@ flowchart LR
 ## 0. Prerequisites
 
 - `npx @lalalic/markcut` runnable
-- TTS CLI (default: `edge-tts`)
 - `ffmpeg`/`ffprobe` on PATH
 - ITT/TTV CLI (for `src:auto` background generation) — optional but recommended
 - For reviewer: image-understanding capability, STT CLI
@@ -49,7 +48,7 @@ flowchart LR
 | Language | no | en | narration language |
 | Style | no | `cinematic` | `cinematic` (dramatic), `energetic` (fast cuts, bright), `minimal` (clean, slow), `trendy` (meme-aware, casual) |
 | Target duration | no | 30s | 15–60s |
-| Voice | no | en: `en-US-GuyNeural` | edge-tts voice |
+| Voice | no |  | mlx-audio voice |
 | BGM mood | no | `upbeat` | mood for background music. BGM is **mandatory**. |
 
 **Rule:** For explainer/quote/storytime formats, generate all visuals via `src:auto prompt:"..."` — describe vivid, cinematic scenes. For showcase/highlight formats, use the provided source media and let the narration describe it.
@@ -61,7 +60,7 @@ flowchart LR
 ```
 # video                          ← root: width:1080 height:1920 fps:30 layout:series
 │                                  subtitle:{fontSize:"56px",type:"Typewriter",fontFamily:"Arial Black"}
-│                                  tts:"<edge-tts CLI>"
+│                                  
 │                                  transition:fade(0.3)
 ├── - audio isBackground:true foreground:true src:bgm.mp3 volume:0.1
 │

package/skills/markcut/docs/templates/vlog/TEMPLATE.md

@@ -31,7 +31,7 @@ Follow this file top to bottom. Read the markcut skill (`SKILL.md` → `docs/mar
 | Style | no | `daily` | `daily` (casual), `lyrical` (cinematic), `humorous` (funny) |
 | Target duration | no | 60s | 15–120s for short vlogs |
 | Profile | **parse from** | context | user's personality, region, family members, voice ref, life context. Read this file at the start — it's the authoritative source for who the creator is. The creator's name, region, family, and regular activities feed into narration naturally ("my daughter", "drove up from Ottawa", "my third camping trip this year"). |
-| Voice | no | en: `en-US-GuyNeural` | edge-tts voice. If profile has a voice reference URL, use TTS voice cloning instead |
+| Voice | no |  | mlx-audio voice. If profile has a voice reference URL, use TTS voice cloning instead |
 | BGM style | no | `ambient` | mood/genre for background music. BGM is **mandatory** — see §2 for root-level audio node |
 | Vlog history | **read from** | `vlog_history.json` or folder | JSON array of past vlogs in the project. Used for story continuity ("last time I was here...", "my third camping trip this year"). If the file doesn't exist, start fresh. See §3 for history rules. |
 
@@ -42,8 +42,15 @@ Follow this file top to bottom. Read the markcut skill (`SKILL.md` → `docs/mar
 ### Overview
 
 ```
+---
+storyoutline: # it's your logic to design story.
+  hook:
+  confliction:
+  emotion:
+  open-ending:
+---
 # video                          ← root: width:1920 height:1080 fps:30 layout:series
-│                                  tts:"<edge-tts CLI template>"
+│                                  
 ├── ## Route                     ← (only if GPS data available)
 │                                  layout:parallel
 │                                  - map waypoints:[...]
@@ -77,9 +84,11 @@ width:1920 height:1080 fps:30 layout:series
 - Volume: 0.10–0.20 for ambient BGM; 0.05–0.10 for lyrical music.
 - Source BGM from royalty-free libraries (see `prompts/bgm-select.md`).
 
-### Core design: one scene per story beat, media + narration as parallel
+### Core design: one scene per story beat
+- determine **Hook**, **Confliction**, **Emotion**, **Open-ending**
+- the vlog's story arc: hook → chronological story beats → close.
 
-Each scene is a **story beat** — a single moment or idea that stands on its own. Inside a scene, `layout:parallel` means all media and the subtitle narration play simultaneously.
+- Each scene is a **story beat** — a single moment or idea that stands on its own. Inside a scene, `layout:parallel` means all media and the subtitle narration play simultaneously.
 
 ```
 ## Into the Woods
@@ -90,7 +99,7 @@ layout:parallel
 ```
 
 **Rules:**
-
+- determine story arc first, then group clips into scenes. Each scene is a single story beat.
 - **Scene count**: 5–12 scenes. Each 3–20 seconds. Total duration matches target ±15%.
 - **Hook → Core → Vibe → Close arc**: The first scene hooks the viewer (best visual + intriguing line). Middle scenes are chronological story beats. The final scene provides emotional/humorous closure.
 - **Transition between scenes**: The root `layout:series` plays scenes sequentially. For smooth transitions, add `transition:fade(0.5)` to the root config line.
@@ -100,19 +109,6 @@ layout:parallel
 - **BGM is mandatory**: Always add an `- audio isBackground:true foreground:true` at root level (see BGM section above).
 - **No bullet-reveal** — vlogs are linear media, not slides. No `current`/`on:` events needed.
 
-### Scene media node style
-
-For images:
-```markdown
-- image src:<relative-path> duration:<s> start:<s>
-```
-
-For video clips (trimmed):
-```markdown
-- video src:<relative-path> startFrom:<s> endAt:<s> start:<s>
-```
-
-The `src` path is relative to the media folder. During assembly, media is symlinked/copied into the markcut project so `npx markcut render` can serve it.
 
 ## 2.b Production polish — route sync, overlays, effects
 
@@ -154,14 +150,14 @@ Use per-scene map overlays when GPS data is available for that specific clip. Us
 
 ## 3. Authoring rules — the professional bar
 
-### Filter rules (see `prompts/group-clips.md`)
+### Filter rules (use `prompts/group-clips.md`)
 
-- Keep all clips unless: aesthetic score < 0.4, near-duplicate of a better clip, or off-topic.
+- Keep all clips unless: near-duplicate of a better clip, or off-topic.
 - Always keep clips with a positive user label from the interactive labeling step.
 - Max ~20% drops. Never drop below 5 clips total.
 - List every dropped clip with a reason.
 
-### Grouping rules (see `prompts/group-clips.md`)
+### Grouping rules (use `prompts/group-clips.md`)
 
 - **Visual continuity rule**: clips sharing the same background/outfit/subject-state form one scene. Exhaust one scene before moving to the next. No jumping A→B→A.
 - 1–4 clips per scene (a single long take >10s may be its own scene).
@@ -187,7 +183,7 @@ Before writing narration, search for local news, events, or weather for the vlog
 - **Local event**: "Turns out the Gatineau Park was running the fall colours festival that weekend."
 - **Seasonal context**: "Full moon that night, so the trail was brighter than usual."
 
-Rules:
+**Rules:**
 - Only use facts confirmed by at least one search result. Never invent weather/events.
 - Keep it to 1–2 local-context references per vlog. Don't overwhelm the narration.
 - The context should **amplify** the story, not replace it. "Drove up during the fall colours festival so the park was packed" tells us more than just the festival fact.
@@ -207,7 +203,7 @@ Rules:
 - Keep references brief (one line per vlog max). The story should stand alone.
 - Never fabricate a past event. Only what exists in the history file.
 
-### Creator profile
+### User profile
 
 Read `~/.pi/agent/user.md` at the start and weave the creator's identity into narration naturally:
 
@@ -215,7 +211,7 @@ Read `~/.pi/agent/user.md` at the start and weave the creator's identity into na
 - **Region**: name-drop the city/area ("drove up from Ottawa", "my favourite spot in the Outaouais").
 - **Family**: use real names/roles ("my daughter", "my wife") as shown in the profile and visible in clips.
 - **Regular activities**: if the user hikes regularly, frame this as one of many hikes ("another trail checked off the list").
-- **Voice reference**: if the profile has a voice URL for TTS cloning, use that instead of default edge-tts voices.
+- **Voice reference**: if the profile has a voice URL for TTS cloning.
 
 ### Title
 
@@ -226,44 +222,6 @@ One title, 3–15 words, poetic/suspenseful/summarizing, social-media friendly.
 - Same pattern as courseware: `# <lang>` variant block at file end with per-language TTS voice.
 - Every `script`/`subtitle` node gets a `<lang>:"..."` twin.
 
-## 4. Components & styles
-
-Vlogs don't need custom JSX components — they use markcut's built-in `image`, `video`, `audio`, `subtitle`, and `map` nodes. However, you may add these optional enhancements:
-
-### Optional: NarratorBox component
-
-If adding a narrator overlay with name label, include this in the `~~~js imports` block:
-
-```jsx
-import { delayRender, continueRender } from 'remotion'
-
-export function NarratorBox({ src, name = '', size = 100 }) {
-  return (
-    <div style={{
-      position: 'absolute', bottom: 40, left: 40,
-      display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6,
-    }}>
-      <div style={{
-        width: size, height: size, borderRadius: '50%', overflow: 'hidden',
-        border: '3px solid rgba(255,255,255,.6)',
-        boxShadow: '0 0 20px rgba(0,0,0,.4)',
-      }}>
-        <img src={src} style={{ width: '100%', height: '100%', objectFit: 'cover' }} />
-      </div>
-      {name && (
-        <span style={{
-          fontSize: 14, color: '#fff', textShadow: '0 2px 8px rgba(0,0,0,.6)',
-          whiteSpace: 'nowrap', fontWeight: 500,
-        }}>{name}</span>
-      )}
-    </div>
-  )
-}
-```
-
-### Stylesheet
-
-No stylesheet needed for standard vlogs. The built-in markcut rendering handles video/image filling, subtitle positioning, and audio mixing. Add one only if you need custom overlays.
 
 ## 5. Workflow
 
@@ -284,7 +242,7 @@ No stylesheet needed for standard vlogs. The built-in markcut rendering handles
      }
    ]
    ```
-   If the file doesn't exist, start fresh.
+   If the file doesn't exist, try to extract for project folder.
 
 ### Phase 1: Prepare media
 
@@ -303,7 +261,7 @@ No stylesheet needed for standard vlogs. The built-in markcut rendering handles
 5. **Search local news/events** — Fill `prompts/local-context.md` with the vlog's location, date range, and theme. This searches for relevant weather, events, news, or seasonal information. The result feeds into narration with 1–2 natural references.
 
 6. **Group and filter clips** — Fill `prompts/group-clips.md` with clip data from `metadata.json`. This produces:
-   - Dropped clips with reasons
+   - Speed up less-interesting clips vs Dropped clips
    - Visual-continuity scene groups
    - Trim boundaries for video clips
    - GPS waypoints for per-scene map overlays
@@ -325,16 +283,7 @@ No stylesheet needed for standard vlogs. The built-in markcut rendering handles
 
 8. **Select BGM** — Choose background music that matches the vlog's mood. Fill `prompts/bgm-select.md` or search using the `audio-sourcing` skill. Download the track and reference it as `src:bgm.mp3` in the root-level audio node.
 
-9. **Assemble course.md** — Write the markcut markdown file using §2 grammar. The root config line includes TTS voice. BGM is at root level (`- audio isBackground:true foreground:true src:bgm.mp3 volume:0.15`). For scenes with GPS data, add per-scene map overlays (see §2.b).
-
-   **Media staging**: Make media accessible to the renderer:
-   ```
-   mkdir -p .markcut/generated/media/
-   cp <media-folder>/clips_normalized/*.mp4 .markcut/generated/media/
-   cp <media-folder>/*.jpg .markcut/generated/media/
-   cp /path/to/bgm.mp3 .markcut/generated/media/bgm.mp3
-   ```
-   Reference as `src:.markcut/generated/media/<file>` in the markdown.
+9. **Assemble .md** — Write the markcut markdown file using §2 grammar. For scenes with GPS data, add per-scene map overlays (see §2.b).
 
 10. **Render** — `npx @lalalic/markcut render course.md`. On engine errors: fix and re-render, max 3 attempts per error, then ask the user.
 
@@ -371,12 +320,7 @@ Done only when ALL hold:
 - [ ] BGM is **present** (ffprobe confirms audio stream or mixed track) and audible (not silent, not clipping)
 - [ ] BGM ducked under voice — TTS audible above music in ≥90% of spoken segments
 - [ ] local context references (if any) verified against search results — no invented weather/events
-- [ ] history references (if any) match actual entries in `vlog_history.json` — no fabricated past events
+- [ ] history references — no fabricated past events
 - [ ] media `src` paths resolve correctly (no broken links in rendered output)
 - [ ] profile used: narration tone matches creator personality, family names from profile appear correctly
-- [ ] per-scene map overlays (if GPS available) positioned without obstructing main content
-
-## 7. Reference — worked examples
-
-- Golden example: See `tests/fixtures/templates/courseware.md` for the template format.
-- Reference vlog storyboard: The bullx vlog project at `free2/bullx/packages/vlog/storyboard.md` shows a real vlog (birthday camping at Lac Philippe) with 13 chronological scenes, route map, clip trimming, and first-person narration. The project's `.pi/agents/story-writer.md` and `.pi/prompts/vlog-storyboard.md` contain the source of truth for the story-writing methodology documented here.
+- [ ] per-scene map overlays (if GPS available) positioned without obstructing main conten

package/src/config.mjs

@@ -94,8 +94,10 @@ export const DEFAULT_EDIT_CLI = process.env.MARKCUT_EDIT_CLI || 'npx pi --sessio
 
 // ── Render-only pipeline CLI templates ─────────────────────────────────────
 // These are specific to the render pipeline (no vision pipeline equivalent).
+// All templates support {input}, {output}, and {seed} placeholders.
+// {seed} is substituted with root.seed (or empty string if not set).
 
 export const DEFAULT_TTI_CLI =
   process.env.MARKCUT_TTI_CLI ||
-  'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}"';
+  'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 5 --prompt "{input}" --output "{output}" --seed {seed}';
 export const DEFAULT_TTV_CLI = process.env.MARKCUT_TTV_CLI || '';

package/src/descriptive/compiler.ts

@@ -180,6 +180,11 @@ export interface DescriptiveRoot {
   stt?: string;
   tti?: string;
   ttv?: string;
+  /** Global seed for TTI/TTV generation. When the CLI template contains {seed},
+   *  this value is substituted in to make generation reproducible.
+   *  All generated media in this video share the same seed, ensuring visual
+   *  consistency across scenes. Default: no seed (random generation). */
+  seed?: number;
   layout?: "series" | "parallel" | "transitionSeries";
   transition?: string;
   transitionTime?: number;

package/src/descriptive/resolve.test.ts

@@ -164,6 +164,7 @@ describe("resolveGeneratedMedia", () => {
       "sunset",
       expect.stringMatching(/\.png$/),
       "gen-img --prompt {input} --out {output}",
+      undefined,
     );
   });
 
@@ -186,6 +187,7 @@ describe("resolveGeneratedMedia", () => {
       expect.stringMatching(/\.mp4$/),
       "gen-vid --prompt {input} --out {output}",
       expect.any(String), // ttiCmd defaults to DEFAULT_TTI_CLI
+      undefined,
     );
   });
 
@@ -235,6 +237,7 @@ describe("resolveGeneratedMedia", () => {
       "override test",
       expect.stringMatching(/\.png$/),
       "root-tti {input} --out {output}",
+      undefined,
     );
   });
 
@@ -253,6 +256,7 @@ describe("resolveGeneratedMedia", () => {
       "test",
       expect.stringMatching(/\.png$/),
       "custom-tti --prompt {input} --out {output}",
+      undefined,
     );
   });
 
@@ -642,6 +646,7 @@ describe("resolveGeneratedMedia — TTV additional", () => {
       expect.stringMatching(/\.mp4$/),
       "root-ttv {input} --out {output}",
       expect.any(String),
+      undefined,
     );
   });
 
@@ -661,6 +666,7 @@ describe("resolveGeneratedMedia — TTV additional", () => {
       expect.stringMatching(/\.mp4$/),
       "custom-ttv {input} --out {output}",
       expect.any(String),
+      undefined,
     );
   });
 

package/src/descriptive/resolve.ts

@@ -678,6 +678,10 @@ export interface ResolveGeneratedMediaOptions {
   ttiCli?: string;
   /** Default TTV CLI template (overrides root.ttv) */
   ttvCli?: string;
+  /** Global seed for reproducible TTI/TTV generation. Applied when the CLI
+   *  template contains {seed}. All generated media share this seed for
+   *  visual consistency across scenes. */
+  seed?: number;
 }
 
 /**
@@ -723,9 +727,13 @@ export async function resolveGeneratedMedia(
       ? (clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI)
       : (clone.ttv ?? options.ttvCli ?? DEFAULT_TTV_CLI);
 
-    // Content-addressed filename: hash of prompt + CLI + type, so identical
-    // prompts across different source files share the same generated media.
-    const cacheKey = computeCacheKey({ prompt, cli, type });
+    // Use root.seed for reproducible generation (applied when CLI template has {seed}).
+    // seed is part of the cache key so different seeds produce different cached outputs.
+    const seed = options.seed;
+
+    // Content-addressed filename: hash of prompt + CLI + type + seed, so identical
+    // prompts with different seeds produce distinct cached media.
+    const cacheKey = computeCacheKey({ prompt, cli, type, seed });
     const outputPath = join(options.outputDir, `${cacheKey}.${ext}`);
 
     const cached = checkCache(cache, `gen:${cacheKey}`, cacheKey);
@@ -742,8 +750,8 @@ export async function resolveGeneratedMedia(
       console.log(`  🔊 ${label}: ${labelText}...`);
       const ttiCmd = clone.tti ?? options.ttiCli ?? DEFAULT_TTI_CLI;
       const result = type === "image"
-        ? generateTTI(prompt, outputPath, cli)
-        : generateTTV(prompt, outputPath, cli, ttiCmd);
+        ? generateTTI(prompt, outputPath, cli, seed)
+        : generateTTV(prompt, outputPath, cli, ttiCmd, seed);
       if (result) {
         node.src = outputPath;
         updateCache(cache, `gen:${cacheKey}`, cacheKey, outputPath);
@@ -782,6 +790,8 @@ export interface ResolveAllOptions extends ResolveMediaOptions {
   ttiCli?: string;
   /** TTV CLI template override (default: pi agent). Overrides root.ttv. */
   ttvCli?: string;
+  /** Global seed for reproducible TTI/TTV generation. Inherited by includes. */
+  seed?: number;
   /** If set, resolve includes. Directory where pre-compiled include JSON files are stored. */
   includeOutputDir?: string;
   /** Separate output dir for the merged subtitles.vtt.
@@ -973,12 +983,15 @@ export async function resolveAll(
   // (e.g. photo_${width}x${height}.jpg), find the closest existing file.
   result = await resolveMediaSrcs(result, { baseDir: options.baseDir });
 
-  // Step 3: Generate images/videos from prompts before probing durations
+  // 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;
   if (options.mediaOutputDir) {
     result = await resolveGeneratedMedia(result, {
       outputDir: options.mediaOutputDir,
       ttiCli: options.ttiCli,
       ttvCli: options.ttvCli,
+      seed: generationSeed,
     });
   }
 

package/src/render/cli-tools.ts

@@ -40,8 +40,13 @@ export { DEFAULT_TTS_CLI, DEFAULT_STT_CLI, DEFAULT_TTI_CLI, DEFAULT_TTV_CLI };
  *
  *   template: --text '{input}'     input: it's "great"
  *     →       --text 'it'\''s "great"'
+ *
+ * Placeholders:
+ *   {input}  — user text/path (quote-aware escaped)
+ *   {output} — output file path (simple escaped)
+ *   {seed}   — integer seed for reproducible generation (or empty string)
  */
-function substituteCli(template: string, input: string, output: string): string {
+function substituteCli(template: string, input: string, output: string, seed?: number): string {
   // Escape the output value (file paths rarely have quotes, but be safe)
   const safeOutput = output;
 
@@ -63,9 +68,15 @@ function substituteCli(template: string, input: string, output: string): string
     safeInput = input.replace(/"/g, '\\"').replace(/'/g, "'\\''");
   }
 
+  // {seed} is always a simple integer — no escaping needed beyond providing
+  // a sensible default. If not set, emit empty string so CLI flags like
+  // "--seed {seed}" become "--seed " (harmless for tools that ignore empty flags).
+  const safeSeed = seed !== undefined ? String(seed) : "";
+
   return template
     .replace(/\{input\}/g, safeInput)
-    .replace(/\{output\}/g, safeOutput);
+    .replace(/\{output\}/g, safeOutput)
+    .replace(/\{seed\}/g, safeSeed);
 }
 
 // ── Exported functions ────────────────────────────────────────────────────
@@ -101,11 +112,12 @@ export async function generateSTT(audioPath: string, outputDir: string, cli?: st
 
 /**
  * Generate an image from a text prompt.
+ * @param seed Optional seed for reproducible generation. Substituted into {seed} in the CLI template.
  * @returns output path on success, empty string on failure.
  */
-export function generateTTI(prompt: string, outputPath: string, cli?: string): string {
+export function generateTTI(prompt: string, outputPath: string, cli?: string, seed?: number): string {
   mkdirSync(dirname(outputPath), { recursive: true });
-  const cmd = substituteCli(cli ?? DEFAULT_TTI_CLI, prompt, outputPath);
+  const cmd = substituteCli(cli ?? DEFAULT_TTI_CLI, prompt, outputPath, seed);
   try {
     execSync(cmd, {
       encoding: "utf-8",
@@ -128,6 +140,7 @@ export function generateTTI(prompt: string, outputPath: string, cli?: string): s
  * to create an image from the prompt, then uses ffmpeg to produce a 3-second MP4.
  *
  * @param ttiCmd Optional TTI CLI template for the image step (defaults to DEFAULT_TTI_CLI).
+ * @param seed Optional seed for reproducible generation. Substituted into {seed} in the CLI template.
  * @returns output path on success, empty string on failure.
  */
 export function generateTTV(
@@ -135,13 +148,14 @@ export function generateTTV(
   outputPath: string,
   cli?: string,
   ttiCmd?: string,
+  seed?: number,
 ): string {
   mkdirSync(dirname(outputPath), { recursive: true });
 
   if (!cli) {
     // Default: use generateTTI to create an image, then ffmpeg to make a 3s MP4
     const pngPath = outputPath.replace(/\.mp4$/, ".png");
-    const imageResult = generateTTI(prompt, pngPath, ttiCmd);
+    const imageResult = generateTTI(prompt, pngPath, ttiCmd, seed);
     if (!imageResult || !existsSync(imageResult)) {
       console.error(`  ✗ TTV: TTI step produced no image for "${prompt.slice(0, 50)}..."`);
       return "";
@@ -161,7 +175,7 @@ export function generateTTV(
   }
 
   // Custom CLI mode: substitute template and run
-  const cmd = substituteCli(cli, prompt, outputPath);
+  const cmd = substituteCli(cli, prompt, outputPath, seed);
   try {
     execSync(cmd, {
       encoding: "utf-8",

package/src/schema/index.ts

@@ -74,6 +74,7 @@ export const root = folder.extend({
   fps: z.number().int().positive().default(30),
   instruction: z.string().optional(),
   metadata: z.string().optional(),
+  seed: z.number().optional().describe("global seed for TTI/TTV generation; substituted into CLI {seed} placeholder"),
   stylesheet: z.string().optional().describe("global css; selectors use .type and .name"),
   subtitle: subtitleOverlay.optional().describe("global subtitle overlay; src is a VTT file with absolute timestamps"),
   /**

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

@@ -1,539 +0,0 @@
-# JSON Descriptive (Canonical IR)
-
-Complete reference for LLM-driven video generation. Emit valid JSON only.
-
-## Output Contract
-
-A single root object describing a renderable video:
-
-- Required at root: `width`, `height`, `fps`, `layout`, `children`
-- `children` is an array of nodes (see Type Catalog)
-- Every `scene` / container must have non-empty `children`
-- Timing is resolved bottom-up; containers derive duration from children
-
-## Type Catalog
-
-### `scene` — storyboard organizer (preferred top-level node)
-
-When to use: always. Scenes are the default organizational unit. They render as folders but carry narrative metadata.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"scene"` | |
-| `name` | yes | string | unique scene identifier |
-| `layout` | yes | `"series"\|"parallel"\|"transitionSeries"` | |
-| `children` | yes | node[] | must be non-empty |
-| `transition` | opt | `"fade"\|"slide"\|"wipe"\|"flip"\|"clockWipe"` | only for transitionSeries |
-| `transitionTime` | opt | number | seconds (default 0.5) |
-| `instruction`,`script`,`style` | opt | | metadata |
-| `on` | opt | `{ when, state }` | Event spec that fires at a specific frame |
-
-> **`scene` is a container.** It supports nesting: a scene can hold other scenes, containers, or leaves. Use nested scenes for chapters, acts, or grouped beats.
-
-Example of nested scenes:
-
-```json
-{
-  "type": "scene",
-  "name": "Chapter2",
-  "layout": "series",
-  "children": [
-    { "type": "scene", "name": "Feature1", "layout": "parallel", "children": [ ... ] },
-    { "type": "scene", "name": "Feature2", "layout": "parallel", "children": [ ... ] }
-  ]
-}
-```
-
-### `video`
-
-When to use: any moving footage (.mp4, .mov, etc.).
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"video"` | |
-| `src` | yes | string | path/URL |
-| `duration` | cond | number | required if no `endAt` |
-| `startFrom` | opt | number | trim from source start (sec) |
-| `endAt` | opt | number | trim at source position; effective length = `endAt − startFrom` |
-| `start` | opt | number | parallel only |
-| `volume` | opt | number 0–1 | default 1 |
-| `playbackRate` | opt | number | |
-| `width`,`height` | opt | number | default 1080×1920 |
-| `instruction`,`script`,`style` | opt | | metadata |
-| `on` | opt | `{ when, state }` | Event spec that fires at a specific frame |
-| `effects` | opt | `string[]` or `object[]` | **New** — apply animations directly: `["fadeIn"]` or `[{animation:"bounceIn",animationTimingFunction:"ease-out"}]` |
-
-### `audio`
-
-When to use: voiceover, BGM, SFX.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"audio"` | |
-| `src` | yes | string | |
-| `duration` | cond | number | required if no `endAt` |
-| `startFrom`,`endAt` | opt | number | trim |
-| `volume` | opt | number 0–1 | |
-| `loop` | opt | int | loop count >1 |
-| `foreground` | opt | bool | ducks parent video audio |
-| `start` | opt | number | parallel only |
-| `on` | opt | `{ when, state }` | Event spec that fires at a specific frame |
-| `effects` | opt | `string[]` or `object[]` | **New** — apply animations directly |
-
-### `image`
-
-When to use: photos, stills, title cards.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"image"` | |
-| `src` | yes | string | |
-| `duration` | yes | number | no intrinsic duration |
-| `fit` | opt | `"contain"\|"cover"\|"fill"` | default `contain` |
-| `start` | opt | number | parallel only |
-| `on` | opt | `{ when, state }` | Event spec that fires at a specific frame |
-
-### `subtitle` (root-level overlay)
-
-When to use: captions, on-screen text, karaoke. Set as `root.subtitle` — not a tree node.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `src` | yes | string | VTT file path/URL, inline VTT body, or plain text |
-| `type` | opt | string | caption animation component: `Bounce`, `Fade`, `Typewriter`, `Colorful`, `Glowing`, `Neon`, etc. Default: plain `Caption` |
-| `style` | opt | string | inline CSS for the overlay container |
-| `fontSize` | opt | number\|string | default 56 |
-| `fontFamily` | opt | string | font family for subtitle text |
-| `fontStyle` | opt | string | `normal`, `italic`, `bold`, `bold italic`, etc. |
-
-> **HTML in cue text**: VTT cue text supports HTML tags with inline CSS for per-word styling:
-> ```vtt
-> 00:00:01.000 --> 00:00:03.000
-> The <span style="color:#ff6b6b;font-weight:bold">quick</span> brown <span style="font-style:italic">fox</span>
-> ```
-> Tags like `<span>`, `<b>`, `<i>`, `<br>`, and inline `style` attributes all work. The `Typewriter` caption type respects HTML tag boundaries during character reveal.
-
-If `src` is plain text (no `-->`), renders as a single static caption for the entire video duration. The `type` field selects an animated caption component from `remotion-subtitle` — omit for a plain static caption.
-
-### `component`
-
-When to use: JSX expression rendered at runtime with frontmatter imports in scope.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"component"` | |
-| `jsx` | yes | string | JSX usage expression, e.g. `"<BarChart data={...} />"` |
-| `duration` | yes | number |
-| `id` | opt | string | Required for event targeting — registers component in event context |
-| `on` | opt | `{ when, state }` | Event spec that fires at a specific frame |
-| `effects` | opt | `string[]` or `object[]` | **New** — apply animations directly |
-
-### `rhythm`
-
-When to use: beat-synced audio (music drops, music-reactive reveals). Duration is derived from `spots` — no explicit `duration` needed.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"rhythm"` | |
-| `src` | yes | string | audio file |
-| `spots` | yes | number[] | beat timestamps (sec); must have ≥2 entries |
-| `children` | yes | node[] | one child per beat slot; child[i] starts at spots[i], ends at spots[i+1] |
-| `volume` | opt | number 0–1 | default 1 |
-
-Duration = `spots[last] + average_gap`. Equivalent to how long the last child plays.
-
-### `effects` (on any node)
-
-Apply CSS keyframe animations directly via the `effects` field — no wrapper node needed.
-
-Each entry is an animation name (string) with optional comma-separated positional parameters inside parentheses:
-
-```json
-{
-  "type": "image",
-  "src": "hero.jpg",
-  "duration": 3,
-  "effects": ["fadeIn", "bounceIn(1.5, ease-out, 2)"]
-}
-```
-
-Parameter order: `(duration, timingFunction, iterationCount)` — all optional.
-
-Built-in animation names:
-
-- **Fades**: `fadeIn`, `fadeOut`, `fadeInDown`, `fadeInUp`, `fadeInLeft`, `fadeInRight`, `fadeOutDown`, `fadeOutUp`, `fadeOutLeft`, `fadeOutRight`
-- **Slides in**: `slideInDown`, `slideInUp`, `slideInLeft`, `slideInRight`
-- **Slides out**: `slideOutDown`, `slideOutUp`, `slideOutLeft`, `slideOutRight`
-- **Zooms**: `zoomIn`, `zoomOut`, `zoomInDown`, `zoomInUp`, `zoomInLeft`, `zoomInRight`
-- **Bounces**: `bounce`, `bounceIn`
-- **Rotations**: `rotateIn`, `rotateOut`, `rotateInDownLeft`, `rotateInDownRight`, `rotateInUpLeft`, `rotateInUpRight`
-- **Flips**: `flipInX`, `flipInY`
-- **Attention**: `pulse`, `flash`, `heartBeat`, `rubberBand`, `shakeX`, `shakeY`, `swing`, `tada`, `wobble`, `jello`
-- **Specials**: `rollIn`, `rollOut`, `jackInTheBox`, `lightSpeedIn`, `lightSpeedOut`
-
-See [Markdown Descriptive](markdown-descriptive.md#effects-on-any-node) for the full syntax reference.
-
-### `map`
-
-When to use: animated route visualization (Google Maps).
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"map"` | |
-| `waypoints` | yes | `{lat,lng,label?,media?}[]` | min 2 for routing |
-| `duration` | yes | number | |
-| `travelMode` | opt | `"DRIVING"\|"WALKING"\|"BICYCLING"\|"TRANSIT"` | |
-| `mapType` | opt | `"roadmap"\|"satellite"\|"hybrid"\|"terrain"` | |
-| `routeMarker`,`routeColor`,`routeWeight`,`zoom`,`center` | opt | | styling |
-
-### `include`
-
-When to use: embed an external markdown file as a sub-video.
-
-In the **descriptive form**, `src` points to a `.md` file. The pipeline
-resolves it recursively: parses the markdown, runs TTS/media/includes,
-compiles to a stream tree JSON (cached at `.markcut/generated/includes/`),
-and bundles any component imports independently.
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `type` | yes | `"include"` | |
-| `src` | cond | string | path to `.md` file (descriptive) or compiled `.json` |
-| `children` | opt | node[] | inline fallback if no `src` |
-| `duration` | cond | number | optional — auto-detected from compiled sub-video |
-| `volume` | opt | number | |
-
-> **Component isolation:** The sub-video's `imports` are bundled to
-> `.markcut/<sub-basename>/components/<hash>.js` and loaded at render
-> time in a nested `ComposeContext`, so sub-video components don't
-> conflict with parent components.
-
-## Imports
-
-External React components are registered via `root.imports`. In the **descriptive** form (input to the pipeline), it's an array of import entries. In the **compiled** form (output of the server pipeline, consumed by the player), it's a string URL pointing to a pre-bundled ESM module.
-
-### Descriptive form (input)
-
-```json
-{
-  "imports": [
-    { "name": "BarChart", "from": "@nivo/bar" },
-    { "name": "Logo", "from": "git:myorg/assets/src/Logo.tsx" },
-    { "name": "Greeting", "jsx": "export default ({name}) => <h1 style={{color:'#fff'}}>Hello {name}</h1>" }
-  ]
-}
-```
-
-### Import entry fields
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `name` | yes | string | component name — used as JSX tag in usage expressions |
-| `from` | cond | string | source spec (see below); alternative to `jsx` |
-| `jsx` | cond | string | inline component definition source (e.g. `"export default ({text}) => <span>{text}</span>"`) |
-| `exports` | opt | string | named export to pick from the module (default: `"default"`) |
-
-### `from:` spec forms (descriptive form)
-
-| Pattern | Resolved by bundler as |
-|---|---|
-| `pkg` or `npm:pkg` | npm package — `npm install pkg`, then `esbuild` re-exports it |
-| `pkg@1.2.3` or `npm:pkg@1.2.3` | npm package with pinned version |
-| `@scope/pkg` or `npm:@scope/pkg` | npm scoped package |
-| `git:user/repo/path` | Raw specifier passed to esbuild; requires the module to be resolvable |
-| `github:user/repo/path` | Same as `git:` |
-| `https://...`, `http://...` | Raw URL passed directly to esbuild as an external |
-| local path | Filesystem path relative to the bundle project |
-
-### Imports block (markdown only)
-
-The `` ```js imports `` or `~~~js imports` code block is a markdown-only feature. See [Markdown Descriptive](markdown-descriptive.md) for the full reference.
-
-### Using imports in component nodes
-
-Components reference imports by name as JSX tags in the usage expression. The compiler passes the resolved `imports` map through to the stream node for runtime resolution:
-
-```json
-{
-  "type": "component",
-  "jsx": "<BarChart data={[{name:'A',value:80},{name:'B',value:60},{name:'C',value:40}]} keys={['value']} indexBy='name' />",
-  "duration": 4
-}
-```
-
-Inline `jsx:` definitions in the imports array are also available as JSX tags in usage expressions:
-
-```json
-{
-  "imports": [
-    { "name": "Greeting", "jsx": "export default ({name}) => <h1 style={{color:'#fff'}}>Hello {name}</h1>" }
-  ]
-}
-// ...
-{ "type": "component", "jsx": "<Greeting name='World' />", "duration": 2 }
-```
-
-> Components defined via `jsx:` inline definitions are bundled by the player server at startup and loaded as a single ESM module. They have access to `useCurrentFrame()`, `interpolate()`, and other Remotion hooks via the bundled module's imports.
-
-### Imports in markdown
-
-The markdown descriptive format supports the same `imports:` array in YAML frontmatter, plus ` ```jsx Name ` code fence blocks for inline definitions. See [Markdown Strict Descriptive](markdown-strict-descriptive.md#component) for details.
-
-## Events
-
-Fire a JavaScript expression at a specific frame to mutate a registered component's state. Useful for syncing UI state with narration beats.
-
-### Registering a component
-
-Add an `id` to a component node to register it in the global event context:
-
-```json
-{
-  "type": "component",
-  "jsx": "<Slide current={current}>{source}</Slide>",
-  "duration": 4,
-  "id": "slide1"
-}
-```
-
-The `id` becomes the variable name available in event expressions.
-
-### Event spec
-
-Any node can carry an `on` field with the following shape:
-
-| Field | Required | Type | Notes |
-|---|---|---|---|
-| `when` | yes | string | Frame selector: `"start"`, `"end"`, `"50%"`, `"2.5s"`, etc. |
-| `state` | yes | string | JavaScript expression evaluated with registered component proxies in scope |
-
-### Examples
-
-```json
-{
-  "type": "scene",
-  "children": [
-    {
-      "type": "audio",
-      "script": "Narration 1",
-      "duration": 3,
-      "on": { "when": "start", "state": "slide1.current=0" }
-    },
-    {
-      "type": "audio",
-      "script": "Narration 2",
-      "duration": 2,
-      "on": { "when": "start", "state": "slide1.current++" }
-    }
-  ]
-}
-```
-
-The expression is evaluated with all registered component IDs as scope variables. Each component variable is a Proxy whose property setter triggers a React re-render on the corresponding component node.
-
-## Common Metadata Fields
-
-Available on every node:
-
-| Field | Type | Purpose |
-|---|---|---|
-| `id` | string | unique within parent scope; required for referencing |
-| `instruction` | string | visual intent or style guide; not rendered |
-| `script` | string | narration/dialogue text — TTS source; only meaningful on `scene` nodes |
-| `style` | string | inline CSS (semicolon-separated); applied to the node's container div, e.g. `"border-radius:16px; opacity:0.9"` |
-| `visible` | bool | default `true`; set `false` to hide without removing |
-| `isBackground` | bool | when `true`, node loops to fill parent duration and does **not** contribute to container duration calculation — use for BGM, looping background imagery |
-| `on` | object `{ when, state }` | Event spec that fires a JS expression at a specific frame, mutating registered component state — see [Events](#events-1) section |
-
-> **`style` tip:** applies to the wrapping container, not the inner media element. Use for positioning, sizing, and opacity overrides.
-> **`isBackground` tip:** use for audio tracks, looping video overlays, or any element that should play across the full parent duration.
-
-## Timing Rules
-
-1. `duration` is authoritative for non-trimmed leaves.
-2. For `video`/`audio`: if `startFrom`+`endAt` present, clip length = `endAt − startFrom`.
-3. `start` allowed only inside `parallel`.
-4. `transitionTime` subtracted between items in `transitionSeries`.
-5. `isBackground` children do not contribute to parent duration.
-
-## Style
-
-Each node accepts a `style` string for inline CSS on its container div. Available on every node:
-
-| Field | Type | Purpose |
-
-TTS, STT, TTI, and TTV are each configured via a **single CLI template string**. The LLM embeds every tool-specific parameter (voice, model, rate, size, style, etc.) directly in the string — only the built-in variables below are substituted by the engine.
-
-**Root level** — sets defaults for all scenes:
-```json
-{
-  "tts": "edge-tts --voice \"en-US-GuyNeural\" --text \"{input}\" --write-media \"{output}\"",
-  "stt": "whisper \"{input}\" --output_format vtt --output_dir \"{outputDir}\""
-}
-```
-
-**Per scene** — narration via audio child with `script`:
-```json
-{
-  "type": "scene",
-  "children": [
-    { "type": "audio", "script": "Hello world", "volume": 1 },
-    ...
-  ]
-}
-```
-
-**Precedence:** scene-level `tts` → root-level `tts` → pipeline option → hardcoded default.
-
-### Built-in Variables
-
-| Variable | Applies To | Description |
-|---|---|---|
-| `{input}` | TTS, TTI, TTV | Input content: narration text (TTS), generation prompt (TTI, TTV), audio file path (STT) |
-| `{output}` | All | Output location: file path for TTS/TTI/TTV, directory for STT VTT files |
-
-### Defaults & Prerequisites
-
-| Pipeline | Field | Default CLI | Prerequisite |
-|---|---|---|---|
-| **Text-to-Speech** | `tts` | `edge-tts --voice "en-US-GuyNeural" --text "{input}" --write-media "{output}"` | `edge-tts` (`pip install edge-tts`) |
-| **Speech-to-Text** | `stt` | `whisper "{input}" --output_format vtt --output_dir "{output}"` | `openai-whisper` (`pip install openai-whisper`) |
-| **Text-to-Image** | `tti` | `pi --model agnes-2.0-flash --print "generate image: {input}" --output "{output}"` | `pi` CLI (`pip install pi-sdk`) |
-| **Text-to-Video** | `ttv` | `pi --model agnes-2.0-flash --print "generate video: {input}" --output "{output}"` | `pi` CLI (`pip install pi-sdk`) |
-
-### Notes
-
-- Only the 2 variables listed above (`{input}` and `{output}`) are substituted. All other parameters (voice, model, rate, size, style, language, etc.) must be written verbatim into the CLI string.
-- To use a different TTS engine (e.g. mlx-audio, piper), simply pass its full command as `tts`:
-  ```json
-  { "tts": "mlx-audio tts --model speecht5 --text "{input}" --ref-audio ./voice.wav --output "{output}"" }
-  ```
-
-## Tween Animation
-
-Animate numeric props over time using `tween(from?, to, easing?)` expressions in component props. Tweens resolve at render time using Remotion's `interpolate()`, producing smooth frame-by-frame animation.
-
-### Syntax
-
-```
-tween(to)                     — 0 → to, linear
-tween(from, to)               — from → to, linear
-tween(from, to, easeOut)      — from → to, with easing
-tween(from, to, spring)       — from → to, spring animation
-tween(from, to, spring(damping:12)) — spring with custom params
-tween(#000, #FFF)             — color hex → hex
-tween(#000, #FFF, easeInOut)  — color hex with easing
-```
-
-### Usage in JSX expressions
-
-Place `tween(...)` expressions inside JSX usage expressions. The engine compiles the JSX at runtime and resolves each `tween()` call to an animated number at each frame:
-
-```json
-{
-  "type": "component",
-  "jsx": "<BarChart data={[{name:'A',value:tween(0,80)},{name:'B',value:tween(0,60)},{name:'C',value:tween(0,40)}]} keys={['value']} indexBy='name' />",
-  "duration": 4
-}
-```
-
-This animates the bars from 0 to their target heights over 4 seconds. At frame 0 all values are 0; they interpolate linearly to 80, 60, 40 by the end.
-
-You can also use `tween()` in inline SVG expressions:
-
-```json
-{
-  "type": "component",
-  "jsx": "<svg viewBox='0 0 400 300'><rect y={260 - tween(0, 200)} width={80} height={tween(0, 200)} fill='#E38627' /></svg>",
-  "duration": 4
-}
-```
-
-### Supported easings
-
-| Name | Remotion mapping |
-|---|---|
-| `linear` (default) | identity |
-| `ease`, `easeIn` | `Easing.in(Easing.ease)` |
-| `easeOut` | `Easing.out(Easing.ease)` |
-| `easeInOut` | `Easing.inOut(Easing.ease)` |
-| `spring` | `spring()` from remotion |
-| `spring(damping:N, mass:N)` | spring with custom config |
-
-### Color tween
-
-Hexadecimal colors can be interpolated:
-
-```json
-{ "fill": "tween(#000000, #ff0000)" }
-```
-
-### Important notes
-
-- Tween values only work inside `component` nodes (not on `image`, `video`, `audio`, etc.).
-- The frame range is derived from the **action duration** (the `duration` field for the component minus its `start` offset).
-- The `tween()` function uses Remotion's `interpolate()` under the hood, with the frame range set to the component's action duration.
-- At frame 0, `tween(from, to)` returns `from`. The component receives the initial value immediately.
-
-## Generation Workflow
-
-1. Choose `width`/`height`/`fps`/`layout`/`theme`.
-2. Break the video into 3–7 `scene` nodes.
-3. For each scene: write `script` (narration, TTS source) and `instruction` (visual intent). Only `scene` nodes carry `script` — leaf nodes ignore it. When scenes nest, the **innermost** scene's `script` wins; parent scenes with nested `script` children are skipped to prevent overlapping narration.
-4. Add leaf nodes inside scenes.
-5. Add transitions only between scene-grouped sequences.
-6. Verify every leaf has resolvable duration.
-
-## Validation Checklist
-
-- [ ] Root has width, height, fps, layout, children.
-- [ ] Every scene/container has non-empty children.
-- [ ] Every video/audio/image/map/component has duration or trim.
-- [ ] No `start` outside parallel.
-- [ ] No duplicate `id` within the same parent.
-- [ ] Event targets (`"id": "name"` on component) match the `"id"` used in `on.when` / `on.state` expressions.
-- [ ] All JSON is valid (no comments, no trailing commas).
-
-## Example
-
-```json
-{
-  "width": 1080,
-  "height": 1920,
-  "fps": 30,
-  "layout": "series",
-  "theme": "neon",
-  "children": [
-    {
-      "type": "scene",
-      "title": "Hook",
-      "layout": "parallel",
-      "children": [
-        { "type": "audio", "script": "A short memory film", "volume": 1 },
-        { "type": "image", "src": "cover.jpg", "duration": 2 },
-        { "type": "image", "src": "intro.jpg", "duration": 1.6, "start": 0.2 }
-      ]
-    },
-    {
-      "type": "scene",
-      "title": "Journey",
-      "layout": "transitionSeries",
-      "transition": "fade",
-      "transitionTime": 0.4,
-      "children": [
-        { "type": "audio", "script": "Set location and emotional tone", "volume": 1 },
-        { "type": "video", "src": "clips/arrival.mp4", "startFrom": 0, "endAt": 3.5 },
-        { "type": "video", "src": "clips/fire.mp4", "startFrom": 1, "endAt": 4 }
-      ]
-    },
-    {
-      "type": "scene",
-      "title": "Stat",
-      "layout": "parallel",
-      "children": [
-        { "type": "component", "jsx": "<StatCounter value={42} label='S-mores' />", "duration": 2 }
-      ]
-    }
-  ]
-}
-```