FFmpeg for Codec, Filtergraph, Audio, and Subtitle

1. A playable file is not necessarily the correct output

Assume an input has one video stream, two audio tracks, and one subtitle stream. FFmpeg finishes successfully and the output plays, yet the first audio track was selected instead of the intended second track. Exit code zero proves process completion, not the intended media contract. CON-016 therefore treats success as an explicit command contract plus post-run ffprobe evidence that matches that contract.

2. The owned CON-016 boundary

The owned artifact is FFmpeg Execution Contract & Probe Verification Matrix v1. General recipe reproducibility belongs to CON-015, creative variant branching belongs to CON-017, and publication/QA decisions belong to CON-018 and CON-022. This lesson asks one bounded question: did streams, codecs, filters, audio, subtitles, and container behavior become exactly what was declared before execution?

3. Close the input inventory before writing the command

Before writing -map, record stream index, type, language, codec, sample rate, channel layout, subtitle type, and required metadata. A filename or “the first track shown by a player” is not reliable identity. If the inventory is incomplete, preserve UNKNOWN; guessing an index or language would manufacture evidence.

4. -map makes stream inclusion explicit

Without -map, FFmpeg can perform automatic stream selection. That convenience is useful for ad-hoc commands but dangerous in an auditable production pipeline. When the contract requires a particular audio or subtitle stream, inclusion must be explicit. -map controls stream selection; codec handling is a separate stage and must not be conflated with it.

5. Stream selection and stream handling are different

After selection, encoder/codec settings apply to the selected output streams. If no codec is declared, the output muxer may choose a default encoder. The matrix therefore asks two distinct questions: which stream was included, and how was it encoded/handled? Correct stream identity with the wrong codec is still a failed contract.

6. Keep simple and complex filtergraphs distinct

A simple filtergraph is tied to an output stream, while a complex filtergraph can have multiple inputs and outputs. The execution contract must state where a filter applies, which input feeds it, and which output is expected. A syntactically valid filter string is not sufficient; post-run technical evidence must also show the expected result such as resolution or audio properties.

7. Labeled complex-filter outputs need exact mapping

A labeled output pad from a complex filtergraph must be mapped to the intended output. A stale label in either the graph or the -map expression breaks the contract. The label and map expression are therefore versioned together. The evidence contract never guesses a “closest label” and never treats an implicit fallback as equivalent to explicit intent.

8. Audio contracts include sample rate and channel layout

Audio is more than codec choice. Record track identity, codec, sample rate, and channel layout. If an input changes from stereo to 5.1, the pipeline must explicitly preserve 5.1, intentionally downmix it, or fail. A silent 5.1-to-stereo change without declared policy is an AUDIO_MISMATCH even when subjective playback sounds acceptable.

9. Subtitle behavior has compatibility constraints

Subtitle streams are not just present or absent: text/image type, encoder, and target container matter. FFmpeg has special subtitle-selection behavior, and specifying a subtitle encoder does not by itself prove conversion or muxer compatibility. If a target expects text subtitles but the source is image-based, the contract must prove a supported path or emit SUBTITLE_UNSUPPORTED.

10. The container is part of the contract

A set of streams may be valid for one container and invalid for another. The matrix therefore evaluates target container, expected streams, codecs, and subtitle mode together. Changing MP4 to MKV or vice versa is not an extension rename; compatibility must be re-evaluated and unsupported combinations become typed failures.

11. ffprobe is post-run technical evidence

ffprobe is FFmpeg's official inspection tool for container and stream information in parseable forms. Here it supplies the observed technical record: stream type/index, codec, audio properties, resolution, subtitle details, and format. It does not prove meaning, rights, accessibility, aesthetic quality, or publication approval.

12. Type the mismatch instead of hiding it behind one PASS flag

Use explicit states such as STREAM_MISMATCH, CODEC_MISMATCH, FILTERGRAPH_MISMATCH, AUDIO_MISMATCH, SUBTITLE_UNSUPPORTED, CONTAINER_MISMATCH, and UNKNOWN. Typed failure makes repair auditable. If multiple technical dimensions fail, the bounded decision is BLOCK and the reason names each failed dimension.

13. The matrix compares Expected with Observed

Each row keeps input/stream identity, intended inclusion, map expression, codec/filter/audio/subtitle/container expectations, and ffprobe observed together. Match is derived from comparing these records, never from process exit status. Observed evidence comes from probe data; expectations come from the contract. Neither side is synthesized from the other.

14. Lab: eight fixtures and 64 assertions

The lab includes a valid baseline plus deliberate failures: automatic/wrong audio selection, a stale filter label, incompatible subtitles, unexpected default codec, audio-layout mismatch, container mismatch, and a transfer with two subtitles and 5.1 audio. The hidden oracle checks eight fields for each of eight fixtures: 64 deterministic assertions. Learners see fixtures and starter code, never expected labels.

15. Transfer: second subtitle, 5.1 audio, and a new container

The transfer adds a second subtitle stream, changes input audio to 5.1, and switches the target container. The previous decision cannot be copied. Inventory, maps, codecs, filters, downmix/preserve policy, subtitle mode, and probe evidence are rebuilt. EXECUTION_VERIFIED is allowed only when every owned technical dimension closes; it is not publication permission.