A video file can expose a codec name, dimensions and duration without proving that its entire selected video stream decodes successfully. Before an expensive downstream step, you can run a decode pass with FFmpeg and discard the decoded output. Treat the result as evidence about that decoder, stream and error policy, not a certificate that the media is perfect.
This guide checks a local delivered file. It does not repair media, verify speech content, or claim that Tornado API performs this exact validation internally.
Choose the question your check answers
Different checks address different failures. A checksum compares bytes with an expected identity. A metadata probe helps identify streams. A decode pass exercises the selected stream through a decoder. Playback in your target browser or application tests another layer again.
For example, a file may decode in your installed FFmpeg build while using a codec your browser does not support. Conversely, a decoder may report an unsupported feature even when the file works in another implementation. Use the container and codec guide when the symptom is playback compatibility.
Choose whether the downstream consumer needs one video stream, all video streams, audio, or subtitles. Do not label a video-only test as validation of the whole media package.
Decode one video stream without saving a new file
Run the following against an application-controlled local file that has finished downloading:
ffmpeg -nostdin -v error -xerror -abort_on empty_output -err_detect explode -i ./video.mkv -map 0:V:0 -an -f null -
This selects the first video stream excluding attached pictures, disables audio output, and sends the result to the null muxer. It does not create a replacement video. The null muxer documentation describes its use for testing and benchmarking; this article makes no performance claim.
-xerror asks FFmpeg to stop on error, while -err_detect explode requests a strict decoder error policy. -abort_on empty_output rejects an empty output. See the FFmpeg option reference for these controls. Strictness is a workflow choice: a strict rejection is not proof that every player would fail on the same file.
Do not add -c copy to make this test faster. Stream copying bypasses decoding and changes the question being tested. Similarly, extracting one thumbnail exercises only the work needed for that extraction, not a complete pass through every selected video packet.
This command has no time-window limit. For a large file it may consume substantial CPU and wall-clock time. Put it behind bounded worker concurrency and an external deadline. If you deliberately check only a sample, record that scope and do not report a full-file pass.
Interpret the process result conservatively
Capture the exit status and a bounded diagnostic log. Keep signed delivery URLs and private source details out of those logs; using a local application-generated filename helps separate validation from remote access troubleshooting.
Use separate outcomes in your application:
- Completed successfully: the selected video stream passed this invocation's checks.
- Decoder or input error: preserve the original and inspect the diagnostic before deciding whether another download or decoder is appropriate.
- No matching video stream: handle the artifact as audio-only or unexpected input, according to the workflow.
- Deadline exceeded: the check is incomplete. A timeout does not establish corruption.
- Tool unavailable or worker failure: fix the execution environment rather than marking the file invalid.
A zero exit status is not a promise that every possible corruption was detected. Keep an expected-duration check where completeness matters: a cleanly shortened file could still decode successfully. Compare the actual artifact against your workflow's requirements using duration validation.
Keep validation tied to the exact artifact
Save the artifact reference or checksum, selected stream, tool version, validation policy, completion status and relevant diagnostic category. If you download or transform the file again, the previous result does not automatically apply to the new bytes.
A SHA-256 check can identify bytes across stages, but it requires a trusted expected value to establish that they match a particular reference. Neither a newly computed checksum nor successful decoding proves that the right programme, speakers or language were delivered.
Do not overwrite the source while investigating. If you produce a repaired or transcoded version, record it as a different artifact and validate it separately. Avoid repeatedly creating new source jobs in response to a deterministic local validation failure.
Place the check after delivery
In a Tornado integration, use the documented job status response to follow processing and obtain the available delivery result. Finish the local download before running this check. Job completion and acceptance by your downstream consumer are separate workflow milestones.
If your next step only needs a preview, the preview extraction guide may be sufficient for that narrower task. If a later process will traverse the whole video, decide whether a separate decode pass is worth the additional work or whether that process already provides equivalent failure handling.
Example verification and limits
The command was exercised locally with a synthetic video, an audio-only fixture, invalid file bytes and a missing input. The tests also confirm that the successful null-output run creates no new media file and leaves the input unchanged. They do not measure detection rates for corrupted frames or prove behavior across all codecs, hardware decoders or source platforms.
No paid API job or production-media test was used. For your application, include representative permitted files and known failure samples before choosing a rejection policy.
To connect source delivery and downstream acceptance, build your first Tornado media workflow and record decoding as a separate step with its own result.