videowright 0.1.0

package/skill/references/audio/build.md

@@ -0,0 +1,208 @@
+# Audio Track Build
+
+## When this is loaded
+
+You have an audio plan (`audio/audio_plan.md`) and are ready to render it into an audio track. This reference walks through the mux-to-approve workflow.
+
+## Overview
+
+Building an audio track means running the ffmpeg command from the audio plan to produce a rendered audio file, then asking the user to approve or discard the result. All operations are bash commands and file edits -- no library code is involved.
+
+## Prerequisites
+
+- The video has an `audio/audio_plan.md` with a complete Plan section (cues + final mix command).
+- All source files referenced by the plan exist in `audio/originals/`.
+- ffmpeg is installed and on PATH.
+
+## Build workflow
+
+Run these steps from the video folder (e.g., `videos/demo_video/`).
+
+### Step 1: Determine the next track ID
+
+List existing tracks and pick the next version:
+
+```bash
+ls audio/tracks/ 2>/dev/null
+```
+
+If no tracks exist, use `v1`. Otherwise, find the highest `vN` and use `v(N+1)`.
+
+### Step 2: Create the track folder
+
+```bash
+mkdir -p audio/tracks/vN/
+```
+
+### Step 3: Snapshot the plan
+
+Copy the Plan section of `audio/audio_plan.md` (everything from the top of the file down to but not including `## Log`) into `audio/tracks/vN/plan_snapshot.md`.
+
+The snapshot is a verbatim copy. Do not modify it. This is what the sync stage reads.
+
+**Splitting rule:** find the line that starts with `## Log` and take everything above it. If there is no `## Log` heading, snapshot the entire file.
+
+### Step 4: Run ffmpeg
+
+Extract the final mix command from the Plan section. Replace `{TRACK_OUT}` with the actual output path:
+
+```bash
+# Example: replace {TRACK_OUT} with audio/tracks/v3/track.mp3
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -c:a libmp3lame -q:a 2 \
+  audio/tracks/v3/track.mp3
+```
+
+**Run the command from the video folder** so that relative paths in the plan resolve correctly.
+
+If ffmpeg fails:
+- Print the full stderr output.
+- Check for common issues: missing input files, invalid filter syntax, malformed paths.
+- Do **not** write `track.ts` or append to the log.
+- Present the error to the user and suggest next steps (fix the plan, check source files).
+
+### Step 5: Measure duration
+
+Use ffprobe to get the rendered file's duration:
+
+```bash
+ffprobe -v error -show_entries format=duration \
+  -of default=noprint_wrappers=1:nokey=1 \
+  audio/tracks/vN/track.mp3
+```
+
+This returns a number like `28.742000`. Use it for `length_s` in track.ts.
+
+### Step 6: Write track.ts
+
+Create `audio/tracks/vN/track.ts`:
+
+```ts
+import type { AudioTrack } from "videowright";
+
+const track: AudioTrack = {
+  audio_file: "./audio/tracks/v1/track.mp3",
+  length_s: 28.74,
+  timing: { perSegment: {} },
+  audio_plan_path: "../../audio_plan.md",
+  plan_snapshot_path: "./plan_snapshot.md",
+  created_at: "2026-05-15T14:22:00Z",
+};
+
+export default track;
+```
+
+Notes:
+- `audio_file` is relative to the **video folder** (the directory containing `timeline.ts`). For a track at `audio/tracks/vN/track.mp3`, use `"./audio/tracks/vN/track.mp3"`.
+- `length_s` comes from ffprobe (step 5). Round to 2 decimal places.
+- `timing` starts as `{ perSegment: {} }` for a new track. If a previous track exists and is active, copy its `timing` as a starting point. The sync stage will update it.
+- `created_at` is the current ISO timestamp.
+- `audio_plan_path` and `plan_snapshot_path` are relative to the track.ts file (these are metadata paths, not consumed by the render pipeline).
+
+### Step 7: Append a render log entry
+
+Append to the Log section of `audio/audio_plan.md`:
+
+```markdown
+## YYYY-MM-DD HH:MM -- <summary>
+**Change:** <what was modified or "initial build">
+**Why:** <user feedback or "first render">
+**Render:** audio/tracks/vN/track.mp3
+```
+
+### Step 8: Present the result
+
+Print a clickable absolute `file://` link to the rendered audio file so the user can listen:
+
+```
+Listen to the rendered track:
+file:///absolute/path/to/audio/tracks/vN/track.mp3
+```
+
+Use the absolute path so the link works in any terminal.
+
+### Step 9: Prompt for approval
+
+Ask the user exactly two options:
+
+> 1. **Approve** -- set this as the active audio track.
+> 2. **Discard and request changes** -- delete this track and revise the plan.
+
+Do not proceed without an explicit choice.
+
+### On Approve
+
+1. **Update timeline.ts** to import the new track as `default_audio_track`:
+
+   Find and replace the existing audio track import (or add one if this is the first track):
+
+   ```ts
+   import defaultAudioTrack from './audio/tracks/vN/track.js';
+   ```
+
+   And in the timeline object:
+
+   ```ts
+   default_audio_track: defaultAudioTrack,
+   ```
+
+   Note: the import path uses `.js` extension (TypeScript ESM convention), not `.ts`.
+
+2. **Append an activation log entry** to `audio/audio_plan.md`:
+
+   ```markdown
+   ## YYYY-MM-DD HH:MM -- Adopted vN as active track
+   ```
+
+3. **Proceed to sync** if the video has per-segment timing needs. Load [sync.md](sync.md) to compute the `Timing` from the track's plan snapshot and VO timing data.
+
+### On Discard
+
+1. **Delete the track folder**:
+
+   ```bash
+   rm -rf audio/tracks/vN/
+   ```
+
+2. **Append a discard log entry** to `audio/audio_plan.md` (the log is append-only -- never delete entries):
+
+   ```markdown
+   ## YYYY-MM-DD HH:MM -- Discarded vN
+   **Why:** <user's feedback>
+   ```
+
+3. **Ask for feedback**: "What should change?"
+
+4. **Revise the plan** based on feedback: edit cues, adjust volumes, change fades, etc.
+
+5. **Loop back to Step 1** and build again.
+
+## Rebuilding after plan changes
+
+When the user requests mix changes after an approved track:
+
+1. Edit the Plan section of `audio/audio_plan.md` (update cues, volumes, etc.).
+2. Run the full build workflow again (Steps 1-9). The new track gets the next version number.
+3. The old track remains in `audio/tracks/` for rollback. To revert, just update the timeline.ts import to point back at the old track.
+
+## Validation before build
+
+Before running ffmpeg, validate:
+
+- All `Source:` paths in the plan point to existing folders.
+- Each source folder contains an `audio.mp3` or `audio.wav` file.
+- The final mix command references the correct number of inputs.
+- `{TRACK_OUT}` is present in the final mix command.
+
+If validation fails, report the specific issue and do not run ffmpeg.
+
+## Error handling
+
+| Situation | Behavior |
+|---|---|
+| ffmpeg not found | Error with install instructions (see [../export.md](../export.md) for ffmpeg install guidance). |
+| Source file missing | Report which path is missing. Suggest checking `audio/originals/`. |
+| ffmpeg filter error | Print stderr. Common causes: typo in filter name, mismatched input count, missing `asetpts` after `atrim`. |
+| Output file is 0 bytes | ffmpeg ran but produced no audio. Check filter graph for dead paths (stream never reaches output). |
+| Plan has no final mix command | Error: "No final mix command found in audio_plan.md. Add a `### Final mix command` section." |

package/skill/references/audio/cue_template.md

@@ -0,0 +1,219 @@
+# Cue Template
+
+## When this is loaded
+
+You are authoring or editing cues in an `audio_plan.md` file. This reference defines the per-cue labeled-field format and the ffmpeg snippet convention.
+
+## Cue format
+
+Each cue is a markdown H3 heading followed by labeled fields and an ffmpeg snippet:
+
+```
+### Cue N -- <short name>
+Source: <relative path to originals folder>
+Slice: <start>-<end> in source  (or "full file")
+Place at: <start> in track
+Volume: <prose curve>
+Fades: <fade description>
+Notes: <optional context>
+
+ffmpeg snippet:
+<filter graph fragment that produces a labeled stream>
+```
+
+### Field reference
+
+| Field | Required | Description |
+|---|---|---|
+| **Source** | Yes | Relative path from the video folder to the originals subfolder. E.g., `audio/originals/voiceovers/v1/` or `audio/originals/sfx/keyboard_typing/`. Points at the folder, not the audio file -- the build step knows to use `audio.mp3` (or `audio.wav`) within. |
+| **Slice** | Yes | Time range within the source file. Either `full file` or `<start>-<end>` in seconds (e.g., `1.2-5.6`). Start and end are timestamps in the source audio, not the output track. |
+| **Place at** | Yes | Where this cue starts in the output track, in seconds (e.g., `3.4s` or `0s`). |
+| **Volume** | Yes | Volume curve for this cue. Can be a simple constant (`100%`, `15%`) or a prose description of changes over time. See volume curves below. |
+| **Fades** | Yes | Fade descriptions. Either `none` or a comma-separated list like `fade in 0-0.2s, fade out 7.4-7.6s`. Times are relative to the cue's placement in the track. |
+| **Notes** | No | Free-text context about what this cue does musically or narratively. Also used by the sync stage as anchor hints for SFX/music timing. |
+
+### ffmpeg snippet
+
+Each cue ends with a labeled ffmpeg filter graph fragment. The snippet:
+
+- Takes one input stream (referenced by input index, e.g., `[0:a]`, `[1:a]`)
+- Applies trim, delay, volume, and fade filters
+- Produces a single labeled output stream (e.g., `[vo1]`, `[sfx1]`, `[music1]`)
+
+The final mix command in the audio plan chains all these labeled streams together.
+
+## Volume curves
+
+Volume is expressed as prose that maps directly to ffmpeg volume expressions. The Volume field is the human-readable version; the ffmpeg snippet is the machine-executable version.
+
+### Constant volume
+
+```
+Volume: 100%
+Volume: 15%
+Volume: -6dB
+```
+
+### Time-varying volume (ducking)
+
+```
+Volume: 100% from 0s, ramps to 15% over 4.5-4.7s, holds 15% until 22.0s, ramps to 100% over 22.0-22.2s
+```
+
+This describes ducking under a voiceover that runs from 4.5s to 22.0s. The ffmpeg implementation uses a `volume` expression with `if(between(...))` or a sidechain compressor -- either is acceptable as long as the snippet matches the described curve.
+
+### Why prose, not raw ffmpeg
+
+The Volume field is prose because:
+
+1. It is auditable -- anyone reading the plan sees the actual level changes.
+2. It is feedback-friendly -- "make cue 3 a bit quieter" maps to a Volume field edit.
+3. The ffmpeg snippet below it is the implementation -- the Volume field is the intent.
+
+## Voiceover cues
+
+### Single VO, full file
+
+```
+### Cue 1 -- VO (full file)
+Source: audio/originals/voiceovers/v1/
+Slice: full file
+Place at: 0s
+Volume: 100%
+Fades: none
+Notes: Full voiceover, see timing.json for word timings.
+
+ffmpeg snippet:
+[0:a] acopy [vo1]
+```
+
+### VO slice
+
+A single VO file can supply multiple cues. Each specifies a slice of the source and a placement in the track.
+
+```
+### Cue 2 -- VO catchphrase
+Source: audio/originals/voiceovers/v3/
+Slice: 1.2-2.4
+Place at: 3.4s
+Volume: 100%
+Fades: none
+Notes: VO says "How now brown cow"
+
+ffmpeg snippet:
+[0:a] atrim=start=1.2:end=2.4, asetpts=PTS-STARTPTS, adelay=3400|3400 [vo2]
+(adelay: repeat the delay value per channel with `|`, or use `adelay=3400:all=1` to apply to all channels — ffmpeg 4.4+)
+```
+
+```
+### Cue 5 -- VO outro
+Source: audio/originals/voiceovers/v3/
+Slice: full file
+Place at: 9.4s
+Volume: 100%
+Fades: none
+Notes: See word-by-word timing in audio/originals/voiceovers/v3/timing.json
+
+ffmpeg snippet:
+[0:a] adelay=9400|9400 [vo5]
+```
+
+Both inline text in Notes and pointers to timing.json are fine. Inline text is convenient for short slices; for long VOs, pointing at timing.json keeps the plan readable.
+
+## SFX cues
+
+```
+### Cue 3 -- Keyboard typing
+Source: audio/originals/sfx/keyboard_typing/
+Slice: full file
+Place at: 8.2s
+Volume: 60%
+Fades: fade in 8.2-8.4s, fade out 14.0-14.2s
+Notes: Typing SFX under the terminal demo segment. Punchy entry, gentle fade.
+
+ffmpeg snippet:
+[2:a] volume=0.6, afade=t=in:st=0:d=0.2, afade=t=out:st=5.8:d=0.2, adelay=8200|8200 [sfx3]
+```
+
+**Note on Fades vs ffmpeg times:** The Fades field uses **track-absolute** times for human readability (e.g., `fade in 8.2-8.4s` means "at 8.2s in the track"). The ffmpeg snippet uses **stream-relative** times (e.g., `afade=t=in:st=0:d=0.2` means "0s into this stream's audio, which starts at 8.2s in the track due to `adelay`"). The Fades field is the intent; the snippet is the implementation.
+
+## Music cues
+
+```
+### Cue 4 -- Background music
+Source: audio/originals/music/uplift_piano/
+Slice: 0-30
+Place at: 0s
+Volume: 100% from 0s, ramps to 15% over 4.5-4.7s, holds 15% until 22.0s, ramps to 100% over 22.0-22.2s
+Fades: fade in 0-0.5s, fade out 28.0-30.0s
+Notes: Music bed. Ducked under VO (4.5-22s). Beat drop at 5.3s aligns with feature reveal.
+
+ffmpeg snippet:
+[3:a] atrim=0:30, asetpts=PTS-STARTPTS,
+      volume='if(between(t,4.7,22),0.15, if(between(t,4.5,4.7),1-0.85*(t-4.5)/0.2, if(between(t,22,22.2),0.15+0.85*(t-22)/0.2,1)))':eval=frame,
+      afade=t=in:st=0:d=0.5, afade=t=out:st=28:d=2 [music4]
+```
+
+### Ducking
+
+Ducking is expressed as a volume curve on the music (or ambient) cue -- not as a separate "duck" primitive. The Volume field describes the level changes in prose. The ffmpeg snippet implements it.
+
+This keeps the plan auditable: anyone reading it sees the actual level changes. See [styles.md](styles.md) for ducking ramp guidance.
+
+## Looped cues
+
+For a short SFX or music clip that needs to fill a longer duration:
+
+```
+### Cue 6 -- Ambient hum (looped)
+Source: audio/originals/sfx/server_hum/
+Slice: full file
+Place at: 0s
+Volume: 20%
+Fades: fade in 0-1s, fade out 25-28s
+Notes: Looped to 28s. Low ambient texture under the entire video.
+
+ffmpeg snippet:
+[4:a] aloop=loop=-1:size=44100*3, atrim=0:28, asetpts=PTS-STARTPTS,
+      volume=0.2, afade=t=in:st=0:d=1, afade=t=out:st=25:d=3 [sfx6]
+```
+
+See [ffmpeg_cookbook.md](ffmpeg_cookbook.md) for loop recipes.
+
+## Final mix command structure
+
+The final mix command references all input files and chains the per-cue labeled streams:
+
+```bash
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -i audio/originals/sfx/keyboard_typing/audio.mp3 \
+  -i audio/originals/music/uplift_piano/audio.mp3 \
+  -filter_complex "
+    [0:a] acopy [vo1];
+    [1:a] volume=0.6, afade=t=in:st=0:d=0.2, afade=t=out:st=5.8:d=0.2, adelay=8200|8200 [sfx3];
+    [2:a] atrim=0:30, asetpts=PTS-STARTPTS,
+          volume='...' [music4];
+    [vo1][sfx3][music4] amix=inputs=3:duration=longest:normalize=0 [mix];
+    [mix] loudnorm=I=-14:TP=-1:LRA=11 [out]
+  " -map "[out]" -c:a libmp3lame -q:a 2 {TRACK_OUT}
+```
+
+Key conventions:
+
+- Input order matches the order inputs appear in the cue list.
+- Each cue's snippet produces a named stream.
+- All named streams feed into `amix` (or `amerge` for stereo mixing).
+- `normalize=0` on amix prevents automatic normalization (the `loudnorm` filter handles it).
+- The `loudnorm` filter at the end targets -14 LUFS (see [styles.md](styles.md)).
+- Output codec is `libmp3lame -q:a 2` for mp3, or `pcm_s16le` for wav.
+
+## Input index mapping
+
+When the same source file appears in multiple cues, it needs only one `-i` input. Cue snippets reference the correct input index:
+
+- Input 0: first `-i` file
+- Input 1: second `-i` file
+- etc.
+
+If two cues use the same VO file with different slices, they share the input index but apply different `atrim` filters.

package/skill/references/audio/ffmpeg_cookbook.md

@@ -0,0 +1,267 @@
+# ffmpeg Cookbook
+
+## When this is loaded
+
+You are building or editing an audio plan and need ffmpeg filter recipes. This is a reference of copy-pasteable ffmpeg patterns for common audio operations.
+
+All examples assume audio inputs. Adjust input indices (`[0:a]`, `[1:a]`, ...) to match your `-i` order.
+
+## Trim and place a clip at a time offset
+
+Extract a slice of audio and place it at a specific point in the output track.
+
+```
+[0:a] atrim=start=1.2:end=5.6, asetpts=PTS-STARTPTS, adelay=3400|3400 [out]
+```
+
+- `atrim=start=1.2:end=5.6` -- extract seconds 1.2 to 5.6 from the source
+- `asetpts=PTS-STARTPTS` -- reset timestamps to start at 0 (required after trim)
+- `adelay=3400|3400` -- delay by 3400ms (place at 3.4s in track). The `|`-separated format repeats the delay per channel. For any number of channels, use `adelay=3400:all=1` (ffmpeg 4.4+).
+
+For a full file placed at an offset (no trim):
+
+```
+[0:a] adelay=5000|5000 [out]
+```
+
+For a full file placed at 0s (passthrough):
+
+```
+[0:a] acopy [out]
+```
+
+## Constant volume scaling
+
+Scale volume by a fixed factor:
+
+```
+[0:a] volume=0.5 [out]       # 50% volume
+[0:a] volume=0.15 [out]      # 15% volume
+[0:a] volume=1.5 [out]       # 150% volume (boost)
+[0:a] volume=-6dB [out]      # -6 dB attenuation
+```
+
+## Time-varying volume (ducking)
+
+### Simple duck: quiet during a time range
+
+```
+[0:a] volume='if(between(t,4.5,22),0.15,1)':eval=frame [out]
+```
+
+This sets volume to 15% between 4.5s and 22s, 100% elsewhere. The transition is instantaneous -- for smooth ramps, use the ramped version below.
+
+### Ramped duck: smooth transitions
+
+```
+[0:a] volume='if(lt(t,4.5),1, if(between(t,4.5,4.7),1-0.85*(t-4.5)/0.2, if(between(t,4.7,22),0.15, if(between(t,22,22.2),0.15+0.85*(t-22)/0.2, 1))))':eval=frame [out]
+```
+
+Breakdown:
+- Before 4.5s: volume = 1.0
+- 4.5s to 4.7s: linear ramp from 1.0 down to 0.15 (over 0.2s)
+- 4.7s to 22.0s: volume = 0.15
+- 22.0s to 22.2s: linear ramp from 0.15 back to 1.0 (over 0.2s)
+- After 22.2s: volume = 1.0
+
+### Multiple duck zones
+
+For ducking under multiple VO segments, chain conditions:
+
+```
+volume='if(between(t,4.5,12),0.15, if(between(t,18,25),0.15, 1))':eval=frame
+```
+
+Add ramps at each transition for smoothness. See [styles.md](styles.md) for recommended ramp durations (~0.2s).
+
+### Expression syntax notes
+
+- `eval=frame` is required for time-varying expressions (evaluates per audio frame, not once).
+- `t` is the timestamp in seconds within the filtered stream.
+- `between(t,a,b)` returns 1 if `a <= t <= b`, else 0.
+- `lt(t,a)` returns 1 if `t < a`.
+- `gt(t,a)` returns 1 if `t > a`.
+- Arithmetic operators: `+`, `-`, `*`, `/`.
+- Nest `if()` calls for multi-range curves.
+
+## Fade in / fade out
+
+```
+[0:a] afade=t=in:st=0:d=0.5 [out]           # fade in over 0.5s starting at 0s
+[0:a] afade=t=out:st=28:d=2 [out]            # fade out over 2s starting at 28s
+```
+
+Combine both:
+
+```
+[0:a] afade=t=in:st=0:d=0.5, afade=t=out:st=28:d=2 [out]
+```
+
+Parameters:
+- `t=in` or `t=out` -- fade type
+- `st` -- start time in seconds (within the stream, after any trim/delay)
+- `d` -- duration of the fade in seconds
+
+### Fade curves
+
+Default is linear. For smoother curves:
+
+```
+afade=t=in:st=0:d=0.5:curve=tri    # triangular
+afade=t=in:st=0:d=0.5:curve=qsin   # quarter sine (smooth)
+afade=t=in:st=0:d=0.5:curve=esin   # exponential sine
+afade=t=in:st=0:d=0.5:curve=log    # logarithmic
+```
+
+For most video audio, the default linear fade is fine. Use `curve=qsin` when a smoother onset is desired.
+
+## Crossfade between two clips
+
+```
+[0:a][1:a] acrossfade=d=1:c1=tri:c2=tri [out]
+```
+
+- `d=1` -- crossfade duration of 1 second
+- `c1`, `c2` -- fade curves for the outgoing and incoming clips
+
+The crossfade overlaps the end of clip 0 with the start of clip 1. The output duration is `len(clip0) + len(clip1) - d`.
+
+This is useful for music transitions but rarely needed for VO or SFX.
+
+## Loop a clip to fill a duration
+
+Loop a short clip to fill a longer time span:
+
+```
+[0:a] aloop=loop=-1:size=2000000, atrim=0:28, asetpts=PTS-STARTPTS [out]
+```
+
+- `loop=-1` -- loop infinitely
+- `size=N` -- loop region size in samples. ffmpeg accepts expressions, so `size=44100*3` works directly in the filter graph (evaluates to 132300 samples = 3s at 44.1 kHz). Set this to at least the source file's total sample count to loop the entire file.
+- `atrim=0:28` -- trim the looped result to 28 seconds
+- `asetpts=PTS-STARTPTS` -- reset timestamps
+
+**Tip:** If you do not know the exact sample count, set `size` to a value larger than any plausible source (e.g., `size=2000000` covers ~45s at 44.1 kHz). ffmpeg loops at most the available samples, so an oversized value loops the full file. Use `ffprobe` to get the exact sample rate and duration if precision matters (see "Probe sample rate and channels" below).
+
+For seamless loops, the source audio should be designed to loop cleanly (no click at the boundary). If there is a click, add a very short crossfade or fade at the loop point.
+
+## Mix N streams
+
+### amix (additive mixing)
+
+```
+[vo1][sfx1][music1] amix=inputs=3:duration=longest:normalize=0 [out]
+```
+
+- `inputs=3` -- number of input streams
+- `duration=longest` -- output duration matches the longest input. Alternatives: `shortest`, `first`.
+- `normalize=0` -- **important**: disables automatic per-stream normalization. Without this, amix scales each input down by 1/N, making everything quiet. Set `normalize=0` and control volume on each stream individually before mixing.
+
+### amerge (interleave channels)
+
+```
+[0:a][1:a] amerge=inputs=2 [out]
+```
+
+`amerge` interleaves channels (e.g., two mono streams into one stereo stream). For summing audio signals (layering VO + music), use `amix`, not `amerge`.
+
+## Final master with loudness normalization
+
+Apply EBU R128 loudness normalization as the last step in the filter chain:
+
+```
+[mix] loudnorm=I=-14:TP=-1:LRA=11 [out]
+```
+
+- `I=-14` -- integrated loudness target: -14 LUFS (good for web/social media delivery)
+- `TP=-1` -- true peak maximum: -1 dBTP (prevents clipping)
+- `LRA=11` -- loudness range target: 11 LU
+
+Apply `loudnorm` after all mixing and volume adjustments. It is the very last filter before output.
+
+### When to use loudnorm
+
+- **Multi-source mixes** (VO + SFX + music): always. Different sources have different levels.
+- **VO-only tracks**: optional. The VO is already at a consistent level from the TTS provider. Including loudnorm is fine but not required.
+
+### Two-pass loudnorm (higher quality)
+
+For critical masters, run loudnorm in two-pass mode:
+
+Pass 1 (measure):
+```bash
+ffmpeg -i input.mp3 -af loudnorm=I=-14:TP=-1:LRA=11:print_format=json -f null /dev/null
+```
+
+This prints measured loudness values. Extract `input_i`, `input_tp`, `input_lra`, `input_thresh`, `target_offset`.
+
+Pass 2 (apply with measured values):
+```bash
+ffmpeg -i input.mp3 -af loudnorm=I=-14:TP=-1:LRA=11:measured_I=-18.5:measured_TP=-2.3:measured_LRA=8.2:measured_thresh=-28.5:offset=-0.5:linear=true [out]
+```
+
+For most video audio, single-pass loudnorm is sufficient.
+
+## Measure audio duration (ffprobe)
+
+Get the duration of an audio file in seconds:
+
+```bash
+ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 audio.mp3
+```
+
+This outputs a single number like `28.742000`. Use this when writing `length_s` in `track.ts`.
+
+## Probe sample rate and channels
+
+```bash
+ffprobe -v error -show_entries stream=sample_rate,channels -of default=noprint_wrappers=1 audio.mp3
+```
+
+Useful for computing the `size` parameter in `aloop`.
+
+## Complete single-command examples
+
+### VO-only (passthrough)
+
+```bash
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -c:a libmp3lame -q:a 2 \
+  {TRACK_OUT}
+```
+
+### VO + music with ducking
+
+```bash
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -i audio/originals/music/uplift_piano/audio.mp3 \
+  -filter_complex "
+    [0:a] acopy [vo];
+    [1:a] atrim=0:30, asetpts=PTS-STARTPTS,
+          volume='if(between(t,4.7,22),0.15, if(between(t,4.5,4.7),1-0.85*(t-4.5)/0.2, if(between(t,22,22.2),0.15+0.85*(t-22)/0.2,1)))':eval=frame,
+          afade=t=in:st=0:d=0.5, afade=t=out:st=28:d=2 [music];
+    [vo][music] amix=inputs=2:duration=longest:normalize=0 [mix];
+    [mix] loudnorm=I=-14:TP=-1:LRA=11 [out]
+  " -map "[out]" -c:a libmp3lame -q:a 2 {TRACK_OUT}
+```
+
+### VO + SFX + music (full mix)
+
+```bash
+ffmpeg -y \
+  -i audio/originals/voiceovers/v1/audio.mp3 \
+  -i audio/originals/sfx/keyboard_typing/audio.mp3 \
+  -i audio/originals/music/uplift_piano/audio.mp3 \
+  -filter_complex "
+    [0:a] acopy [vo];
+    [1:a] volume=0.6, afade=t=in:st=0:d=0.2, afade=t=out:st=5.8:d=0.2,
+          adelay=8200|8200 [sfx];
+    [2:a] atrim=0:30, asetpts=PTS-STARTPTS,
+          volume='if(between(t,4.7,22),0.15,1)':eval=frame,
+          afade=t=in:st=0:d=0.5, afade=t=out:st=28:d=2 [music];
+    [vo][sfx][music] amix=inputs=3:duration=longest:normalize=0 [mix];
+    [mix] loudnorm=I=-14:TP=-1:LRA=11 [out]
+  " -map "[out]" -c:a libmp3lame -q:a 2 {TRACK_OUT}
+```