ffpipe — video conversion, probe & frames

extract_frames

Queue an asynchronous frame extraction - the tool to reach for when you need to SEE a video: fetches sourceUrl (or, with upload: true, waits for you to PUT the bytes to the returned uploadUrl) and extracts still frames as jpeg, webp or png. mode is REQUIRED and picks the sampling (all, every_nth, interval, keyframes, evenly_spaced, timestamps); there is no default because every candidate implies a rate you did not ask for. A finished job's resultUrl is a JSON MANIFEST: source display dimensions, fps, rotation, an echo of your parameters, frame_count, and one entry per frame with index, pts_time (seconds in the source) and its own download url on this gateway - fetch the manifest, then the frames you want. Up to 1000 frames per job; "all"/"interval" on a long source can exceed that and fail fast, so prefer interval, evenly_spaced or timestamps. Unreadable input, audio-only files and still images FAIL here (probe_media diagnoses those). Download within 24 hours. Paid: $0.03 USDC via x402 (base mainnet), or a frames-kind retryVoucher.

Input Schema

TableJSON Schema

Name	Required	Description
`n`	No	every_nth only: keep every Nth DECODED frame (a frame index, not a time).
`fps`	No	interval only: frames per second, may be below 1 (0.5 = one frame every two seconds).
`mode`	Yes	How to pick frames (required): "all" every frame; "every_nth" every Nth decoded frame (needs n); "interval" a fixed rate in seconds (needs fps, may be below 1); "keyframes" keyframes only, cheap on long sources; "evenly_spaced" count samples across the window (needs count); "timestamps" one frame per given second (needs timestamps).
`count`	No	evenly_spaced only: how many frames to spread across the window.
`format`	No	Image format of each frame, default jpeg (small and accepted by every vision API). png is lossless.
`upload`	No	Set true to upload the bytes yourself instead of giving a sourceUrl (exactly one of the two). The paid result then returns status awaiting_upload plus uploadUrl and uploadExpiresAt: HTTP PUT the raw bytes to uploadUrl before the deadline (201 -> queued). You are charged at acceptance; an abandoned upload window errors with no refund, while a pipeline failure after your upload earns a retryVoucher.
`endTime`	No	Window end in seconds (0 or omitted = to the end); must exceed startTime.
`quality`	No	Encoder quality for jpeg/webp, default 85; ignored for png.
`maxFrames`	No	Ceiling on frames produced, default and hard limit 1000. A request whose sampling would exceed it fails before any decoding.
`sourceUrl`	No	https URL of the input media (<= 100 MiB). Fetched from datacenter IP ranges - prefer a presigned URL from storage you control; no IP literals, no localhost/.internal/.local. Provide EXACTLY ONE of sourceUrl or upload.
`startTime`	No	Window start in seconds (default 0).
`timestamps`	No	timestamps only: seconds into the source, one accurate frame each. Sorted for you.
`retryVoucher`	No	Retry-voucher credential (`uuid.hmac`) from a failed paid job's status - pays for this call instead of x402. Single use, kind-matched.
`maxOutputWidth`	No	Fit box width applied to the source's DISPLAY dimensions: aspect preserved, never upscaled, oriented to the input. 0 = no limit on this axis.
`maxOutputHeight`	No	Fit box height, same rules as maxOutputWidth.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide no readonly, destructive, or idempotent hints, but the description fully compensates by detailing the async queue behavior, upload workflow, payment via x402 or retryVoucher, 24-hour download window, 1000-frame limit, and failure conditions (exceeding limit, unreadable input, audio-only, still images). This is far beyond what annotations offer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and front-loaded with the purpose, but it runs long (multi-sentence paragraph). Every sentence adds value, but the length could be slightly trimmed for quicker scanning. Still, it is well-organized and avoids redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (15 params, async queue, payment, upload options), the description covers all critical aspects: behavior, failure modes, pricing, voucher usage, and manifest format. No output schema exists, so the description's explanation of the result URL content is essential and well-handled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. However, the description adds significant value by explaining the absence of a default for mode (avoids assuming a rate), clarifying the upload flow (status awaiting_upload), and describing the manifest structure (resultUrl JSON). It also warns about the exact-one constraint between sourceUrl and upload, which is implicit in the schema. It does not explain every parameter in prose but compensates through rich context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queues asynchronous frame extraction for video, specifying output formats and the core requirement to 'SEE a video'. It is distinct from siblings like convert_video (which likely transforms format) and probe_media (which diagnoses files).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool (when you need to see a video), warns against using 'all'/'interval' on long sources, suggests preferring interval/evenly_spaced/timestamps, and mentions probe_media for diagnosing unreadable inputs. It also clarifies the upload vs sourceUrl distinction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ffpipe — video conversion, probe & frames tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0

Disambiguation4/5

Each tool targets a distinct capability: convert_video, extract_frames, probe_media, get_job_status, get_balance, and leave_feedback are clearly separated. However, there is a minor overlap potential between convert_video and extract_frames for users wanting to get video stills, but descriptions clarify the difference well.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (convert_video, extract_frames, get_balance, get_job_status, leave_feedback, probe_media). The verbs are descriptive and the nouns clearly indicate the resource or action, making them predictable and easy to navigate.

Tool Count5/5

With 6 tools, the set is well-scoped for a video processing service. Each tool serves a core function: two for processing (convert, extract), one for analysis (probe), one for status tracking, one for account management, and one for feedback. No tool is superfluous, and the count feels proportional to the domain.

Completeness4/5

The toolset covers essential video operations: conversion, frame extraction, media probing, with robust status tracking and account management. Obvious gaps include the lack of a cancel_job tool for stopping queued jobs and no explicit download management tool beyond the 24-hour window, but the core lifecycle is well-covered.

Resources

Need Help?