ferraus media replace-audio

Write a copy of a video with a new audio track

Synopsis

ferraus media replace-audio <inputs...> [options] [-o <output>]

Takes a video and an audio file and writes the video with the audio replaced (video stream copied, never re-encoded). The audio is copied when the container accepts its codec, otherwise encoded: AAC for MP4/MOV, Opus for WebM, FLAC for MKV. Needs the FFmpeg bridge.

Examples

Swap in the mastered mix (AAC 192k)

ferraus media replace-audio clip.mp4 mastered.wav -o clip-mastered.mp4

New audio first, original kept as track 2

ferraus media replace-audio talk.mkv clean.flac --keep-original

Opus audio in WebM, trimmed to whichever of video or audio is shorter

ferraus media replace-audio promo.webm voiceover.wav --codec opus --shortest -o promo-vo.webm

Options

Flag	Type	Default	Meaning
`--codec`	auto \| copy \| aac \| opus \| mp3 \| flac \| pcm	`auto`	Audio codec in the output: auto picks copy when compatible, else the container's usual codec
`--keep-original`	flag	—	Keep the original audio as a second track [default: off]
`--shortest`	flag	—	End the output when the shorter of video and audio ends [default: off]

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Code	Meaning
0	Success
1	Processing failed
2	Usage or parameter error
3	Input missing or unreadable
4	Unsupported format or codec
8	Cancelled
70	Internal error (bug)

Common mistakes

Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

MCP tool: ferraus_media_replace_audio
Schema: ferraus schema media replace-audio
Pipeline: { op: media replace-audio, args: { ... } } (flag names with _ instead of -)
fx stage: no

{"command": "media replace-audio", "defaults": {"codec": "auto"}}