videowright 0.1.0

package/skill/references/audio/voiceover/sync_algorithm.md

@@ -0,0 +1,167 @@
+# Sync Algorithm
+
+## When this is loaded
+
+You have a voiceover audio file and provider timing data, and you need to compute a `Timing` object that syncs segment advances to the audio.
+
+## Overview
+
+This is an agent reasoning step, not a deterministic function. You read the per-word timing data from the provider, walk the per-segment script from PLAN.md, and produce a `Timing` object with advance times for each segment.
+
+## Inputs
+
+1. **Per-segment script** from PLAN.md (the `## Script` section with subsections per segment id).
+2. **Provider timing JSON** at `audio/originals/voiceovers/<slug>/timing.json`. This contains per-word or per-character timestamps from the TTS provider or STT transcription.
+3. **Segment ids** in timeline order, plus each segment's `notes` and `voiceover` hint string.
+4. **Each segment's `advances` array** -- the current timing. You will be replacing these values in the `Timing`, but the array length tells you how many advances each segment needs.
+
+## Output
+
+A `Timing` object written into `voiceover.ts`:
+
+```ts
+timing: {
+  perSegment: {
+    'intro':          [4.2],
+    'feature-cards':  [2.1, 5.8, 9.3, 12.0],
+    'outro':          [3.5],
+  },
+},
+```
+
+Each value array has the same length as the segment's `advances` array. Values are segment-relative seconds (same units as `SegmentSpec.advances`).
+
+## Parsing provider timing JSON
+
+### ElevenLabs TTS timing
+
+ElevenLabs TTS can output per-word timing (via the API's with-timestamps endpoint, or extracted via STT after portal generation). The JSON format contains an array of word entries with start and end timestamps:
+
+```json
+{
+  "words": [
+    { "word": "Welcome", "start": 0.0, "end": 0.45 },
+    { "word": "to", "start": 0.47, "end": 0.55 },
+    { "word": "Acme", "start": 0.58, "end": 0.92 },
+    ...
+  ]
+}
+```
+
+Timestamps are in seconds from the start of the audio file. The `end` of the last word in a segment's script section gives you the boundary for that segment's audio content.
+
+### ElevenLabs Speech-to-Text timing
+
+ElevenLabs STT output has a similar structure with word-level timestamps. The format may include additional fields like confidence scores -- ignore those. Focus on `word`, `start`, and `end`.
+
+If the JSON structure differs from the above (ElevenLabs may update their format), adapt by looking for word-level entries with start/end time fields. The core need is: which word was spoken at which timestamp.
+
+## The sync procedure
+
+### Step 1: Map script text to timing words
+
+Walk through the provider timing JSON word by word. For each segment's script section in PLAN.md, find the corresponding words in the timing data by text matching.
+
+- Match is case-insensitive and ignores punctuation.
+- Provider timing may include words from pause markers or annotations that were in the provider script but not the PLAN script -- skip those.
+- If the provider timing has significantly different text (indicating the TTS changed wording), flag this to the user and ask which text to use.
+
+### Step 2: Find segment boundaries
+
+For each segment, identify the timestamp where the segment should transition to the next:
+
+- **Align to the next segment's VO onset, not the current segment's VO offset.** Each segment's final advance should land just *before* the next segment's first spoken word, so the voiceover starts right after the transition -- not after a dead-air pause. The transition is a lead-in to the next VO, not a tail-out from the previous one.
+- Find the first word of the *next* segment's script section. Place the segment boundary 0.1-0.3 seconds before that word's `start` timestamp, so the transition finishes right as the new narration begins.
+- For the **last segment** (no next segment), find the last word in the segment's script section and add a small buffer (0.3-0.5 seconds) after its `end` timestamp.
+
+### Step 3: Convert to segment-relative advances
+
+The `Timing` uses segment-relative seconds (time since the segment started, not since the audio started). To convert:
+
+```
+segment_start = sum of all previous segments' durations
+advance_time = absolute_timestamp - segment_start
+```
+
+For the last advance of each segment (the one that transitions to the next segment), set it so the transition lands just before the next segment's first VO word (per Step 2).
+
+### Step 4: Handle multi-advance segments
+
+Segments with multiple advances have internal beats (`waitForNext()` calls in their `play()` function). For these:
+
+1. **Count the advances.** The segment's `advances` array length tells you how many beats are needed.
+2. **Identify beat positions.** Look for natural break points in the segment's script:
+   - `[pause for animation]` markers in the PLAN.md script.
+   - Sentence boundaries that align with visual transitions (check the segment's `notes` or code).
+   - Content transition cues: "Next,...", "And now,...", "Finally,...", "Moving on,...".
+3. **Place internal advances** at the timestamps corresponding to these break points. Each internal advance should land at the end of the narration chunk before the next visual beat.
+4. **Place the final advance** (the segment transition) just before the next segment's first VO word, per Step 2.
+
+Example for a segment with 4 advances:
+
+```
+Script: "First feature. [pause] Second feature. [pause] Third feature."
+Advances array length: 4 (3 internal beats + 1 final transition)
+
+advance[0] = end of "First feature" + buffer   (first waitForNext resolves)
+advance[1] = end of "Second feature" + buffer  (second waitForNext resolves)
+advance[2] = end of "Third feature" + buffer   (third waitForNext resolves)
+advance[3] = just before next segment's first VO word (transition to next segment)
+```
+
+### Step 5: Apply the "audio always wins" rule
+
+The video duration adapts to match the audio duration:
+
+- If the audio for a segment is shorter than the segment's current `advances` suggest, compress the advances.
+- If the audio is longer, stretch the advances.
+- The last advance of the last segment should land at (or very near) the end of the audio file.
+- Never truncate audio. Never pad with silence.
+
+## Presenting the timing to the user
+
+After computing the `Timing`, present it with annotations:
+
+```
+Proposed timing:
+
+  intro (1 advance):
+    [0] 4.2s -- "...set us apart." (end of intro narration)
+
+  feature-cards (4 advances):
+    [0] 2.1s -- "...across devices." (end of collaboration section)
+    [1] 5.8s -- "...in one view." (end of analytics section)
+    [2] 9.3s -- "...and more." (end of integrations section)
+    [3] 12.0s -- transition (next VO starts at ~12.2s)
+
+  outro (1 advance):
+    [0] 3.5s -- "...Thanks for watching." (end of video)
+
+  Total audio duration: 19.7s
+```
+
+For each advance, show:
+
+- The segment-relative time in seconds.
+- A snippet of the script text that the advance lands on.
+- What the advance does (internal beat vs. segment transition).
+
+## Iteration
+
+The user may request adjustments:
+
+- "Move the second beat in feature-cards 0.5 seconds later" -- adjust that advance value.
+- "The intro feels rushed" -- extend the intro's advance time by adding more buffer.
+- "Combine the first two beats in feature-cards into one" -- this changes the number of advances, which means the segment's `play()` function needs a `waitForNext()` removed. Flag this as a code change.
+
+After each adjustment, re-present the timing. When the user confirms, write it into `voiceover.ts`.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| Provider timing JSON is missing | Error. The user must download it from the provider portal. Direct them to the provider walkthrough. |
+| Words in timing do not match the script | Likely the TTS changed wording. Flag specific mismatches, ask user whether to use TTS text or original script text for alignment. |
+| Segment has no script (silent segment) | Use the segment's existing `advances` values. The segment passes through without voiceover. |
+| Audio is significantly shorter/longer than expected | Apply "audio always wins" -- compress or stretch. Flag the discrepancy so the user can decide if they want to re-record or adjust the video. |
+| Provider timing has character-level rather than word-level data | Aggregate characters into words by grouping on whitespace boundaries. Use the word-end timestamp. |

package/skill/references/audio/voiceover.md

@@ -0,0 +1,296 @@
+# Voiceover
+
+## When this is loaded
+
+You were routed here from [audio.md](../audio.md) or from another workflow that needs to work with voiceover content. This is the top-level reference for all voiceover functionality.
+
+## Overview
+
+Videowright supports voiceover audio integrated into video playback. A voiceover consists of an audio file (mp3 or wav), a `Timing` that syncs segment advances to the audio, and metadata stored in a typed `voiceover.ts` file. Audio plays in the dev server via an HTML `<audio>` element and is muxed into MP4 output by `render` via ffmpeg.
+
+Two production flows are supported:
+
+- **AI-generated** -- write a script, transform it with v2-targeted provider annotations, generate audio via ElevenLabs (API key or web portal), and import the audio and per-word timing JSON.
+- **Manual** -- user provides their own audio file, then runs it through ElevenLabs Speech-to-Text to get per-word timing data for sync.
+
+Both flows produce the same output: a `voiceover.ts` file with a `Voiceover` object that includes the audio path and a `Timing` object.
+
+## Flow entry point
+
+When the user asks to "add a voiceover" or "generate a voiceover", ask:
+
+> Do you have an audio file already, or would you like to generate one with AI text-to-speech?
+
+- **AI generation** -- follow Flow A below.
+- **User-provided audio** -- follow Flow B below.
+
+### Flow A: AI generation (ElevenLabs)
+
+1. **Approach and voice selection.** Ask API key vs. portal, then (API only) which voice from the curated catalog. See [voiceover/providers/elevenlabs.md](voiceover/providers/elevenlabs.md) for the mode selection prompt and [voice catalog](#curated-voice-catalog).
+2. **Style intake.** Ask the user about tone and emotional arc preferences. See [voiceover/style_intake.md](voiceover/style_intake.md).
+3. **Script.** Write or integrate the VO script into PLAN.md. See [voiceover/script_writing.md](voiceover/script_writing.md).
+4. **Provider script.** Transform the PLAN script into `provider_script.md` with v2-targeted annotations (SSML `<break>` tags, punctuation-driven prosody -- no v3 emotion tags). See [voiceover/provider_script.md](voiceover/provider_script.md).
+5. **Audio generation.** Follow the sub-flow for the approach chosen in step 1. See [voiceover/providers/elevenlabs.md](voiceover/providers/elevenlabs.md).
+6. **Sync timing.** Read the provider timing JSON and compute a `Timing` object. See [voiceover/sync_algorithm.md](voiceover/sync_algorithm.md).
+7. **Write `voiceover.ts`.** Create the typed module exporting a `Voiceover` object.
+8. **Audio plan and build.** Create or update `audio/audio_plan.md` with a VO cue pointing at this voiceover. For VO-only videos, the plan is minimal (single cue, full file, placed at 0s -- see [audio_plan.md](audio_plan.md) for the VO-only shortcut). Then build the track via [build.md](build.md). The build workflow handles approval, timeline.ts update, and sync.
+
+### Curated voice catalog
+
+When the user picks the **API key** approach in step 1, immediately present this catalog (default is **Asher** if no preference):
+
+| # | Voice | Description | Preview |
+|---|---|---|---|
+| 1 | **Asher** | Warm, clear, and conversational male voice with confident, grounded delivery. Natural pacing and friendly authority give him an engaging presence that holds attention without feeling forced. Ideal for podcasts, narration, explainers, and authentic commercial reads. Works especially well as a default voice because of his versatility across different content types and tones. | [Listen](https://elevenlabs.io/app/voice-library?voiceId=tMvyQtpCVQ0DkixuYm6J) |
+| 2 | **Cecily** | Warm, versatile female voice from the West Coast with an engaging, approachable delivery. Her natural warmth and conversational style make her equally effective for advertisements, social media content, and brand storytelling. She can shift between polished and casual registers without losing authenticity. A strong choice when you want a voice that feels relatable and trustworthy across a range of content. | [Listen](https://elevenlabs.io/app/voice-library?voiceId=Uc7anshoV8mdBhDnEZEX) |
+| 3 | **Don** | Young American male voice with a casual, approachable tone that feels natural and engaging. Light, clear, and expressive -- perfect for conversations with listeners in a relaxed way. This style works especially well for social media content, storytelling, and audiobooks, where relatability and flow are key. The voice carries warmth and clarity, making it easy to listen to over long sessions from narration to digital campaigns. | [Listen](https://elevenlabs.io/app/voice-library?voiceId=8IbUB2LiiCZ85IJAHNnZ) |
+| 4 | **Hanna** | Professional American female voice with a polished, authoritative delivery. Clear articulation and steady pacing make her an excellent choice for informative narration, e-learning modules, and corporate voiceover. She conveys competence and credibility without sounding stiff or robotic. Best when you need a voice that commands attention while remaining approachable in instructional or business contexts. | [Listen](https://elevenlabs.io/app/voice-library?voiceId=Hh0rE70WfnSFN80K8uJC) |
+| 5 | **Other** | Provide any ElevenLabs voice ID. Browse voices at the [ElevenLabs Voice Library](https://elevenlabs.io/app/voice-library) to find one that fits your project. | -- |
+
+If the user does not pick, default to **Asher**. Save the selected voice ID to the `eleven_labs_voice_id` field in the `voiceover.ts` file (not as an env var). If the user picks "Other", ask them to provide the voice ID.
+
+Portal users skip this catalog -- they pick a voice visually in the ElevenLabs UI during audio generation (step 5).
+
+### Flow B: Manual (user-provided audio)
+
+1. **Get the audio.** Ask the user to provide or drop an audio file into `audio/originals/voiceovers/<slug>/`.
+2. **Generate transcript and timing.** Walk the user through ElevenLabs Speech-to-Text to get per-word timing data. See [voiceover/providers/manual.md](voiceover/providers/manual.md).
+3. **Sync timing.** Same as Flow A step 6.
+4. **Write `voiceover.ts`.** Same as Flow A step 7.
+5. **Audio plan and build.** Same as Flow A step 8.
+
+## File and folder conventions
+
+Voiceover originals live per-video under `audio/originals/voiceovers/`:
+
+```
+videos/<video-slug>/
+  timeline.ts
+  PLAN.md
+  voiceover_script/
+    script.md
+  audio/
+    originals/
+      voiceovers/
+        <vo-slug>/
+          voiceover.ts             # typed Voiceover object (default export)
+          audio.mp3                # audio file (mp3 or wav; any name works, referenced from voiceover.ts)
+          timing.json              # provider-supplied per-word timings (optional)
+          provider_script.md       # provider-annotated script (AI flow only)
+          generate.sh              # API generation script (AI flow only)
+    tracks/
+      v1/
+        track.ts                   # typed AudioTrack object (default export)
+        track.mp3                  # rendered audio
+        plan_snapshot.md           # point-in-time copy of audio plan
+```
+
+**Slug naming.** Both auto-versioned (`v1`, `v2`) and user-named (`narrator-warm`, `take-3`) are valid. The slug is the folder name under `audio/originals/voiceovers/`.
+
+**Multiple voiceovers.** Stored as separate sibling folders under `audio/originals/voiceovers/`. Each is independent and self-contained. The active audio is determined by the audio track referenced in `timeline.ts` via `default_audio_track`.
+
+## Types
+
+### `Voiceover`
+
+```ts
+type Voiceover = {
+  audio_file: string;             // path relative to the voiceover.ts file
+  provider: "elevenlabs" | "manual";
+  provider_timing_file?: string;  // path relative to the voiceover.ts file
+  timing: Timing;
+  notes?: string;
+  eleven_labs_voice_id?: string;  // ElevenLabs voice ID; defaults to Asher if omitted
+};
+```
+
+### `Timing`
+
+```ts
+type Timing = {
+  perSegment: Partial<Record<string, number[]>>;
+};
+```
+
+A `Timing` overrides segment `advances` for any segments it lists. Segments not listed fall back to their own `advances` array.
+
+### `Timeline` extensions
+
+```ts
+interface Timeline {
+  meta: TimelineMeta;
+  segments: TimelineEntry[];
+  default_timing?: Timing;            // standalone timing overrides
+  default_audio_track?: AudioTrack;   // default audio track for this video
+}
+```
+
+## Writing `voiceover.ts`
+
+A voiceover module default-exports a `Voiceover` object:
+
+```ts
+import type { Voiceover } from 'videowright';
+
+const voiceover: Voiceover = {
+  audio_file: './audio.mp3',
+  provider: 'elevenlabs',
+  provider_timing_file: './timing.json',
+  eleven_labs_voice_id: 'tMvyQtpCVQ0DkixuYm6J', // Asher
+  timing: {
+    perSegment: {
+      'intro':          [4.2],
+      'feature-cards':  [2.1, 5.8, 9.3, 12.0],
+      'outro':          [3.5],
+    },
+  },
+  notes: 'Warm male voice, conversational tone',
+};
+
+export default voiceover;
+```
+
+## Setting the default audio track
+
+After generating a voiceover, it is combined into an audio track (see [../audio.md](../audio.md) for the full audio workflow). The active audio track is set in `timeline.ts`:
+
+```ts
+import '../../styles/editorial-mono/tokens.css';
+import type { Timeline } from 'videowright';
+import defaultAudioTrack from './audio/tracks/v1/track.js';
+
+const timeline: Timeline = {
+  meta: { title: 'My Video' },
+  segments: [
+    { id: 'intro' },
+    { id: 'feature-cards', transition: 'fade' },
+    { id: 'outro', transition: 'fade' },
+  ],
+  default_audio_track: defaultAudioTrack,
+};
+
+export default timeline;
+```
+
+The `default_audio_track` import is the single source of truth for which audio track is active. Switching tracks means updating the import path.
+
+## CLI usage
+
+`render` accepts `--audio-track`:
+
+```bash
+# Use a specific audio track
+npx videowright render --audio-track v1
+
+# Suppress audio (ignore default_audio_track, use default_timing or segment advances)
+npx videowright render --audio-track none
+
+# No flag: use default_audio_track from timeline.ts if set, otherwise no audio
+npx videowright render
+```
+
+`dev` does not accept `--audio-track`. It uses `default_audio_track` from `timeline.ts` if set, otherwise no audio.
+
+## Audio playback by mode
+
+| Mode | Audio mechanism | Behavior |
+|---|---|---|
+| `dev` | HTML `<audio>` element | Play button in HUD starts auto-advance with synced audio. Manual nav pauses audio. |
+| `render` | ffmpeg audio mux | Audio file is muxed into the output MP4 as a second input to ffmpeg. No `<audio>` element. |
+
+## Timing precedence
+
+When determining advance schedules:
+
+1. **Active audio track's `timing`** -- if an audio track is active (via `--audio-track <id>` or `default_audio_track`).
+2. **`default_timing`** on `timeline.ts` -- if no audio track is active.
+3. **`SegmentSpec.advances`** -- per-segment fallback.
+
+`--audio-track none` suppresses level 1 (audio tracks) but preserves `default_timing` (level 2) and per-segment advances (level 3).
+
+## The `voiceover` field on segments
+
+Each segment can declare a `voiceover` string in `defineSegment`:
+
+```ts
+export default defineSegment({
+  id: 'intro',
+  advances: [3.0],
+  voiceover: 'Welcome to the product demo.',
+  async play(ctx) { await ctx.hold(3000); },
+});
+```
+
+This field is:
+
+- **Shown in the HUD** during dev mode.
+- **Collected by `videowright script`** into a single markdown document.
+- **Used by the agent** to understand the segment's narrative purpose when editing.
+
+It is a display hint, not the canonical voiceover audio source. The canonical audio comes from the `Voiceover` object in `voiceover.ts`.
+
+## VO-first authoring
+
+The default authoring pattern for new videos with voiceover intent:
+
+1. **Write the script first.** Draft the full VO copy organized by segment in PLAN.md.
+2. **Scaffold segments from the script.** Each segment's content and timing follow from its VO text. A 30-word section suggests ~12s; a 100-word section suggests ~40s (based on ~150 WPM).
+3. **Use `waitForNext()` for every VO-aligned beat.** Each content reveal that a voiceover line should cue must be gated by `waitForNext()`, not `hold()`. This is what makes voiceover-swapping possible — different voiceovers supply different advance timings, and segments respond by advancing at the right moment without code changes. Use `hold()` only for animation lead-in or fixed internal pauses within a beat.
+4. **Set `voiceover` on each segment** to its section of the script.
+5. **Generate the audio** using one of the two flows above.
+6. **Sync timing** to align segment advances with the audio.
+
+## VO-alignment smell
+
+If you are adjusting `hold()` values inside a segment to make an animation line up with a specific voiceover recording, that is a code smell. It means the segment is coupled to one narration — any change to the voiceover (different voice, different pacing, re-recorded take) will require re-tuning those timers.
+
+The fix is structural: content that needs to sync with the voiceover should be gated by `waitForNext()`, so timing comes from the `advances` / `Timing` data rather than from hardcoded milliseconds in the segment code. Add a new advance at the sync point, and let the timers within each beat use percentage-based durations so they scale when beat lengths shift. See [authoring_segment.md § Percentage-based timing within beats](../authoring_segment.md#percentage-based-timing-within-beats) for the pattern.
+
+## `videowright script` CLI
+
+The `script` command reads segments' `voiceover` fields and assembles them into markdown:
+
+```bash
+npx videowright script              # print to stdout
+npx videowright script --write      # write to voiceover_script/script.md
+```
+
+See the `videowright script` section below for output format and `--write` behavior.
+
+### Output format
+
+```markdown
+# Video Title
+
+## segment-id-1
+Voiceover text for the first segment.
+
+## segment-id-2
+Voiceover text for the second segment.
+
+---
+
+*No voiceover: segment-id-3, segment-id-4*
+```
+
+### `--write` flag
+
+With `--write`, the script is written to `videos/<name>/voiceover_script/script.md`. Without `--write`, it prints to stdout.
+
+## Keeping things in sync
+
+The `voiceover` field on each segment and `voiceover_script/script.md` are two representations of the same content:
+
+- **After editing `voiceover` fields** on segments, run `npx videowright script --write` to regenerate `script.md`.
+- **After editing `script.md`** directly, update each segment's `voiceover` field to match.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| User wants VO but has no script yet | Draft one during the build phase based on the video's purpose and segment outline. |
+| User changes audio intent from silent to voiceover mid-project | Add `voiceover` fields to existing segments. Run `videowright script --write`. Follow the voiceover flow to generate audio and timing. |
+| Audio file missing on disk | CLI errors before playback or render starts with a clear message and path. |
+| `--audio-track <id>` with non-existent track | CLI errors with a hint to check the `audio/tracks/` folder. |
+| Browser autoplay blocked | Audio is silent until the user clicks the play button (which counts as a user gesture). |
+| Default audio track set but user switches via `--audio-track <other-id>` | Advance timing updates automatically. In-segment animations remain tuned to the original default -- the user can re-run the animation sync pass if needed. |

package/skill/references/audio.md

@@ -0,0 +1,135 @@
+# Audio
+
+## When this is loaded
+
+You were routed here from the intent dispatch table because the user wants to work with audio -- voiceover, sound effects, or background music.
+
+## Overview
+
+Videowright supports multi-source audio tracks: voice-over, sound effects, and music combined into a single rendered audio file. Videos reference an audio track (not a voice-over directly); the audio track drives video timing and is muxed into the final MP4.
+
+The audio workflow is progressive: start with what the video needs, source the assets, then build and sync the track.
+
+## Audio intent questions
+
+Ask these three questions upfront. Skip any whose answer is already clear from the user's input.
+
+> 1. Will this video have a **voice-over**? (yes / no)
+> 2. Will it have **sound effects**? (yes / no)
+> 3. Will it have **background music**? (yes / no)
+
+Based on answers, load only the relevant sub-references below.
+
+## Routing
+
+### Voice-over
+
+If the user wants a voice-over, load [audio/voiceover.md](audio/voiceover.md). This covers:
+
+- AI-generated (ElevenLabs) and manual (user-provided audio) flows
+- Script writing, provider script transformation
+- Voice selection and style intake
+- Sync timing computation
+
+### Sound effects
+
+If the user wants sound effects, load [audio/sfx/sfx.md](audio/sfx/sfx.md). This covers:
+
+- BYO (user-provided audio), ElevenLabs (AI-generated), and Openverse (free search) sourcing flows
+- `sfx.ts` metadata authoring
+- Per-asset approval UX (Approve / Discard and request changes)
+- Integration into the audio plan as cues
+
+SFX assets live in `audio/originals/sfx/<slug>/` and are referenced by cues in the audio plan.
+
+### Background music
+
+If the user wants background music, load [audio/music/music.md](audio/music/music.md). This covers:
+
+- BYO (user-provided audio), ElevenLabs (AI-generated), and Openverse (free search) sourcing flows
+- `music.ts` metadata authoring (rich free-text notes for BPM, key, mood, structure)
+- Per-asset approval UX (Approve / Discard and request changes)
+- Integration into the audio plan as cues with volume curves and ducking
+
+Music assets live in `audio/originals/music/<slug>/` and are referenced by cues in the audio plan.
+
+### Audio plan, build, and sync
+
+If any audio is present (VO, SFX, or music), the audio plan/build/sync workflow applies:
+
+1. **Audio plan** -- author `audio/audio_plan.md` describing the mix composition. See [audio/audio_plan.md](audio/audio_plan.md) for the format spec, [audio/cue_template.md](audio/cue_template.md) for the per-cue field template, and [audio/styles.md](audio/styles.md) for mix-level guidance.
+2. **Build** -- render the plan into an audio track via ffmpeg. See [audio/build.md](audio/build.md). Uses recipes from [audio/ffmpeg_cookbook.md](audio/ffmpeg_cookbook.md).
+3. **Sync** -- compute per-segment timing from the track. See [audio/sync.md](audio/sync.md).
+
+For **VO-only videos** (no SFX, no music), the plan is minimal (single cue, full file, placed at 0s) and is auto-emitted during the voiceover flow. The user does not need to understand the plan format -- it is created transparently and consumed by build and sync.
+
+For **multi-source mixes** (VO + SFX, VO + music, or all three), the plan is authored explicitly with per-cue volume curves, fades, and a full ffmpeg mix command.
+
+## File layout
+
+Each video has an `audio/` directory:
+
+```
+videos/<video-slug>/
+  voiceover_script/
+    script.md                          # assembled VO script
+  audio/
+    audio_plan.md                      # audio composition plan + log
+    originals/                         # source files (immutable after use)
+      voiceovers/
+        v1/
+          voiceover.ts
+          audio.mp3
+          timing.json
+          provider_script.md
+          generate.sh
+      sfx/                             # slug-named subfolders
+        keyboard_typing/
+          audio.mp3
+          sfx.ts
+          generate.sh
+      music/                           # slug-named subfolders
+        uplift_piano/
+          audio.mp3
+          music.ts
+          generate.sh
+    tracks/                            # rendered audio tracks
+      v1/
+        track.ts                       # typed AudioTrack object
+        track.mp3                      # rendered audio
+        plan_snapshot.md               # point-in-time plan copy
+```
+
+### Active track
+
+`timeline.ts` imports the active track via `default_audio_track`. The import is the single source of truth for which track is live. Switching tracks means updating the import.
+
+```ts
+import defaultAudioTrack from './audio/tracks/v1/track.js';
+
+const timeline: Timeline = {
+  // ...
+  default_audio_track: defaultAudioTrack,
+};
+```
+
+## CLI usage
+
+```bash
+# Use a specific audio track
+npx videowright render --audio-track v1
+
+# Suppress audio (use default_timing or segment advances)
+npx videowright render --audio-track none
+
+# No flag: use default_audio_track from timeline.ts if set
+npx videowright render
+```
+
+## Timing precedence
+
+1. **Active audio track's `timing`** -- via `--audio-track <id>` or `default_audio_track`
+2. **`default_timing`** on `timeline.ts`
+3. **`SegmentSpec.advances`** -- per-segment fallback
+
+`--audio-track none` suppresses level 1 (audio tracks) but preserves levels 2 and 3.