Inspect Media Container Structure Using ffprobe

Analyzing the internal layout of video and audio files is crucial for troubleshooting playback, editing, and transcoding issues. This article provides a practical guide on how to use ffprobe, a powerful command-line tool bundled with FFmpeg, to inspect media container structures, view stream metadata, identify codecs, and extract packet-level details.

Basic Container Inspection

To get a quick overview of a media file’s container, streams, and metadata, run ffprobe followed by the filename. By default, this outputs a lot of build information. You can use the -hide_banner flag to suppress the build configuration and focus only on the media details:

ffprobe -hide_banner input.mp4

The output will display the container format (e.g., QuickTime/MP4), the duration, start time, overall bitrate, and a list of internal streams (such as video, audio, and subtitle tracks) along with their respective codecs and resolutions.

Outputting in Structured Formats (JSON, XML, CSV)

If you need to programmatically parse the container’s structure, ffprobe can format its output as JSON, XML, or CSV (flat writer). The following command extracts format and stream information and outputs it in clean JSON:

ffprobe -v error -show_format -show_streams -of json input.mp4

• -v error: Suppresses all logs except actual errors, keeping the output clean.
• -show_format: Displays container-level metadata (duration, size, bit rate, format name).
• -show_streams: Displays detailed information about each individual stream inside the container.
• -of json: Specifies the output format as JSON.

Inspecting Specific Streams

Media containers often hold multiple streams. You can isolate and inspect a specific stream, such as the video track, using the -select_streams option.

For example, to view only the codec name and pixel format of the first video stream:

ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,pix_fmt -of default=noprint_wrappers=1 input.mp4

• -select_streams v:0: Selects the first video stream (use a:0 for the first audio stream).
• -show_entries stream=codec_name,pix_fmt: Tells ffprobe to only display the specified fields.
• default=noprint_wrappers=1: Simplifies the output layout by removing the wrapper headers.

Analyzing Packets and Frames

For advanced debugging, you may need to look inside the container at the packet or frame level. This is useful for identifying issues with keyframe intervals, timecodes, or packet sizes.

To view information about every packet within the container:

ffprobe -v error -show_packets input.mp4

To view decoding details for individual frames (which includes picture types like I, P, or B-frames):

ffprobe -v error -show_frames input.mp4

Because packet and frame outputs can be massive, it is recommended to pipe the output to a text file or a pager like less:

ffprobe -v error -show_frames input.mp4 | less