# FFprobe Video Metadata: Duration, Codec & Resolution (Bulk) (`data-done-right/ffprobe-video-metadata`) Actor

Get video metadata for a list of video file URLs: duration, container, video and audio codec, resolution, frame rate, bitrate, rotation, audio channels and tags. Reads the header with HTTP range requests, no full download. Direct files only, no YouTube.

- **URL**: https://apify.com/data-done-right/ffprobe-video-metadata.md
- **Developed by:** [Data Done Right](https://apify.com/data-done-right) (community)
- **Categories:** Videos, Developer tools, Automation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.20 / 1,000 video probeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## FFprobe Video Metadata: Duration, Codec & Resolution (Bulk)

Get the **video metadata** of a whole list of video file URLs with **ffprobe in the cloud**: duration, container, video and audio codec, resolution, frame rate, bit rate, rotation, audio channels and the file tags, one row per URL. The Actor reads only the **header of each file with HTTP range requests**, so a multi-gigabyte video is probed in seconds instead of being downloaded.

> **What it does not do.** It reads **direct file URLs** (mp4, mov, webm, mkv, avi, flv, ts, mp3 and other audio/video files). It does **not** read YouTube, Vimeo, TikTok, Instagram or other streaming-site pages and rejects them without charge. HLS/DASH playlists (.m3u8, .mpd) are not supported. It reads metadata only: it does not decode, convert, cut or analyse the picture. Files behind a login are not reachable. Use it only on files you have the right to access.

**What you get**

- One dataset row per URL: duration, container, codecs, width and height, fps, bit rates, rotation, HDR flag, audio channels and sample rate, file size, tags, and a clear status or error.
- Large files are probed from their first and last few MB (range requests); if the header is elsewhere, the Actor downloads the file once (up to a cap you set) and says so in the row.
- Failed, rejected and non-video links never stop the run and are free.

### How to get the duration and resolution of many videos from URLs

1. Paste direct video file links in `videoUrls`, for example `https://example.com/clip.mp4`.
2. Run it. Each URL becomes one row, in input order, with `durationSeconds`, `durationTimecode`, `width`, `height`, `fps`, `videoCodec`, `audioCodec` and more.
3. Export the dataset as CSV, Excel or JSON, or read it through the API.

### How to check a video file without downloading it

Leave `fullDownloadFallback` on and `headTailMb` at 4. The Actor asks the server for the first 4 MB and the last 4 MB (most mp4, mov, mkv, webm, avi, flv and ts files keep their header in one of the two) and runs ffprobe on them. The row's `probeMethod` shows what happened: `range` (head and tail read), `range-full` or `full` (the file was small enough to read completely), `stream-head` (the server ignores range requests, so only the start was read; duration may be missing and `partialProbe` is true).

### How to find broken or non-video links in a list

Run your list and filter on `status`. `error` rows explain why: a web page instead of a file, HTTP 404, a streaming-site link, a private address, an unreadable or corrupt file. Only `ok` rows are charged.

### How to read audio files too

Audio files (mp3, wav, flac, m4a, ogg) work the same way: `hasVideo` is false and the audio fields are filled.

### Input

| Field | Default | What it does |
|---|---|---|
| `videoUrls` | sample video | Direct file links, one result row each (required). |
| `deduplicate` | on | Probe each distinct URL once. |
| `maxVideos` | 1000 | Hard cap per run (max 10000). |
| `includeStreams` | off | Add a `streams` list with every stream's details. |
| `headTailMb` | 4 | MB fetched from the start and from the end of each file. |
| `fullDownloadFallback` | on | Download the whole file if the header is not at the start or end. |
| `maxDownloadMb` | 200 | Largest file the fallback may download (max 2048). |
| `videoTimeoutSecs` | 90 | Time limit per video. |
| `concurrency` | 5 | Videos read in parallel (max 20). |

Input example:

```json
{
  "videoUrls": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
    "https://upload.wikimedia.org/wikipedia/commons/c/c0/Big_Buck_Bunny_4K.webm"
  ],
  "includeStreams": false
}
```

### Output

From a real local run on the first URL above (`tags` shortened):

```json
{
  "index": 1,
  "sourceUrl": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "status": "ok", "error": null, "note": null,
  "probeMethod": "range-full", "partialProbe": false, "contentType": "video/mp4", "fileSizeBytes": 1128375,
  "container": "mov,mp4,m4a,3gp,3g2,mj2", "containerName": "QuickTime / MOV",
  "durationSeconds": 5.055, "durationTimecode": "00:00:05.055", "bitRate": 1785756,
  "hasVideo": true, "hasAudio": true, "videoStreams": 1, "audioStreams": 1, "subtitleStreams": 0,
  "videoCodec": "h264", "videoProfile": "High", "width": 960, "height": 540, "rotation": 0,
  "aspectRatio": "16:9", "fps": 29.97, "frameCount": 150, "pixelFormat": "yuv420p", "hdr": false, "videoBitRate": 1538137,
  "audioCodec": "aac", "audioChannels": 2, "audioChannelLayout": "stereo", "audioSampleRate": 48000,
  "audioBitRate": 256000, "audioLanguage": "und",
  "title": null, "creationTime": "2018-03-07T15:21:21.000000Z", "encoder": null,
  "tags": {"major_brand": "mp42", "creation_time": "2018-03-07T15:21:21.000000Z"},
  "streams": null
}
```

The second URL, a 2.96 GB 4K WebM, was read with two range requests (`probeMethod: "range"`) and reported 634.553 s, 4000x2250, VP8 video and 5.1 Vorbis audio; the whole local run took about five seconds. An `error` row looks like `{"status": "error", "error": "www.youtube.com is a video site page, not a direct video file...", "videoCodec": null}`.

Field notes: `width` and `height` are the coded size; if `rotation` is 90 or 270 a player shows them swapped. `fps` is the stream's average frame rate; absurd values stored in a file (above 1000) are dropped. `bitRate` is read from the file or, when missing, estimated from size and duration. The `SUMMARY` record in the key-value store counts ok, failed and skipped videos.

### Use with the Apify API, MCP, n8n and Make

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("data-done-right/ffprobe-video-metadata").call(run_input={
    "videoUrls": ["https://example.com/a.mp4", "https://example.com/b.mov"]})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["sourceUrl"], row["durationSeconds"], row["width"], row["height"], row["error"])
```

JavaScript:

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: '<APIFY_TOKEN>' });
const run = await client.actor('data-done-right/ffprobe-video-metadata').call({
  videoUrls: ['https://example.com/a.mp4'], includeStreams: true });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

In n8n or Make use the Apify node with the Actor name and the same JSON. With Apify's MCP server (mcp.apify.com) an AI assistant can call it: "what codec and resolution is this mp4?" Only a URL is needed.

### Use cases

- Audit a media library or CDN: find files over a resolution, duration or bit-rate limit.
- Check uploads before they enter an encoding pipeline: readable, expected codec, has audio.
- Sort a list of clips by duration or orientation (rotation) before editing.
- Find videos without an audio track, or with more than one.
- Build a catalogue of video files with size, duration and creation date.

### How much does it cost

Pay per event: **$0.004 per video probed** (`video-probed`, $4 per 1,000). Failed and skipped links, rejected URLs and the `SUMMARY` record are free. Plan discounts apply (Silver about 10%, Gold and higher about 20%).

- 1,000 videos: $4.
- 10,000 videos: $40.
- 100,000 videos: $400.

`maxVideos` caps a run, and if you set a maximum spend per run the Actor stops cleanly when it is reached and marks the remaining rows `skipped`. The price is per video whatever its size; Apify platform usage is included.

### FAQ

#### Does it download the whole video?

Normally no: it fetches the first and last few MB with HTTP range requests. If the metadata sits somewhere else in the file (some mp4 files), it downloads the whole file once, up to `maxDownloadMb` (200 by default), and the row's `probeMethod` says `full`. Turn the fallback off with `fullDownloadFallback: false` if you never want that; such files then give an error row.

#### Which servers work?

Any public HTTP or HTTPS server. Servers that ignore range requests still work but only the start of the file is read, so formats that keep the duration at the end may show no duration (`partialProbe: true`). In local tests, mp4 (header at start or end), mov, mkv, webm, avi, flv, ts and mp3 files were read correctly from a range-capable test server; the large-file test was against Wikimedia. It has not been tested on Apify yet.

#### Can it read YouTube or other streaming links?

No. YouTube, Vimeo, TikTok, Instagram and similar page links are rejected with a message and no charge, as are m3u8/mpd playlists. Use a direct link to a media file.

#### Is the duration exact?

It is the duration stored in the file or computed by ffprobe from its header, the same value `ffprobe -show_format` prints. It is not measured by decoding the video. Broken or truncated files can report wrong values.

#### What about private or internal URLs?

Links to private, loopback and internal addresses are blocked, and every redirect hop is checked. ffprobe itself never opens a network connection; it only reads the local copy of the header bytes.

#### Which fields can be empty?

Everything that the file does not contain: `fps` and `frameCount` for audio files, audio fields for silent videos, `creationTime` and `title` when the tags are missing, `frameCount` for many mkv and ts files.

### Related tools

- **Video Frame Extractor: Keyframes, Scenes & Thumbnails for AI** pulls still images from the same videos.
- **Cut Video: Video Trimmer, Clip Cutter & Video to GIF** cuts clips out of the files you just checked.
- **Image Metadata & EXIF Extractor: GPS, Camera, Dates (Bulk)** does the same metadata job for photos.

# Actor input Schema

## `videoUrls` (type: `array`):

Direct links to video or audio files (mp4, mov, webm, mkv, avi, mp3...). Example: https://example.com/clip.mp4. One result row per URL. YouTube, Vimeo, TikTok and other streaming-site page links, and HLS/DASH playlists, are rejected and not charged.

## `deduplicate` (type: `boolean`):

Probe each distinct URL once, so a URL listed twice is not charged twice. Example: on.

## `maxVideos` (type: `integer`):

Hard cap on URLs processed in one run (also caps cost). Extra URLs are not processed and the run summary says how many. Example: 500.

## `includeStreams` (type: `boolean`):

Add a 'streams' list to each row with codec, size, frame rate, sample rate and language of every video, audio and subtitle stream. Example: off for the flat columns only.

## `headTailMb` (type: `number`):

How much of the start and of the end of each file is fetched with range requests (so up to twice this per video). 4 MB is enough for most files; raise it for very long videos with a large index. Example: 8.

## `fullDownloadFallback` (type: `boolean`):

If the metadata is not in the first and last bytes (some mp4 files store it in the middle), download the whole file once, up to 'Max full download'. Example: on.

## `maxDownloadMb` (type: `number`):

Largest file the fallback may download. Bigger files whose header is not at the start or end give an error row (not charged). Example: 500.

## `videoTimeoutSecs` (type: `number`):

Time limit for fetching and probing one video. Example: 120.

## `concurrency` (type: `integer`):

How many videos are read at the same time. Lower it if the file host rate-limits you. Example: 5.

## Actor input object example

```json
{
  "videoUrls": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
  ],
  "deduplicate": true,
  "maxVideos": 1000,
  "includeStreams": false,
  "headTailMb": 4,
  "fullDownloadFallback": true,
  "maxDownloadMb": 200,
  "videoTimeoutSecs": 90,
  "concurrency": 5
}
```

# Actor output Schema

## `results` (type: `string`):

One row per video URL with duration, codecs, resolution, frame rate, bitrate, audio details and status, as JSON, CSV, Excel and more.

## `records` (type: `string`):

Key-value store records: the SUMMARY of the run (counts of ok, failed and skipped videos).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "videoUrls": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("data-done-right/ffprobe-video-metadata").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "videoUrls": ["https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"] }

# Run the Actor and wait for it to finish
run = client.actor("data-done-right/ffprobe-video-metadata").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "videoUrls": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
  ]
}' |
apify call data-done-right/ffprobe-video-metadata --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,data-done-right/ffprobe-video-metadata"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/lXR82NP6A8j8gxh1S/builds/7wrJTFJP6lPqwIaV3/openapi.json