Validate media duration before downstream processing

Validate media duration by comparing a measured duration from the delivered artifact with an explicit expectation for that same artifact. Keep missing duration metadata as unknown, choose a tolerance before accepting results, and record which stream or container supplied the measurement. A matching number is a useful gate, but it does not prove that every frame decodes or that the content is the right recording.

This guide shows a local ffprobe inspection and a small Python comparison. It is intended for workflows that need to catch a wrong-length input before transcription, editing, or another downstream step.

Define the expected artifact first

A source recording, a requested excerpt, and a delivered audio file are different objects. Compare the delivered file against the output you intended, rather than automatically comparing it against the full source duration.

For a continuous excerpt requested from second 120 to second 150, the intended span is 30 seconds. That arithmetic alone does not establish the actual cut boundaries. If your workflow requires precise alignment, inspect those boundaries and preserve the relationship to the source timeline. The transcript timestamp guide explains why a requested start is not always a measured origin.

Record the artifact revision, expected duration, measurement method, unit, tolerance, and decision. Use seconds consistently. Job processing latency is a separate measurement: time spent downloading or uploading is not the playback duration of the media.

Inspect the local file and retain both levels

With FFmpeg tools installed, run this on a completed local file you are authorized to inspect:

ffprobe -v error -show_entries format=duration:stream=index,codec_type,start_time,duration -of json ./media.wav

The ffprobe reference documents selection of entries and JSON output. The command asks for container duration and individual stream information; it does not transcode or repair the file. Replace the example path with your file. Check the command's exit status before consuming its output.

For an overall-file check, inspect format.duration. For a particular audio track, identify the intended stream and inspect its own duration when available. Do not sum parallel audio and video stream durations to obtain playback length. Do not silently substitute the video track's duration when the question concerns an audio track.

Keep missing fields visible in your application record. Some inputs do not provide a useful duration at the level you selected. A value such as N/A, an omitted field, and a measured zero should not all become the number zero.

We checked the command against a generated one-second mono PCM WAV fixture. Its format duration was 1.000000. That confirms the command and expected fixture duration in the local ffprobe installation; it does not establish behavior for every container, remote stream, or production job.

Compare with a documented tolerance

The helper below accepts decimal-second strings with at most nine integer digits and six fractional digits. The bounds are an example input contract, not media-platform limits. It treats only a missing value or N/A as unknown; malformed numeric values raise an error rather than passing the gate.

import re
from decimal import Decimal, localcontext

_PATTERN = re.compile(r"[0-9]{1,9}(?:\.[0-9]{1,6})?", re.ASCII)


def seconds(value):
    if not isinstance(value, str) or not _PATTERN.fullmatch(value):
        raise ValueError("expected bounded nonnegative decimal seconds")
    return Decimal(value)


def compare_duration(observed, expected, tolerance):
    target = seconds(expected)
    margin = seconds(tolerance)
    if target == 0:
        raise ValueError("expected duration must be positive")
    if observed is None or observed == "N/A":
        return {"decision": "unknown", "difference_seconds": None}
    actual = seconds(observed)
    with localcontext() as context:
        context.prec = 28
        difference = actual - target
        return {
            "decision": "within-tolerance" if abs(difference) <= margin
                        else "outside-tolerance",
            "difference_seconds": format(difference, "f"),
        }


print(compare_duration("29.980", "30.000", "0.050"))
# {'decision': 'within-tolerance', 'difference_seconds': '-0.020'}

Here 50 milliseconds is an illustrative application policy, not a recommended universal tolerance or a Tornado guarantee. A longer tolerance can hide a missing ending; a stricter one may reject acceptable output. Choose it against the transformation and the downstream requirement, then test representative files. A provider's hard maximum duration is a separate limit and must not be relaxed by this matching tolerance.

Python's Decimal documentation explains decimal-string representation and arithmetic context. The bounded inputs fit within the selected precision. Keeping the signed difference makes a short output distinguishable from a long one; it does not reveal the cause.

Route unknown and mismatched results explicitly

When the duration is unexpected, first confirm that the file and revision are correct. Then check whether the comparison used the intended track, whether the requested excerpt was near the source ending, and whether a later edit changed the timeline. Inspect a completed download rather than a file another worker is still writing; atomic download handoff helps establish that boundary.

Metadata can be internally consistent while the file contains corruption or the wrong content. For important handoffs, add decoding or playback checks appropriate to your formats and review the beginning and ending. An audio file can also have the expected duration while containing only zeros; our WAV silence check covers that separate condition.

Keep delivery and duration decisions separate

Tornado's job-status reference exposes job status and delivery information. Retain the job ID and inspect the exact delivered artifact before handing it downstream. The comparison above belongs to your application's validation policy; it is not a new Tornado endpoint or a claim about frame-accurate trimming.

Do not resubmit the source job merely because your comparison returned unknown. A missing measurement may require another inspection method rather than another acquisition. Keep the failed inspection, mismatched output, and failed ingestion as distinct outcomes so retries target the right step.

Build your first Tornado media workflow with one authorized source, record the intended output, and add a duration gate alongside format, completeness, and content checks before scaling.