Analyze media files with FFprobe

FFprobe is FFmpeg's inspection tool. It reads media files and returns metadata about the container, video streams, audio streams, codecs, and encoding settings. It does not transcode, compress, or modify the file in any way.

Think of it as a diagnostic scanner for video and audio files. Before you run an expensive transcoding job or try to process a file, you can use FFprobe to confirm the file is valid, check what codecs it uses, and make sure the format matches what your workflow expects.

FFprobe returns structured data about:

• Duration — total length in seconds, plus start time and bitrate
• Video codec — H.264, H.265, VP9, AV1, or whatever codec the file uses
• Resolution — width and height in pixels
• Frame rate — frames per second, both average and real-time base
• Bitrate — video bitrate and overall file bitrate
• Audio codec — AAC, MP3, Opus, or other audio format
• Audio channels — mono, stereo, or surround layout
• Sample rate — audio sample rate in Hz (usually 44100 or 48000)
• Stream layout — how many video and audio streams are in the file, and what order they appear
• Container format — MP4, WebM, MKV, MOV, AVI, or other wrapper format

This data lets you make smarter decisions before you spend processing time or quota on a job that might fail.

curl -X POST https://api.ffmpeg-micro.com/v1/ffprobe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "media_url": "gs://your-bucket/sample-video.mp4"
  }'

The media_url can point to a file in Google Cloud Storage, S3, or any publicly accessible HTTPS URL.

{
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "r_frame_rate": "30/1",
      "avg_frame_rate": "30/1",
      "bit_rate": "2500000",
      "duration": "120.500000",
      "nb_frames": "3615"
    },
    {
      "index": 1,
      "codec_name": "aac",
      "codec_type": "audio",
      "sample_rate": "48000",
      "channels": 2,
      "channel_layout": "stereo",
      "bit_rate": "128000",
      "duration": "120.500000"
    }
  ],
  "format": {
    "filename": "sample-video.mp4",
    "nb_streams": 2,
    "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
    "format_long_name": "QuickTime / MOV",
    "duration": "120.500000",
    "size": "40123456",
    "bit_rate": "2662000",
    "tags": {
      "major_brand": "isom",
      "minor_version": "512",
      "compatible_brands": "isomiso2avc1mp41",
      "encoder": "Lavf58.76.100"
    }
  }
}

The streams array contains one entry per video or audio stream. The format object describes the container and overall file properties.

Teams use FFprobe to:

• Validate uploads before processing — check if the file is corrupt, missing streams, or using an unsupported codec before you spend quota on a transcode job that will fail
• Check duration before billing — if you charge per minute of video processed, read the duration first so you can estimate cost and warn users about long files
• Detect multiple streams — some files have multiple audio tracks or embedded subtitles. FFprobe tells you what streams exist so you can map them correctly during transcoding
• Confirm resolution — if you only accept files under 4K, or you charge differently for HD vs SD, read the width and height before you process
• Choose the right transcoding path — if a file is already H.264 at 1080p, you might skip re-encoding and just copy the stream. FFprobe lets you detect that case
• Fail early on unsupported files — if a user uploads a proprietary codec or a broken file, FFprobe will surface that immediately instead of waiting for a transcode job to crash halfway through

Running FFprobe costs almost nothing compared to a full transcode, so it's worth doing upfront for any workflow where file validity matters.

FFprobe is designed to run before FFmpeg. You inspect the file, decide what operations to apply based on the metadata, then submit a transcode job with the settings that match the input.

For example: if FFprobe shows the file is 1920x1080 at 30fps, you might transcode it to 1280x720 at 30fps for web delivery. If it's already 720p, you skip the resize and just change the codec or bitrate.

If FFprobe reveals the file has no audio stream, you know not to specify audio codec options in your transcode request. If it has two audio tracks, you can pick which one to keep or mix both into a single stereo output.

This two-step pattern (inspect, then process) prevents wasted jobs and gives you fine control over what happens to each file.

Corrupt input — If FFprobe returns an error or missing stream data, the file is likely corrupt or incomplete. Re-upload or ask the user to export the file again from their editor.

Missing streams — Some export tools produce video-only or audio-only files. FFprobe will show a single stream in the streams array. This is valid, not an error. Just don't try to extract audio from a video-only file.

Unusual codecs — If the codec name is something obscure (like a proprietary format from a camera), you might need to reject the file or convert it locally before uploading. FFmpeg supports hundreds of codecs, but not every codec works in every container.

Inconsistent containers — A file with a .mp4 extension might actually be a different format. FFprobe reads the container signature, not the file extension, so it will tell you the real format in format_name.

Variable frame rate — If r_frame_rate and avg_frame_rate differ significantly, the file uses variable frame rate (VFR). This can cause sync issues during processing. Consider forcing a constant frame rate in your transcode options.