FFprobe Analysis

Extract detailed technical metadata from your media files using FFprobe. Analyze format properties, stream details, and frame-level data to understand your media content.

What is FFprobe?

FFprobe is a powerful media analysis tool that extracts technical information from audio and video files. Our API makes it accessible via simple HTTP requests, perfect for:

Quality Control: Verify codecs, bitrates, and dimensions
Content Analysis: Extract metadata for cataloging and search
Debugging: Identify issues with media files
Automation: Build workflows that depend on media properties

Quick Start

📋

FFprobe requires files to be uploaded first. See File Management for the complete workflow.

1. Upload a File

# Register file
curl -X POST https://api.ffmpeg-api.com/file \
  -H "Authorization: Basic YOUR_API_KEY" \
  -d '{"file_name":"video.mp4"}'
 
# Upload to the returned presigned URL
curl -X PUT "$UPLOAD_URL" --data-binary @video.mp4

2. Analyze with FFprobe

curl -X POST https://api.ffmpeg-api.com/ffprobe/analyze \
  -H "Authorization: Basic YOUR_API_KEY" \
  -d '{
    "file_path": "dir_abc123/video.mp4",
    "probe": {
      "format": ["duration", "size"],
      "streams": ["codec_name", "width", "height"]
    }
  }'

API Reference

Endpoint: POST /ffprobe/analyze

Example Request

{
  "file_path": "dir_id/filename.ext",
  "probe": {
    "format": ["duration", "size", "bit_rate"],
    "streams": ["codec_name", "width", "height"],
    "select_streams": "v:0"
  }
}

Example Response

{
  "ok": true,
  "result": {
    "format": {
      "duration": "120.5",
      "size": "15728640",
      "bit_rate": "1048576"
    },
    "streams": [
      {
        "codec_name": "h264",
        "width": 1920,
        "height": 1080
      }
    ]
  },
  "usage": {
    "time_sec": 2.1,
    "input_size_gb": 0.015,
    "output_size_gb": 0.0001,
    "gb_sec": 0.0315
  }
}

Probe Options

The probe object controls what information FFprobe extracts. All fields are optional.

Section Arrays

Specify which sections to include and which fields to return:

Section	Description	Common Fields
`format[]`	File format information	`duration`, `size`, `bit_rate`, `format_name`
`streams[]`	Stream properties	`codec_name`, `width`, `height`, `sample_rate`
`chapters[]`	Chapter information	`id`, `start_time`, `end_time`, `title`
`programs[]`	Program data (MPEG-TS)	`program_id`, `nb_streams`, `streams`
`frames[]`	Frame-level data	`pkt_pts_time`, `key_frame`, `pict_type`
`packets[]`	Packet-level data	`pts_time`, `dts_time`, `size`, `flags`

Control Options

Option	Type	Description	Example
`select_streams`	String	Select specific streams	`"v:0"`, `"a"`, `"s:1"`
`read_intervals`	String	Limit analysis to time/frame ranges	`"0%+10"`, `"#500"`
`count_frames`	Boolean	Count frames without dumping data	`true`
`analyzeduration`	String	Analysis time limit	`"10s"`
`probesize`	String	Probe size limit	`"10M"`

Common Use Cases

Basic File Information

Get essential file properties:

{
  "file_path": "dir_123/video.mp4",
  "probe": {
    "format": ["duration", "size", "bit_rate", "format_name"]
  }
}

Video Stream Analysis

Analyze video properties:

{
  "file_path": "dir_123/video.mp4",
  "probe": {
    "streams": ["codec_name", "width", "height", "bit_rate", "r_frame_rate"],
    "select_streams": "v:0"
  }
}

Audio Stream Analysis

Get audio codec and quality info:

{
  "file_path": "dir_123/audio.mp3",
  "probe": {
    "streams": ["codec_name", "sample_rate", "channels", "bit_rate"],
    "select_streams": "a"
  }
}

Frame Counting

Count frames without extracting frame data:

{
  "file_path": "dir_123/video.mp4",
  "probe": {
    "streams": ["nb_frames", "nb_read_frames"],
    "select_streams": "v:0",
    "count_frames": true,
    "read_intervals": "0%+10"
  }
}

Keyframe Analysis

Find keyframes for thumbnail generation:

{
  "file_path": "dir_123/video.mp4",
  "probe": {
    "frames": ["pkt_pts_time", "key_frame", "pict_type"],
    "select_streams": "v:0",
    "skip_frame": "nokey",
    "read_intervals": "0%+30"
  }
}

Error Detection

Check for media file issues:

{
  "file_path": "dir_123/video.mp4",
  "probe": {
    "format": [],
    "streams": [],
    "error": []
  }
}

Advanced Features

Stream Selection

Use select_streams to target specific streams:

"v:0" - First video stream
"a" - All audio streams
"s:1" - Second subtitle stream
"v:0,a:0" - First video and audio streams

Read Intervals

Limit analysis to specific time ranges:

"0%+10" - First 10 seconds
"30%+5" - 5 seconds starting at 30%
"#500" - First 500 frames
"10%+#100" - 100 frames starting at 10%

Resource Limits

The API enforces limits to prevent abuse:

Analysis Duration: Maximum 60 seconds
Probe Size: Maximum 50MB
Frame/Packet Limits: 30 seconds or 3000 frames when requesting frame/packet data

Best Practices

Performance Optimization

Use specific field names instead of empty arrays when possible
Limit read intervals for frame/packet analysis
Use count_frames instead of dumping all frame data
Select specific streams to reduce output size

Error Handling

const response = await fetch('/ffprobe/analyze', {
  method: 'POST',
  headers: { 'Authorization': 'Basic YOUR_API_KEY' },
  body: JSON.stringify({
    file_path: 'dir_123/video.mp4',
    probe: { format: [], streams: [] }
  })
});
 
const data = await response.json();
 
if (!data.ok) {
  console.error('Analysis failed:', data.error);
  return;
}
 
console.log('File duration:', data.result.format.duration);
console.log('Video codec:', data.result.streams[0].codec_name);

Integration Examples

Quality Control Workflow

async function validateVideo(filePath) {
  const response = await fetch('/ffprobe/analyze', {
    method: 'POST',
    headers: { 'Authorization': 'Basic YOUR_API_KEY' },
    body: JSON.stringify({
      file_path: filePath,
      probe: {
        format: ['duration', 'bit_rate'],
        streams: ['codec_name', 'width', 'height', 'bit_rate'],
        select_streams: 'v:0'
      }
    })
  });
 
  const data = await response.json();
 
  if (!data.ok) {
    throw new Error(`Analysis failed: ${data.error}`);
  }
 
  const video = data.result.streams[0];
 
  // Validate requirements
  if (video.width < 1280) {
    throw new Error('Video too small: minimum 1280px width required');
  }
 
  if (video.codec_name !== 'h264') {
    throw new Error('Invalid codec: H.264 required');
  }
 
  return {
    duration: parseFloat(data.result.format.duration),
    resolution: `${video.width}x${video.height}`,
    codec: video.codec_name,
    bitrate: parseInt(video.bit_rate)
  };
}

Thumbnail Generation

async function getKeyframes(filePath) {
  const response = await fetch('/ffprobe/analyze', {
    method: 'POST',
    headers: { 'Authorization': 'Basic YOUR_API_KEY' },
    body: JSON.stringify({
      file_path: filePath,
      probe: {
        frames: ['pkt_pts_time', 'key_frame'],
        select_streams: 'v:0',
        skip_frame: 'nokey',
        read_intervals: '0%+60' // First minute
      }
    })
  });
 
  const data = await response.json();
 
  if (!data.ok) {
    throw new Error(`Keyframe analysis failed: ${data.error}`);
  }
 
  return data.result.frames
    .filter(frame => frame.key_frame === 1)
    .map(frame => parseFloat(frame.pkt_pts_time));
}

Troubleshooting

Common Issues

“select_streams is required when requesting frames or packets”

Add select_streams when using frames[] or packets[]
Example: "select_streams": "v:0"

“read_intervals duration cannot exceed 30s”

Reduce the time range in read_intervals
Use frame-based limits instead: "#1000"

“probesize cannot exceed 50MB”

Reduce the probesize value
Use time-based analysis instead: "analyzeduration": "10s"

Validation Errors

The API validates all parameters to prevent security issues:

Field names must be alphanumeric with underscores only
Stream selectors must match FFmpeg format (v:0, a, etc.)
Read intervals must use valid syntax (0%+10, #500)

⚠️

Invalid parameters will return a 400 Bad Request error with details about what needs to be fixed.

Ready to analyze your media? Check out the API Reference for complete endpoint documentation, or explore Examples for production-ready code samples.

Examples API Reference