# How to use ffprobe to see what is inside a video file

> Learn how to use ffprobe on a Mac to inspect video codecs, audio streams, bitrates, and HDR transfer metadata in plain text or structured JSON.

Published 2026-10-31 · Libraries & tools · https://www.hazenstudio.com/maclc/blog/how-to-use-ffprobe/

## In short

- ffprobe is a lightweight stream analyzer bundled with FFmpeg that inspects container and codec metadata without decoding frames.
- Using -select_streams v:0 allows you to isolate video track properties like resolution, frame rate, and pixel format.
- Inspecting color_primaries and color_transfer reveals whether a file is standard SDR (BT.709) or genuine HDR (BT.2020 / PQ / HLG).
- MacLC shows the HDR side of this without a terminal: badges in its library, the format card when a film opens, and the live panel in Settings › HDR & Colour.

The command `ffprobe` is a lightweight multimedia stream analyzer bundled with FFmpeg that displays detailed technical metadata about containers, video tracks, audio channels, and subtitles. Unlike video editors that take minutes to scan a file, `ffprobe` reads file headers and packet indexes in milliseconds without decompressing audio samples or video frames.

Whether you need to verify if a downloaded movie has true 10-bit HDR color, check which audio channels are present, or pipe structured JSON metadata into an automated encoding script, `ffprobe` is the standard tool. Below is a guide to using `ffprobe` on macOS to inspect codecs, extract HDR parameters, and interpret output.

## What is ffprobe and how do you run it on a Mac?

When you install FFmpeg on an Apple Silicon Mac using Homebrew (`brew install ffmpeg`), Homebrew places two primary tools in `/opt/homebrew/bin/`: the converter `ffmpeg` and the analyzer `ffprobe`. While `ffmpeg` is designed to process and write new files, `ffprobe` is strictly a read-only diagnostics tool.

If you run `ffprobe` with only an input file path, it outputs everything it can find:

```bash
ffprobe input.mp4
```

By default, `ffprobe` prints several lines of compiler build flags followed by the container metadata and stream details. To silence the multi-line build banner and make your terminal output concise, always add the `-hide_banner` flag:

```bash
ffprobe -hide_banner input.mp4
```

Terminal will display a concise block detailing the container format, total duration, overall bitrate, and an enumerated list of every stream packed inside the file. Video streams list codec names (such as `h264`, `hevc`, or `av1`), pixel color formats, screen resolution, and frame rates. Audio streams display the audio codec (such as `aac`, `ac3`, or `flac`), sampling rates in Hertz, and channel layouts (such as `stereo` or `5.1(side)`).

If you want to understand how FFmpeg and its libraries process these streams during playback, read our foundational guide on [what is FFmpeg](/maclc/blog/what-is-ffmpeg/).

## How do you inspect specific video streams and codecs?

When inspecting files containing multiple audio languages, commentary tracks, and subtitle streams, raw `ffprobe` output can fill your entire terminal window. You can isolate specific streams and fields using the `-select_streams` and `-show_entries` flags.

### Listing all streams and their codecs:

To see a clean list of every stream without container clutter, run:

```bash
ffprobe -v error -show_entries stream=index,codec_name,codec_type -of default=noprint_wrappers=1 input.mkv
```

### Explaining the flags:
- `-v error`: Sets logging verbosity to errors only, hiding informational warnings and processing logs.
- `-show_entries stream=...`: Limits the output strictly to the specified stream fields (`index`, `codec_name`, `codec_type`).
- `-of default=noprint_wrappers=1`: Formats output as simple key-value pairs without enclosing structural block headers like `[STREAM]` and `[/STREAM]`.

### Inspecting video resolution, frame rate, and pixel format:

To isolate the primary video stream (stream index 0 of type video, written as `v:0`):

```bash
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate,pix_fmt -of default=noprint_wrappers=1 input.mp4
```

This returns four straightforward values:
- `width=3840` and `height=2160`: Confirms standard 4K Ultra HD resolution.
- `r_frame_rate=24/1`: The native frame rate expressed as an exact mathematical fraction (such as 24/1 for cinema or 24000/1001 for 23.976 fps).
- `pix_fmt=yuv420p10le`: The internal pixel format. The `10le` suffix stands for 10-bit little-endian color depth, confirming higher color precision than standard 8-bit (`yuv420p`).

*Dissecting an ffprobe command*

## How do you inspect HDR metadata and color transfer curves?

One of the most valuable uses of `ffprobe` is determining whether a 4K file contains genuine High Dynamic Range (HDR) mastering data or is merely standard dynamic range (SDR) in an oversized container. File names often boast "HDR" or "Dolby Vision", but file names are easily mislabeled.

To verify a video's color characteristics, query its color primaries, transfer characteristics, and matrix coefficients:

```bash
ffprobe -v error -select_streams v:0 -show_entries stream=color_space,color_primaries,color_transfer,pix_fmt -of default=noprint_wrappers=1 input.mkv
```

### How to interpret the output:

| Field | SDR (Standard Dynamic Range) | HDR10 / Dolby Vision | HLG (Broadcast HDR) |
| :--- | :--- | :--- | :--- |
| **`color_primaries`** | `bt709` | `bt2020` | `bt2020` |
| **`color_transfer`** | `bt709` | `smpte2084` (Perceptual Quantizer / PQ) | `arib-std-b67` (Hybrid Log-Gamma) |
| **`color_space`** | `bt709` | `bt2020nc` (Non-constant luminance) | `bt2020nc` |
| **`pix_fmt`** | `yuv420p` (8-bit) | `yuv420p10le` (10-bit) | `yuv420p10le` (10-bit) |

If `color_transfer` reports `smpte2084`, the file uses the SMPTE ST 2084 Perceptual Quantizer curve, which is the foundational transfer function for both HDR10 and Dolby Vision. If it reports `arib-std-b67`, the video uses Hybrid Log-Gamma, commonly used in television broadcasts and iPhone HDR recordings. For a comprehensive comparison of these formats, see our guide on [how to tell if a video is HDR](/maclc/blog/how-to-tell-if-a-video-is-hdr/).

### Inspecting mastering display luminance (MaxCLL and MaxFALL):

HDR10 files also include static metadata specifying the mastering monitor's peak brightness and the film's maximum light levels. To read this side data from the first video frame, run:

```bash
ffprobe -v error -select_streams v:0 -show_frames -read_intervals "%+#1" -show_entries frame=side_data_list -of json input.mkv
```

Look for the `Mastering display metadata` and `Content light level metadata` objects in the JSON response:
- `max_content`: Maximum Content Light Level (MaxCLL), indicating the brightest individual pixel in the entire video (e.g. 1,000 nits).
- `max_average`: Maximum Frame-Average Light Level (MaxFALL), indicating the highest average brightness of any single frame.

## How do you export ffprobe output as structured JSON?

If you are writing Python scripts, shell automations, or ingestion workflows, reading plain-text strings requires brittle regex parsing. Instead, instruct `ffprobe` to format its entire report as structured JSON by adding `-of json`:

```bash
ffprobe -v error -show_format -show_streams -of json input.mkv
```

The resulting output contains two top-level JSON objects:
1. `"streams"`: A list of objects containing every video, audio, and subtitle stream with its complete technical attributes.
2. `"format"`: An object containing container-level metadata, including filename, size in bytes, start time, total duration in fractional seconds, aggregate bitrate in bits per second, and container tags (such as title, artist, encoder version, and creation date).

You can pipe this output directly into modern command-line JSON processors like `jq`:

```bash
ffprobe -v error -show_format -of json input.mkv | jq '.format.bit_rate | tonumber / 1000000'
```

This single pipeline extracts the total stream bitrate, converts it to a number, and prints the overall bandwidth in megabits per second (Mbps). To learn what bitrates indicate high-fidelity video, read our guide on [what is bitrate](/maclc/blog/what-is-bitrate/).

## How does ffprobe compare to MediaInfo?

Both `ffprobe` and `MediaInfo` are widely respected open-source media inspection tools, but they appeal to different workflows.

`ffprobe` is part of the FFmpeg codebase. It requires no separate installation if you already have FFmpeg, and it is well suited for automated shell scripts, continuous integration pipelines, and headless server environments. However, reading raw `ffprobe` output requires familiarity with command-line flags and video engineering acronyms.

`MediaInfo`, developed by MediaArea, provides a dedicated graphical interface on macOS alongside its CLI. It organizes file metadata into structured Tree, Sheet, and Text views that group container, video, audio, and subtitle information into readable summaries. MediaInfo also specializes in decoding complex Dolby Vision Profile indicators (such as distinguishing Profile 5 from Profile 8.1) in explicit plain English.

If you prefer a visual desktop app with drag-and-drop convenience, MediaInfo is usually the friendlier choice. Learn how to install and configure it in our guide to [MediaInfo on Mac](/maclc/blog/mediainfo-on-mac/).

MacLC eliminates the need to run terminal commands to check your video files. Its library view displays instant 4K, HDR10, and Dolby Vision badges, while its built-in format card tells you which formats a movie carries and how it is rendered on your screen. Open Settings › HDR & Colour to see real-time bit depth, color primaries, and display headroom live during playback.

## What to do next

Using `ffprobe` is the most reliable way to verify what codecs and color spaces your video files use before archiving or converting them. Practice running `ffprobe -hide_banner` on a few files in your library, and use the `-select_streams v:0` recipes above to quickly check resolution and HDR metadata.

If you want to view detailed video information without opening Terminal every time, read our guide on [MediaInfo on Mac](/maclc/blog/mediainfo-on-mac/). And when you want to watch high-bitrate HDR10 and Dolby Vision films with automatic format detection and hardware acceleration on your Apple Silicon Mac, try [MacLC](/maclc/donate/).

## Questions people ask

### Where do I get ffprobe on a Mac?

ffprobe installs automatically whenever you install FFmpeg via Homebrew using brew install ffmpeg. It is located at /opt/homebrew/bin/ffprobe on Apple Silicon Macs.

### How do I check if a video is HDR using ffprobe?

Run ffprobe -v error -select_streams v:0 -show_entries stream=color_primaries,color_transfer input.mkv. If color_primaries shows bt2020 and color_transfer shows smpte2084 or arib-std-b67, the video is HDR.

### What is the difference between ffprobe and MediaInfo?

ffprobe is a command-line tool built into FFmpeg designed for terminal inspection and automated scripting with JSON output. MediaInfo provides both a terminal CLI and a native graphical desktop interface with tree and text views.

### Can ffprobe convert or re-encode video files?

No. ffprobe is strictly a read-only stream and format analyzer. To convert, remux, or edit media files, use the ffmpeg command instead.

---
MacLC is a free, open-source video player for Apple Silicon Macs: https://www.hazenstudio.com/maclc/ · download: https://www.hazenstudio.com/maclc/donate/