Correctness & QC
The checks a job passes before it is reported complete, and the evidence retained afterwards. Intended for operators who must defend a delivery against a specification.
For internal encodes, the baseline verification described first is sufficient. For deliveries to a broadcaster, a streamer or a client with a written specification, the remaining sections describe the recorded evidence that distinguishes believing an output is correct from demonstrating that it is.
Purpose#
Distributed encoding introduces a failure mode that local encoding does not: the output is assembled from segments produced on different machines. If one machine differs in FFmpeg build, hardware accelerator or colour interpretation, the result is a file that plays and passes casual inspection but is incorrect partway through.
FFmpeg also exits successfully in many failure cases: a truncated encode, a silent audio track and a dropped caption track all exit 0. A successful exit code is therefore not evidence of a correct output. Verification exists to provide that evidence.
Baseline verification#
Every job, on every configuration, passes the following checks before it is reported complete:
- The assembled duration must match the source within a one-frame tolerance.
- If the source carried audio, the output must carry audio.
A job that fails either check is reported as failed rather than delivered. This behaviour is always enabled and is not configurable.
Correctness verifiers#
Beyond the baseline, a set of verifiers examines properties specific to distributed encoding. Each verifier produces a recorded outcome rather than a pass/fail gate.
| Verifier | What it establishes |
|---|---|
| Quality metrics | PSNR, SSIM and VMAF sampled around every chunk boundary — the locations where a seam would appear. |
| Timing continuity | Walks the packet timeline and asserts strict monotonicity, so no stream jumps backwards where two chunks were joined. |
| Audio concatenation | Compares cumulative sample counts at each boundary, catching sample-level drift a listener would perceive as sync error. |
| Colour consistency | Confirms every chunk shares one colour signature. Mismatched chunks are refused at assembly rather than blended into the output. |
| Codec conformance | Scores the bitstream against the specification for the requested codec and profile. It runs only for presets that carry a registered specification; a preset without one records a skipped result — shown in grey — rather than a pass, so a green report never implies a check that did not run. |
| HDR static metadata | For an HDR deliverable, confirms the mastering-display primaries and the content light levels (MaxCLL / MaxFALL) are present and well-formed. A missing light-level block is a common cause of rejection at a streaming platform. |
| Determinism | Audits the encoder arguments for anything that would make output vary between runs or between workers. |
| Reproducibility | Encodes twice and compares bitstream hashes for bit-exactness. |
| Source fixity | Records the source at submission and re-checks it at completion. |
| Audio content | Scores whether the delivered audio contains the correct samples, per channel, against the source. |
| Caption survival | Compares embedded captions present in the source against the assembled deliverable. |
These verifiers record findings; they do not stop a job. Only the baseline duration and audio-presence checks fail a job outright. A failed verifier on a completed job is recorded evidence to review, not an indication that the delivery was blocked.
Caption survival#
Embedded 608/708 captions ride inside the video essence rather than as a separate stream, which makes them susceptible to loss in a chunked pipeline without any error being raised.
Two mechanisms apply. At dispatch, when the source carries captions and the target encoder can carry them, the encode is instructed to preserve them. At completion, the assembled output is compared against the source; a loss is reported and raised as an activity event.
This check is presence-based. It establishes that captions survived; it does not establish that 708 continuity is intact across every seam, because the probe does not expose that information. Treat it as detection of catastrophic loss, not as a full caption QC pass.
By default a loss is reported. Set TRNSCODE_CAPTIONS_PREFLIGHT_STRICT to fail the job instead when captions are a contractual requirement.
Fleet build consistency#
When a job's chunks were encoded by workers running different FFmpeg builds, that is recorded against the job.
This check reports rather than blocks. A mixed-build assembly is not proven incorrect, and genuinely incompatible bitstreams cause the concatenation step to fail on its own. The record supplies the fact when it matters most — typically during a rolling worker upgrade, when a mixed build is the first cause to rule out.
Quality at chunk boundaries#
The quality metrics do not sample the file at random. They sample frames around each chunk boundary, because chunk boundaries are where distributed encoding can fail; elsewhere the output is equivalent to a local encode.
These measurements address the standard objection to distributed encoding: that splitting a video across machines introduces artefacts at the joins. The per-boundary metrics are recorded evidence that no such artefacts were introduced.
Determinism and reproducibility#
The two properties are related but distinct.
Determinism is a property of the instructions. Some encoder settings introduce variation by design — anything drawing on wall-clock time, thread scheduling or a random seed. The determinism audit inspects the arguments before the encode and flags settings that would make the same input produce different output.
Reproducibility is a property of the result. It encodes the same input twice and compares hashes of the two bitstreams. Identical hashes mean bit-exact reproduction.
Bit-exact reproducibility means a delivery can be regenerated later and proven identical to the file that shipped. Without it, re-running a job produces a file that is likely equivalent but cannot be proven identical.
Source fixity#
The source is recorded when the job is submitted and re-checked when it completes. If the file changed while the job ran, the change is detected and reported. Common causes are an overwrite, a sync-client update, or a transfer that was still in progress at submission.
This failure is common in a shared-storage facility. Without a fixity check it produces an output that is internally consistent but does not correspond to any single version of the source.
QC profiles#
Correctness verification establishes whether the encode is sound. QC establishes whether it meets a delivery specification, which varies per customer.
Loudness is measured against the target of the selected profile. Three common specifications ship:
| Profile | Integrated loudness | True-peak ceiling | Typically for |
|---|---|---|---|
| ATSC A/85 | −24 LUFS | −2 dBTP | North American broadcast |
| EBU R128 | −23 LUFS | −1 dBTP | European broadcast |
| Netflix delivery | −27 LUFS | −2 dBTP | Streaming, with a tighter quality floor |
A profile can also carry video quality floors — a minimum PSNR and VMAF. When set, the QC report evaluates them against the numbers the quality-metrics verifier already produced, so one measurement backs both the correctness report and the delivery specification. When metrics did not score a job — an image-sequence source, or a deliverable whose geometry the reference could not be normalised to — the floor reads as not measured rather than as a pass.
QC profiles measure and report; they do not correct. A file that fails a loudness target is reported as failing it, and the encode is not adjusted to pass. Normalising audio to a specification is a mix decision; applying it automatically would conceal that the delivered mix differed from the mix the mixer approved.
Verification evidence#
Every job records its evidence in the Forensics tab of its expanded row in the queue. A screenshot walkthrough is available at How-to: Read job forensics. The tab contains four panels:
| Panel | Answers |
|---|---|
| Correctness report | Per-verifier outcome, with the reason when one was skipped. |
| QC report | Per-deliverable loudness and true-peak numbers, and whether an operator overrode a failure. |
| Lineage | Source fixity, and a source-versus-output metadata difference. |
| Chunk argv | The exact encoder command each chunk ran, copyable. |
Reading a result
Each verifier reports one of three states:
- Pass — the verifier ran and was satisfied.
- Skipped — the verifier could not run, and the reason is recorded. This state is common and usually benign; for example, a check that requires two encodes on one worker cannot run on a job that did not distribute that way. A skipped verifier provides no evidence in either direction and is neither a pass nor a failure.
- Fail — the verifier ran and was not satisfied. Because these verifiers report rather than gate, a failure on a completed job is recorded information, not a blocked delivery. Review any failure before shipping.
Together, the argv panel and the reports answer the two questions a delivery dispute turns on: which settings produced the file, and what was measured about the result.
Retain the master's database where the record must be preserved. It holds the job history, the verification outcomes and the audit trail; the backup command exists for this purpose.
Verification coverage is strongest on jobs that distribute. A source short enough to encode as a single chunk exercises little of the machinery described here, because most of it checks properties that exist only where chunks meet. Validate the pipeline with a source of realistic length, not a ten-second test clip.