ffpipe — video conversion, probe & frames

probe_media

Read-only

Queue an asynchronous media inspection: fetches sourceUrl (or, with upload: true, waits for you to PUT the bytes to the returned uploadUrl) and returns its technical metadata as a downloadable file. In the default json format the result is the full raw analysis plus one added top-level "ffpipe_summary" object: container, duration_s, size_bytes, has_video, has_audio, video_codec, audio_codec, coded_width/height, display_width/height, rotation, fps, is_hdr, audio_channels, audio_sample_rate. USE display_width/display_height as the size the picture actually is - phones store portrait video as a landscape frame plus a rotation flag. A file that cannot be decoded is still a SUCCESS whose result carries the diagnosis. Returns { jobId, status, statusUrl, ... } - poll with get_job_status until finished/error, then download resultUrl within 24 hours. Paid: $0.01 USDC via x402 (base mainnet), or a probe-kind retryVoucher.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`summary`	No	Keep the normalized ffpipe_summary block (json only). Default true; send false for byte-exact raw output.
`sections`	No	Which sections to report. Default: format, streams, chapters.
`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.
`showFrames`	No	Report per-FRAME detail. Large: a bounded window is applied for you unless you send readIntervals. Pair with showEntries to keep only the fields you need.
`countFrames`	No	Count frames exactly. Requires decoding the whole file - slow on long sources.
`showEntries`	No	Keep only the named fields, e.g. "frame=pict_type,pts_time,key_frame" or "format=duration". Section and field names only.
`showPackets`	No	Report per-PACKET detail. Same bounded-window treatment as showFrames.
`countPackets`	No	Count packets exactly. Same cost caveat as countFrames.
`outputFormat`	No	Format of the delivered analysis, default json. Only json carries the ffpipe_summary block; the rest are raw. flat is delivered as .txt.
`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.
`readIntervals`	No	Limit the analysis to a window, e.g. "%+60" (first 60 seconds), "30%+10" (10 seconds from 0:30), "%+#500" (first 500 packets).
`selectStreams`	No	Restrict the analysis to matching streams, e.g. "v:0" (first video stream) or "a" (all audio).

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context: async nature (polling required), result lifetime (24 hours), error handling (undecodable files return SUCCESS with diagnosis), payment and voucher mechanics, and upload flow details. This goes well beyond annotations.

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

Conciseness3/5

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

The description is comprehensive but verbose, mixing core purpose, parameter details, pricing, and result format in a dense block. While every sentence adds value, it could be better structured (e.g., separate sections for usage, parameters, output, pricing). It is adequate but not optimally concise.

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 complexity (13 parameters, no output schema), the description covers return format (including the summary object), async polling, error handling, pricing, and parameter nuances (e.g., upload flow, readIntervals syntax). No gaps are apparent; the agent has enough context to invoke the tool correctly.

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 description coverage is 100%, so baseline is 3. The description adds value by explaining output structure (ffpipe_summary block), upload process, readIntervals syntax, and the meaning of display_width/height. These clarifications are not present in the schema and aid correct parameter usage.

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's purpose: 'Queue an asynchronous media inspection: fetches sourceUrl ... and returns its technical metadata as a downloadable file.' It uses a specific verb ('inspect'), specifies the resource (media via URL or upload), and distinguishes itself from sibling tools like convert_video or extract_frames.

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

Usage Guidelines4/5

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

The description implicitly guides when to use this tool (for media inspection to get technical metadata) and provides detailed usage context such as payment ($0.01 via x402 or retryVoucher), async polling via get_job_status, and result expiration. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent.

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?