A reported frame rate cannot, by itself, establish the actual number of frames in a master. Multiplying duration by that rate gives an estimate under assumptions about timing and cadence; it is not a count of the frames ffprobe reads. For a file-level count, use -count_frames, select the intended video stream, and record the stream index and method with the result.
Decide what you are counting
A video file may contain more than one video stream, such as a main picture and an attached cover image. First identify the stream you intend to accept. In ffprobe output, each STREAM section has an index; stream indices are assigned according to the detected stream order. The v:0 selector means the first video stream, not necessarily stream index 0. Check the stream listing rather than assuming those numbers are the same.
Also define the count’s meaning. -count_frames asks ffprobe to count frames per stream and report the count in that stream’s section. It is different from reading a stream’s reported frame rate, and from counting packets: a packet count is not a frame count. Describe the result as the count reported by this ffprobe operation, not as proof that every frame represents unique motion or that playback is visually correct.
Count the intended stream
- List all streams without filtering:
ffprobe -v error -show_streams -show_entries stream=index,codec_type,codec_name,width,height -of json master.mp4. Identify the stream that corresponds to the master picture. Note its globalindexand identifying details. TheVstream type excludes attached pictures, video thumbnails, and cover art;vincludes them. Use the listing to decide which stream to count rather than assuming the first video stream is the master picture. - Count the confirmed stream. For example, if the intended stream is global index 1, run
ffprobe -v error -select_streams 1 -count_frames -show_streams -show_entries stream=index,codec_type,codec_name,width,height,avg_frame_rate,r_frame_rate,duration,nb_frames,nb_read_frames -of json master.mp4. Replace1with the confirmed global index. Check that the outputindexmatches the intended stream identified in step 1. If the master picture is confirmed to be the first video stream,v:0is also a valid selector, but it is a video-stream ordinal, not a global index. - Record the count field or fields actually present in the selected
STREAMentry, including their names and values. The official option description says-count_framescounts frames per stream and reports the count in the corresponding stream section; it does not specify a field name in that description. Do not assumenb_read_framesis present or treat it as interchangeable withnb_frameswithout verifying the output. Keepavg_frame_rateandr_frame_ratelabeled as reported rate fields, not counts. If a field is absent, record that fact rather than filling it with an inference. - If you need to inspect individual frame records, use
-show_frameswith the same stream selection. ffprobe emits a separateFRAMEsection for each frame it reports. This output can become very large for a long master, so use it when frame-level inspection is needed, not as a compact summary. - Save the file name, selected stream index, reported rate fields, duration field if present, count field, command, and any warnings or errors in the delivery record.
The options and output sections are documented in the ffprobe options reference. For stream selection and how a stream index is matched, see ffprobe stream specifiers.
Use rates as a cross-check, not a count
Suppose a hypothetical report lists a duration of 12 seconds and avg_frame_rate of 25/1. Multiplication gives 300 as a rough consistency estimate. If nb_read_frames reports 298, do not overwrite the count with 300 or assume the file is defective from this difference alone. Check that you selected the intended stream, inspect the available timing and count fields, and review ffprobe warnings. Duration and a reported rate do not necessarily encode the same counting convention or endpoint behavior.
| Hypothetical observation | What it supports | Next check |
|---|---|---|
Stream index 1; nb_read_frames 298 | ffprobe counted 298 frames for the selected stream | Confirm index 1 is the master picture |
Duration 12 s; avg_frame_rate 25/1 | A rate-duration estimate of 300 | Keep it labeled as an estimate |
nb_frames absent; nb_read_frames present | A reported frame-count field is unavailable, but a read count is available | Record the available field and method |
| Two video streams appear | The file has multiple candidates | Select the intended stream explicitly |
Handle a mismatch or an unusable report
If the count is missing, the command selected no stream, or the output reports an error, inspect the full stream listing and rerun against the identified video stream. For uncertain results, request -show_frames on that stream and inspect whether frame records are being emitted. ffprobe documents -show_frames as outputting information for each frame; it does not make a long report small. For a long file, redirecting output to a review file may help, but choose a location that will not overwrite the master.
A count alone cannot diagnose corruption, dropped motion, duplicate images, or visual quality. It records a counting result, not whether successive pictures contain new movement. If acceptance depends on cadence or repeated motion, inspect the relevant frames or use an appropriate visual review alongside the count. Do not treat a rate-duration product, packet count, or count from a different stream as a replacement.
Common questions
Is `nb_frames` the same as `nb_read_frames`?
Do not assume they are interchangeable. The -count_frames option is documented as reporting a per-stream count in the corresponding stream section, but that description does not name the output field. Inspect the actual output, record the field name and value it provides, and note any missing or differing fields instead of silently choosing a convenient number.
Should I count packets instead?
No, not when the deliverable requirement is a frame count. -count_packets counts packets per stream. Use the frame-count option for this question, and identify the stream being counted.
Does the count prove there are no duplicate frames?
No. It reports how many frames ffprobe counted, not whether each frame adds new motion information. That requires a separate inspection suited to the creative or technical requirement.
Sources and next step
This guide interprets public documentation and uses explicitly hypothetical acceptance examples, not application tests. Controls and availability can change; verify the cited manual against your installed version.
For work created in Imagild, carry the input requirements and acceptance checklist into the film workspace. The external software controls discussed above belong to their respective products.