Inspect a video file with ffprobe before processing it

Probe a media file before choosing an encoding plan. A filename ending in .mp4 does not establish that the file contains a usable video stream, a known duration or the dimensions an export workflow expects. Treat the probe result as input that still needs validation.

Ask for structured metadata

The following command requests a compact JSON response for an authored local fixture. It reads media metadata; it does not upload the file.

ffprobe -v error -show_entries format=duration:stream=index,codec_type,width,height -of json fixture.mp4

Inspect the exit status before parsing stdout. Then select the video stream according to the application's policy. A file can have several video streams, including an attached image, so blindly taking the first object in the JSON array can select the wrong source.

Probe metadata is validated before an encoding plan is accepted; a valid probe alone does not verify every frame.

Reject an incomplete plan

This synthetic validation example illustrates the minimum checks for one selected stream. A real importer also needs a timeout and a policy for unknown duration.

import math

probe = {"format": {"duration": "2.0"},
         "streams": [{"codec_type": "video", "width": 640, "height": 360}]}
video = next(s for s in probe["streams"] if s["codec_type"] == "video")
duration = float(probe["format"]["duration"])
assert math.isfinite(duration) and duration > 0
assert video["width"] > 0 and video["height"] > 0

Do not convert a missing value to zero and continue as if the file were valid. Show a controlled import error or choose a separate streaming-input workflow. Retain a short diagnostic category without logging private filenames or the entire source directory.

Check the actual decode path

A successful probe does not prove that every frame will decode or that the selected encoder is available. After metadata validation, run a small decode or encode check appropriate to the intended output. Keep cancellation available when inspecting a large or malformed file.

The local authoring environment includes FFmpeg and FFprobe 8.0.1. A disposable generated video can verify the command's JSON shape and dimensions without customer media. The code fixture is synthetic and makes no claim about imported production files.

The FFprobe documentation explains show_entries and JSON output. ShortForge is a related desktop-video project; this example is a standalone diagnostic rather than a claim that its current importer performs these exact checks.