Customize FFprobe Metadata Output as JSON

If you’ve worked with media files on the command line, you’re probably familiar with FFmpeg. But not everyone knows about its quieter, metadata-loving sibling: ffprobe.

In this article, you’ll learn how to:

• Use ffprobe to extract structured metadata from video and image files
• Suppress the noisy banner output
• Format the output as JSON
• Use jq to extract just the fields you care about
• Wrap all of this in a Bash function for clean, reusable scripting

What Is ‘ffprobe’ (and How Is It Different from ‘ffmpeg’)?

While ffmpeg is designed for media processing — transcoding, muxing, filtering, and converting — ffprobe is designed purely for analyzing media files. It gives you detailed information about formats, streams, codecs, resolution, colorspace, framerate, and embedded metadata.

Think of ffprobe as the ffmpeg version of exiftool for video, audio, and image containers.

Key ffprobe Flags You Should Know

Here are a few of the most essential ffprobe flags:

You can combine these like so:

ffprobe -v quiet -hide_banner -print_format json -show_format -show_streams myfile.avif

Why JSON? Why jq?

JSON is machine- and human-readable, and using tools like jq you can programmatically filter or extract exactly the data you need — no regex hacks, no fragile greps.

Here’s how you can extract just the video codec and resolution of the first stream:

ffprobe -v quiet -hide_banner -print_format json \
  -show_streams myfile.avif | jq '.streams[0] | {codec_name, width, height}'

It should output something like this JSON:

{
  "codec_name": "av1",
  "width": 1170,
  "height": 659
}

Example: Extract Useful AVIF Metadata

Let’s say you’re working with .avif images and just want:

• The container format
• The "compatible_brands" tag
• Key per-stream info like codec_name, pix_fmt, and resolution

Here’s a raw one-liner (no Bash function yet):

ffprobe -v quiet -print_format json -show_format -show_streams -hide_banner duluth-childhood.avif |
  jq '{
    filename: .format.filename,
    format: .format.format_long_name,
    compatible_brands: .format.tags.compatible_brands,
    streams: [.streams[] | {
      index,
      codec_name,
      pix_fmt,
      width,
      height,
      color_space,
      color_range,
      color_transfer
    }]
  }'

This outputs a clean, color-coded JSON summary:

{
  "filename": "duluth-childhood.avif",
  "format": "QuickTime / MOV",
  "compatible_brands": "avifmif1miaf",
  "streams": [
    {
      "index": 0,
      "codec_name": "av1",
      "pix_fmt": "yuv420p",
      "width": 1170,
      "height": 659,
      "color_space": "smpte170m",
      "color_range": "pc",
      "color_transfer": "iec61966-2-1"
    },
    {
      "index": 1,
      "codec_name": "av1",
      "pix_fmt": "gray",
      "width": 1170,
      "height": 659,
      "color_space": null,
      "color_range": "pc",
      "color_transfer": null
    }
  ]
}

Add a Bash Function for Reuse

You can drop this into your ~/.profile, ~/.zshrc, ~/.bashrc, or ~/.zprofile to create a permanent helper function:

ffprobe_json() {
  local file_path="$1"

  if [[ -z "$file_path" ]]; then
    echo "Usage: ffprobe_json <media-file>" >&2
    return 1
  fi

  ffprobe -v quiet -print_format json -show_format -show_streams -hide_banner "$file_path" |
    jq '{
      filename: .format.filename,
      format: .format.format_long_name,
      compatible_brands: .format.tags.compatible_brands,
      streams: [.streams[] | {
        index,
        codec_name,
        pix_fmt,
        width,
        height,
        color_space,
        color_range,
        color_transfer
      }]
    }'
}

Then you can use it like:

ffprobe_json duluth-childhood.avif

Conclusion

With ffprobe, structured media introspection is just a command away. By suppressing verbose banners and leveraging JSON output, you can cleanly extract metadata for automation, reporting, or debugging. Pair it with jq and a few reusable functions in your shell, and you’ve got a powerful CLI toolkit for working with AVIF, MP4, and virtually any other multimedia format.