Replace or Add a Local Video Soundtrack

What it does

Inspect audio streams; replace every original audio track, replace a chosen audio ordinal, or append a local soundtrack as a separate track. Works with silent video and multi-audio inputs. Compatible video is copied by default; all output audio is encoded as AAC. Choose silence padding, looping, or leaving a short audio track short, plus linear gain on the new soundtrack.

How to use

Inspect the video first. Choose the operation, zero-based audio ordinals and duration policy. Review the dry-run command and export to a new directory. A JSON manifest records the policy, output audio order and measured streams.

Requirements

Python 3.10+ with FFmpeg and ffprobe separately installed. No additional Python packages. An explicit H.264 reencode option handles video outside the conservative MP4 copy allowlist.

Caveats

Add means another audio track, not an audio mix. Full video duration is retained. Existing audio is reencoded; gain affects the new soundtrack only. Global metadata/chapters can be preserved or dropped; audio stream tags are reset. This is not a privacy sanitizer. No copyrighted-music downloads, arbitrary YouTube URL downloads, uploads, or overwriting existing output.