Video & Audio Toolkit — Probe, Cut, Convert, Extract Audio

A single cloud actor that replaces a local ffmpeg / ffprobe / yt-dlp install. Give it a media URL (or a page URL) and get back metadata, a mono speech track for transcription, a lightweight 480p analysis proxy, trimmed segments, or a clean H.264/AAC faststart MP4.

Use it when you need to:

• read video metadata (duration, resolution, fps, codecs, streams) before processing
• extract 16 kHz mono audio to feed a speech-to-text model
• build a 480p proxy so face detection / scene analysis costs a fraction of the master
• cut one or many time windows out of a long video without re-encoding
• download a video by page URL, or just resolve its direct media URLs
• remux / ingest any container into a browser-friendly MP4
• grab one window of audio or video straight from a page URL, so you can fan out hundreds of parallel shards without ever hosting the full file

Everything runs headlessly on CPU. No GPU, no local installs, no desktop software.

Quick start

{
  "op": "probe",
  "source": "https://example.com/video.mp4"
}

Feature-detect the build (free, a few seconds, needs no source):

{ "op": "capabilities" }

Operations

op	What it does	Needs source
probe	ffprobe metadata: duration, size, streams, codecs, fps	yes
plan_shards	split a duration into shards for parallel processing	yes
audio16k	mono speech audio (wav / mp3 / opus), optional time range	yes
proxy	fast 480p analysis proxy (audio kept by default)	yes
cut	trim one or many segments, stream copy or re-encode	yes
ytdlp	download by page URL (cookies / proxy supported)	yes (page URL)
resolve	print the direct media URLs only, no download	yes (page URL)
audio_shard	resolve + range-read + encode ONE audio window in one run	yes (page URL)
video_window	resolve + range-read + cut ONE full-res video window	yes (page URL)
audio_full	download the whole audio track once and host it	yes (page URL)
ingest	download and guarantee H.264/AAC faststart MP4	yes
remux	any container/codec → faststart MP4 (stream copy when possible)	yes
capabilities	report ops, features and vCPUs of this build	no

source accepts an https:// URL or kv:<storeId>/<key> pointing at a record produced by an earlier run, so actors can be chained without downloading anything to your machine.

Examples

Extract speech audio for transcription

{
  "op": "audio16k",
  "source": "https://example.com/interview.mp4",
  "options": { "format": "wav", "sample_rate": 16000 }
}

Build a 480p analysis proxy

{
  "op": "proxy",
  "source": "https://example.com/podcast.mp4",
  "options": { "height": 480, "fps": 15, "crf": 28, "audio": true }
}

Cut three highlight segments (no re-encode)

{
  "op": "cut",
  "source": "https://example.com/stream.mp4",
  "options": {
    "segments": [
      { "start_sec": 12.4, "end_sec": 41.0, "name": "hook" },
      { "start_sec": 320, "end_sec": 372, "name": "tip" }
    ]
  }
}

One audio window straight from a page URL (fan-out friendly)

{
  "op": "audio_shard",
  "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
  "options": { "start_sec": 600, "duration_sec": 240, "format": "mp3", "bitrate": "64k" }
}

Output

Every run pushes one dataset item:

{
  "status": "success",
  "op": "audio16k",
  "artifacts": [
    { "name": "audio16k", "kv_key": "audio16k.wav", "url": "https://api.apify.com/v2/key-value-stores/.../audio16k.wav", "bytes": 5412233 }
  ],
  "meta": { "duration_sec": 338.4, "sample_rate": 16000, "channels": 1 }
}

• artifacts[].url is a public URL you can hand straight to the next actor.
• artifacts[].kv_key is the key inside this run's key-value store (kv:<storeId>/<key>).
• meta carries per-op details (probe streams, shard plan, proxy dimensions, offsets...).

Set output.signed_upload_url to have the artifact PUT directly into your own storage (S3, R2, GCS) so heavy files never sit on Apify. Set callback: { "url": "...", "secret_header": { "name": "...", "value": "..." } } to be notified with the result JSON the moment the run finishes.

Error handling

Failures never return SUCCEEDED with zero items. You always get:

{ "ok": false, "reason": "UPSTREAM_BLOCKED", "message": "..." }

reason	Meaning	What to do
BAD_INPUT	missing/invalid source or options	check the payload against the schema
UPSTREAM_BLOCKED	the host refused the download	pass options.cookies / options.apify_proxy
TIMEOUT	the operation exceeded the run timeout	raise timeoutSecs, or shard the work
OOM_LIMIT	not enough memory for this file	run with 16 GB, or use proxy / cut first
INTERNAL	unexpected failure	retry; open an issue with the run ID

Performance and cost

Operation	Typical memory	Typical time (1 h source)
probe, resolve, plan_shards	1–2 GB	a few seconds
audio16k, audio_full	4 GB	20–60 s
proxy	8–16 GB	1–4 min
cut, remux (stream copy)	4 GB	under 1 min
ingest (transcode)	16 GB	several minutes

16 GB (≈4 vCPU) is the recommended setting for anything that transcodes.

FAQ

Do I need ffmpeg installed? No. Everything runs in the actor.

Can I chain this with other actors? Yes — pass artifacts[].url or kv:<storeId>/<key> as the source of the next run.

Does it re-encode when cutting? Only if you ask for it (options.reencode). By default segments are stream-copied, which is fast and lossless.

How do I analyse a big video cheaply? Run proxy once and analyse the 480p copy. Results in normalised coordinates apply back to the master unchanged.

Can I avoid storing files on Apify? Yes — use output.signed_upload_url together with cleanup: "always".