add-music-track

name	add-music-track
description	mix a music track under a silent video using ffmpeg. normalizes loudness to roughly -14 LUFS, applies a short fade in and out, and trims or loops the music to match video duration. use after a silent video master and a chosen music file are both ready.

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

1. Verify music is real. Probe the music file with ffprobe. Reject if the metadata or filename suggests a tone (lavfi, sine, tone, placeholder, synth), or if a spectral check shows a sustained pure-tone profile. Reject also if the run's caller manifest records music_source: placeholder. The run is blocked unless --allow-placeholder-tone is set.
2. Probe video duration with ffprobe and music duration.
3. If music is shorter than video, loop with a crossfade so the join is seamless. If longer, trim with a fade-out at the cut.
4. Apply loudnorm to bring music to the target LUFS. Apply fade-in at the start and fade-out near the end of the video.
5. If --duck-vo is provided, mix the VO at -16 LUFS and side-chain compress the music when VO is active.
6. Run a single ffmpeg invocation that combines the silent video stream with the processed music (and optional VO) and writes the output with H.264 video and AAC audio.
7. Write manifest.json with input paths, durations, target LUFS, music provenance (real | placeholder-tone-allowed), and the final output path. Write verification.md.

Output

• A muxed video file at the requested output path.
• manifest.json and verification.md.

Quality Checks

• Output duration matches the input video duration exactly.
• Output has an audible audio stream (probe confirms a non-silent track).
• Music provenance is recorded in the manifest and is not placeholder for production runs.
• Measured loudness is within ±1 LUFS of the target.
• No clipping in peaks (true peak below -1 dBTP).

Failure Modes

• ffmpeg or ffprobe not installed — surface the error and mark blocked.
• Music file is corrupt or unreadable — surface the error.
• Music file is a synthesized tone or placeholder — mark blocked and direct the caller to re-run find-music. Do not silently mix a tone under a delivery video.
• Video already has an audio stream — by default, replace it; surface the replacement in the manifest.
• Loudness target cannot be hit because the music is too quiet — re-encode at higher gain and re-measure.