feat: [SFX:] timeline lines — sound effects mixed at absolute offsets

[darioalessandro]

What

A new line-oriented marker for script.md:

[SCENE: body | template=code-meme duration=7.0]
[SFX: assets/sfx/impact.mp3 | at=5.5 gain=-15]
[CLIP: body | at=0.2]
...

Each [SFX:] mixes an audio file into the final assembly at scene.start + at, with an optional gain in dB (default 0).

Why

Web-template scenes render silent — until now the only audio channels were narration, video-clip native audio, and the music bed. Sound design (impacts, whooshes, stamps, record scratches) needed a per-cue channel that doesn't fight the narration timing model.

Design choices

• Parser (videoeditor-timeline): Sfx { file, at, gain_db } on Scene. An [SFX:] between narration lines does NOT split the surrounding clip's text (deliberately no flush_clip). Malformed gain= is an error, not a silent 0.
• Assembly (videoeditor-media): SFX enter the existing amix graph exactly like narration clips (adelay + normalize) but never get atempo and never gate scene durations or the fit-check.
• Missing file fails loudly — an authored cue that ships as silence is a bug, so assemble bails (unlike the music bed, which is ambient and skips with a note).
• Authoring guidance added to guide.md: keep SFX ≈ −15 dB under narration; land impacts in pauses, never over a spoken number.

Testing

• Parser unit tests extended (parses_scenes_clips_and_data): gain default, clip-text integrity across an interleaved [SFX:].
• just check clean (clippy -D warnings + fmt).

🤖 Generated with Claude Code