Ffmpeg Sidecar Injection turns scattered metadata into precision. No guessing, no mismatched timestamps—just exact control over how sidecar files merge with your media streams.
A sidecar file holds metadata separate from the main video, often in formats like JSON, XML, or ASS subtitles. Injecting it properly is critical when you need subtitles, chapters, or timecode aligned without re-encoding. Ffmpeg’s stream mapping and filter systems make this possible, but only if you handle container compatibility, codec alignment, and timebase rules.
The core method:
- Identify the main media file and the sidecar file.
- Use
-i flags in Ffmpeg for each input. - Map streams with
-map to ensure the sidecar content joins the correct track. - Preserve codecs with
-c copy to avoid losing quality.
Example for injecting an ASS subtitle sidecar into an MP4 without re-encoding:
ffmpeg -i video.mp4 -i subs.ass -c copy -map 0 -map 1 video_with_subs.mp4
This maps the main video stream with its audio, plus the sidecar subtitle stream, into a single output container. No re-encode, no loss.
For JSON or XML metadata, injection depends on the container. MP4 supports some custom metadata streams, while MKV handles broader sidecar injection via attachments. With MKV:
ffmpeg -i video.mkv -attach metadata.xml -metadata:s:t mimetype=text/xml -c copy output.mkv
Here, -attach places the sidecar directly into the container as an attachment, and the mime type ensures proper player recognition.
Sidecar injection is not always about display. It can feed downstream processes—like automated QC, frame-accurate markers, or proxy workflows—without altering core media streams. By mastering Ffmpeg’s stream mapping and attachment syntax, you gain deterministic merges that survive transcoding layers and distribution pipelines.
Get the command right, and sidecar injection becomes a fast, repeatable part of your build. See it running live in minutes at hoop.dev.