Analyze media files with FFprobe

What FFprobe does

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.

Metadata Fields

The API runs FFprobe on your file and returns these fields:

• duration_seconds: total length in seconds
• format: the container, as FFprobe names it (an MP4 reads mov,mp4,m4a,3gp,3g2,mj2)
• size_bytes: file size
• width and height: video dimensions in pixels
• fps: frames per second
• codec_video: the video codec, such as h264, hevc or vp9
• codec_audio: the audio codec, such as aac, mp3 or opus
• has_video and has_audio: whether the file has a video stream and an audio stream

The dimension, frame rate and codec fields are left out when they do not apply: an audio file has no width, height, fps or codec_video. The first three are always present, and read 0 or unknown when FFprobe could not tell: a still image has a duration_seconds of 0. The API does not return bitrate, sample rate, channel layout or a per-stream list.

Request

Send the address of a file you have uploaded. It is the fileUrl that POST /v1/upload/confirm returned:

curl -X POST https://api.ffmpeg-micro.com/v1/ffprobe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "gs://<YOUR_BUCKET>/1234567890-video.mp4"
  }'

The call creates no job and uses no tokens. It is limited to 30 requests a minute per API key, and your plan's file size limit applies.

Only uploaded files can be probed. A public HTTPS URL is answered with a 400 that says to upload the file first. The upload-confirm response already carries the same fields under result.metadata, so right after an upload you do not need this call at all.

Response

The address you sent, and the file's metadata:

{
  "url": "gs://<YOUR_BUCKET>/1234567890-video.mp4",
  "metadata": {
    "duration_seconds": 120.5,
    "format": "mov,mp4,m4a,3gp,3g2,mj2",
    "size_bytes": 40123456,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "codec_video": "h264",
    "codec_audio": "aac",
    "has_video": true,
    "has_audio": true
  }
}

Errors

• 400: the url is missing, is not a gs:// address, or names a bucket that is not your upload bucket
• 401: the API key is missing or not recognised
• 404: no uploaded file has that address
• 422: the file is over your plan's size limit, or FFprobe could not read it as audio, video or an image
• 429: more than 30 requests in a minute
• 502: the probe could not run right now; try again

Use Cases

Teams use FFprobe to:

• Validate uploads before processing: a file FFprobe cannot read comes back as a 422, before you spend tokens on a transcode job that would fail
• Check duration before billing: if you charge per minute of video processed, read duration_seconds first so you can estimate cost and warn users about long files
• Detect a missing audio track: has_audio tells you whether there is sound to keep, replace or transcribe
• Confirm resolution: if you only accept files under 4K, or you charge differently for HD and SD, read width and height before you process
• Choose the right transcoding path: if a file is already H.264 at 1080p, you might skip the resize and only change the container

A probe is free, so it is worth doing upfront for any workflow where file validity matters.

FFprobe Before FFmpeg

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 the probe shows the file is 1920x1080 at 30fps, you might transcode it to 1280x720 at 30fps for web delivery. If it is already 720p, you skip the resize.

If has_audio is false, you know not to ask for audio options in your transcode request. This two-step pattern (inspect, then process) prevents wasted jobs.

Troubleshooting

Corrupt input: a 422 with "Could not read media" means FFprobe could not parse the file. It is likely corrupt, incomplete, or not media at all. Re-upload it, or ask the user to export it again from their editor.

Video-only and audio-only files: some export tools produce one without the other. has_video or has_audio comes back false. This is valid, not an error.

Cover art: artwork embedded in an audio file is a video stream to FFprobe. An MP3 with cover art reports has_video: true with the artwork's dimensions.

Rotated video: width and height are the stored dimensions, before any rotation the file carries. A phone video shot upright can report 1920 by 1080.

Mismatched extensions: a file named .mp4 might be a different format. FFprobe reads the container itself, not the file name, so format tells you what it really is.

Related