Video Frame Extractor: Scene Detection, Keyframes, Thumbnails

Takes direct links to video files and returns still frames with exact timestamps (timecodes): every N seconds, N evenly spaced frames, or one frame per scene change. Useful for thumbnails, contact sheets, datasets and feeding frames to AI vision models.

What you get

• JPG or PNG frames stored in the run's key-value store, with a link for each.
• Exact timecode for every frame (seconds and HH:MM:SS.mmm).
• Three modes: fixed interval, N evenly spaced frames, or scene-change detection.

Why this Actor

• No login and no platform scraping: you give direct video file URLs, nothing is downloaded from YouTube or social platforms.
• Timecodes included, so frames can be matched back to the video.
• Cost control: a per-video frame cap and the run's maximum charge setting.

Use cases

• Thumbnails and preview images for video libraries.
• Input frames for AI vision models and video search indexes.
• Building image datasets from video footage you own.
• Reviewing long recordings quickly through scene-change frames.

Quick start

Keep the example video (a short public-domain clip) and mode count, then press Start. Each frame becomes one row with an image link and its timecode. Switch mode to scene for footage with cuts.

Input

{ "videoUrls": ["https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"], "mode": "count", "frameCount": 3, "sceneThreshold": 0.3,
  "maxFramesPerVideo": 60, "format": "jpg", "maxWidth": 1280 }

Field	Meaning
mode	interval (every everySeconds), count (frameCount evenly spaced, centred in equal slices), scene (at scene changes)
maxFramesPerVideo	Hard cap, 1-500, default 60
format	jpg or png
maxWidth	Larger frames are scaled down (aspect ratio kept); never upscaled

Output

One dataset row per frame: videoUrl, frameIndex, timestampSeconds, timestamp (HH:MM:SS.mmm), imageUrl, imageKey, bytes, videoDurationSeconds. Images are stored in the run's key-value store. A video that fails gives one row with status: error and the reason.

Pricing

Pay per event: one frame-extracted event per frame returned. Failed or empty videos are not charged. Set a maximum charge per run to cap the cost.

Limits

• Direct video file URLs only (mp4, webm, mov, mkv...). Pages of YouTube, TikTok, Instagram, Facebook, X, Vimeo, Twitch and Niconico are rejected: this Actor does not download from platforms.
• Public hosts only (private and loopback addresses are refused, redirects are checked at every hop). Maximum 300 MB per video. Use videos you have the right to process.
• interval and count timestamps are the requested seek points; scene timestamps are the frame times reported by ffmpeg.
• Video decoding is done by ffmpeg (bundled through the imageio-ffmpeg package).

Run the tests

python -m unittest discover -s tests -t . (the ffmpeg tests make a 4-second clip and are skipped if ffmpeg is missing; no network access needed).

Related actors

• AI Crawler Checker & GEO / AEO Audit: check a site for AI search readiness (llms.txt, AI bots, JSON-LD).
• Stable Diffusion Prompt Extractor: read prompts and settings embedded in AI images.
• Japanese to Romaji, Hiragana & Furigana Converter: readings for Japanese text.
• Japan Diet Parliament Debates & Speeches Search: speeches from Japan's National Diet since 1947.