add-music-track

Purpose

Take a silent (or near-silent) video master and a music file, mix them with sane defaults, and write a final video with audible, well-balanced music. Loudness is normalized so the output sits at roughly -14 LUFS (platform-friendly for social and YouTube). Fades in and out are applied automatically, and music duration is matched to video duration by trimming or looping with a crossfade.

Inputs

• --video <path> to a silent video (any common container).
• --music <path> to a music file (mp3 or wav). Must be a real music track from find-music, create-programmatic-music-bed, or user-supplied with a documented source. Synthesized tones (ffmpeg -f lavfi -i sine=..., white noise, oscillator output) are rejected by default.
• --out <path> for the mixed output.
• Optional --target-lufs <float> (default -14).
• Optional --fade-in <seconds> and --fade-out <seconds> (defaults: 0.5 and 1.0).
• Optional --duck-vo <path> to a voiceover track to mix on top with side-chain ducking.
• Optional --allow-placeholder-tone flag (off by default) for explicit smoke-test runs where the upstream user has acknowledged the music is a placeholder.

Workflow