Skip to content

Adapt Ffmpeg

Adapt FFmpeg -- mvp.adapt_ffmpeg

Cluster: Creative & Media | Type: component | MCP Tools: 36

Overview

FFmpeg media-processing block that wraps the ffmpeg CLI to handle video and audio conversion, trimming, concatenation, resizing, framerate changes, filtering, thumbnail extraction, GIF creation, scene detection, subtitle burning, watermarking, audio normalisation, and slideshow generation. Accepts input as a file path or base64-encoded bytes and returns output the same way. Probes media files for metadata without any additional library beyond the FFmpeg binary.

When to use:

  • Converting video or audio files between formats (MP4, WebM, MP3, etc.) in a pipeline
  • Trimming or concatenating media clips produced by other blocks
  • Generating thumbnails or GIFs from video for preview or documentation purposes
  • Extracting audio tracks from video before passing them to a voice or audio block

Example:

from mvp.adapt_ffmpeg import AdaptFFmpegBlock, FFmpegInput

block = AdaptFFmpegBlock(name="ffmpeg")
result = block.infer(FFmpegInput(
    op="probe",
    input_path="/tmp/clip.mp4",
))
# result.value.duration_seconds → video length; result.value.metadata → full probe dict

Works well with: adapt_audio, adapt_voice, adapt_generative_art

Public API

FFmpegOpRecommendation

Validated ffmpeg op+preset recommendation decision record.

Field Type Default
op str required
format str DEFAULT_FORMAT
video_codec str ''
audio_codec str ''
encode_preset str DEFAULT_ENCODE_PRESET
rationale str ''
alternatives list[str] field(default_factory=list)
confidence float 0.0
degraded bool False
raw_response str ''

Methods:

to_metadata() -> dict[str, Any]

FFmpegPlanner

Runtime-first facade with the deterministic floor as honest fallback.

Constructor:

Parameter Type Default
runtime FFmpegRuntime \| None None

Methods:

recommend(brief: str, has_input: bool = False) -> FFmpegOpRecommendation

AdaptFFmpegBlock(AIBlock[FFmpegInput, FFmpegOutput, None])

FFmpeg media-processing block.

Field Type Default
name str 'adapt_ffmpeg'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)

Methods:

infer(data: FFmpegInput) -> Result[FFmpegOutput]

FFmpegInput(BaseModel)

Input to AdaptFFmpegBlock.

Field Type Default
op str 'probe'
input_path str ''
input_base64 str ''
output_path str ''
format str ''
brief str ''
start_seconds float 0.0
end_seconds float 0.0
width int 0
height int 0
framerate int 0
video_codec str ''
audio_codec str ''
bitrate str ''
volume float 1.0
speed float 1.0
filter_expr str ''
second_input_path str ''
overlay_x int 0
overlay_y int 0
subtitle_path str ''
watermark_path str ''
preset str 'medium'
timeout_seconds int 120
subtitle_codec str ''
muxer str ''
stream_maps list[str] Field(default_factory=list)
profile_parameters dict Field(default_factory=dict)
refresh_capabilities bool False

FFmpegOutput(BaseModel)

Output from AdaptFFmpegBlock.

Field Type Default
op str required
output_path str ''
output_base64 str ''
duration_seconds float 0.0
width int 0
height int 0
format str ''
size_bytes int 0
metadata dict Field(default_factory=dict)
stdout str ''
stderr str ''
recommendation dict Field(default_factory=dict)
agentic_evidence dict Field(default_factory=dict)
degraded bool False
degradation_reason str ''
warnings list[str] Field(default_factory=list)
unsupported_features list[str] Field(default_factory=list)
effective_plan dict Field(default_factory=dict)
resolved_argv list[str] Field(default_factory=list)
capability_validation dict Field(default_factory=dict)
dependency_status dict Field(default_factory=dict)
completion_state str 'qualified-draft'
warning_card dict Field(default_factory=dict)
evidence dict Field(default_factory=dict)
request_id str ''
run_id str ''

AdaptFFmpegMCPBlock(AIBlock[MCPFFmpegInput, MCPFFmpegOutput, dict])

28-op FFmpeg MCP block (25 media/info/history + 3 advisory) backed by SQLite.

Field Type Default
name str 'adapt_ffmpeg_mcp'
db_path str ':memory:'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)

Methods:

infer(data: MCPFFmpegInput) -> Result[MCPFFmpegOutput]

MCPFFmpegInput(BaseModel)

Field Type Default
op Literal['convert', 'trim', 'concat', 'extract_audio', 'add_audio', 'resize', 'framerate', 'filter', 'probe', 'thumbnail', 'gif', 'overlay', 'speed', 'volume', 'batch_convert', 'merge_av', 'detect_scenes', 'split_scenes', 'normalize_audio', 'slideshow', 'subtitles', 'watermark', 'encode_preset', 'job_history', 'job_get', 'get_info', 'recommend', 'auto', 'list_patterns', 'capabilities', 'probe_capabilities', 'inspect_backend', 'encode_custom', 'filtergraph', 'stream_map', 'run_profile'] required
input_path str ''
input_base64 str ''
output_path str ''
format str ''
brief str ''
start_seconds float 0.0
end_seconds float 0.0
width int 0
height int 0
framerate int 0
video_codec str ''
audio_codec str ''
bitrate str ''
volume float 1.0
speed float 1.0
filter_expr str ''
second_input_path str ''
overlay_x int 0
overlay_y int 0
subtitle_path str ''
watermark_path str ''
preset str 'medium'
subtitle_codec str ''
muxer str ''
stream_maps list[str] Field(default_factory=list)
profile_parameters dict Field(default_factory=dict)
refresh_capabilities bool False
timeout_seconds int 120
job_id str ''
limit int 50

MCPFFmpegOutput(BaseModel)

Field Type Default
op str required
ok bool True
message str ''
job_id str ''
output_path str ''
output_base64 str ''
duration_seconds float 0.0
width int 0
height int 0
format str ''
size_bytes int 0
metadata dict Field(default_factory=dict)
stdout str ''
stderr str ''
jobs list[dict] Field(default_factory=list)
count int 0
recommendation dict Field(default_factory=dict)
agentic_evidence dict Field(default_factory=dict)
degraded bool False
degradation_reason str ''
warnings list[str] Field(default_factory=list)
unsupported_features list[str] Field(default_factory=list)
effective_plan dict Field(default_factory=dict)
resolved_argv list[str] Field(default_factory=list)
capability_validation dict Field(default_factory=dict)
dependency_status dict Field(default_factory=dict)
completion_state str 'qualified-draft'
warning_card dict Field(default_factory=dict)
evidence dict Field(default_factory=dict)
request_id str ''
run_id str ''

FFmpegStore

Constructor:

Parameter Type Default
db_path str ':memory:'

Methods:

db_path() -> str

insert_job(op: str, input_path: str = '', output_path: str = '', fmt: str = '', duration_seconds: float = 0.0, width: int = 0, height: int = 0, size_bytes: int = 0, ok: bool = True, error: str = '', metadata: dict | None = None) -> str

list_jobs(limit: int = 50, op: str = '') -> list[dict]

get_job(job_id: str) -> dict | None

count_all() -> dict[str, int]

Functions

agentic_planner_enabled(default_enabled: bool = True) -> bool

Decide whether the agentic ffmpeg-op-recommendation planner should be used.

recommend_ffmpeg_op_floor(brief: str, has_input: bool = False) -> FFmpegOpRecommendation

Deterministic keyword/heuristic ffmpeg-op selector (the demoted floor).

MCP Tools

Operation Source
convert ffmpeg_mcp
trim ffmpeg_mcp
concat ffmpeg_mcp
extract_audio ffmpeg_mcp
add_audio ffmpeg_mcp
resize ffmpeg_mcp
framerate ffmpeg_mcp
filter ffmpeg_mcp
probe ffmpeg_mcp
thumbnail ffmpeg_mcp
gif ffmpeg_mcp
overlay ffmpeg_mcp
speed ffmpeg_mcp
volume ffmpeg_mcp
batch_convert ffmpeg_mcp
merge_av ffmpeg_mcp
detect_scenes ffmpeg_mcp
split_scenes ffmpeg_mcp
normalize_audio ffmpeg_mcp
slideshow ffmpeg_mcp
subtitles ffmpeg_mcp
watermark ffmpeg_mcp
encode_preset ffmpeg_mcp
job_history ffmpeg_mcp
job_get ffmpeg_mcp
get_info ffmpeg_mcp
recommend ffmpeg_mcp
auto ffmpeg_mcp
list_patterns ffmpeg_mcp
capabilities ffmpeg_mcp
probe_capabilities ffmpeg_mcp
inspect_backend ffmpeg_mcp
encode_custom ffmpeg_mcp
filtergraph ffmpeg_mcp
stream_map ffmpeg_mcp
run_profile ffmpeg_mcp