The Python API is synchronous and currently marked beta. Prefer explicit keyword arguments and inspect nonzero results.
One privacy-redacted JSON Lines event emitted by a batch run.
Serialize the versioned event as privacy-redacted JSON data.
Stable per-item result, including resumed and cancelled jobs.
Serialize the outcome and include execution evidence when available.
One stable job identity paired with an immutable typed plan.
Strict versioned profile-job manifest compiled through the typed planner.
Serialize manifest version, policy, signatures, and redacted plans.
Explicit concurrency, retry, input-size, and timeout limits.
A configured per-job timeout overrides each plan's process timeout.
Return validated concurrency, retry, input-size, and timeout limits.
Versioned ordered outcome for one bounded batch execution.
Serialize policy, ordered item outcomes, and aggregate counts.
Execute validated jobs concurrently with receipts, events, retry, and resume.
run(self, jobs: 'Iterable[BatchJob]', *, policy: 'BatchPolicy | None' = None, cancellation: 'threading.Event | None' = None, event_callback: 'Callable[[BatchEvent], None] | None' = None, state_path: 'str | Path | None' = None, resume: 'bool' = False, overwrite_state: 'bool' = False, receipt_dir: 'str | Path | None' = None, overwrite_receipts: 'bool' = False, hash_content: 'bool' = False) -> 'BatchRun'
Run jobs once and refuse receipt replacement unless explicitly allowed.
Existing state files require resume or explicit overwrite. State files are claimed before the first job starts and cannot alias media outputs or generated receipts. A configured batch timeout overrides the timeout in each job plan.
The installed FFmpeg build cannot satisfy the requested workflow.
Versioned FFmpeg inventory; inspection raises when a five-second listing times out.
Return unsupported requirements in the same order as requested.
Check a normalized kind:name requirement.
Serialize inventory, capability counts, baseline coverage, and subtitle support.
Python 3.10-compatible string enumeration.
CompressOptions(target_size_bytes: 'int | None' = None, crf: 'int' = 23, two_pass: 'bool' = True, video_codec: 'str' = 'libx264', audio_codec: 'str' = 'aac', video_bitrate: 'str | None' = None, audio_bitrate: 'str' = '128k', preset: 'str' = 'medium', pixel_format: 'str' = 'yuv420p', threads: 'int | None' = None, container_overhead_percent: 'float' = 5.0, minimum_video_bitrate: 'int' = 102400)
ConvertOptions(video_codec: 'str | None' = None, audio_codec: 'str | None' = None, video_bitrate: 'str | None' = None, audio_bitrate: 'str | None' = None, pixel_format: 'str' = 'yuv420p', threads: 'int | None' = None, audio_only: 'bool' = False, hardware_acceleration: 'str | None' = None, preserve_all_streams: 'bool' = False)
A required executable or host resource is unavailable.
Deterministic, non-shell execution plan for one media workflow.
Plan fields are frozen; nested mapping/list metadata is read-only. to_dict()
returns a detached, mutable serialization copy.
Serialize workflow, argument vectors, policy, streams, warnings, and metadata.
Explicit process, overwrite, capture, and cleanup behavior.
A configured process timeout must be finite and greater than zero.
One named argument-vector step inside a multi-pass plan.
Execute typed workflows or an explicit non-shell argument vector.
adjust_speed(self, input_file: 'str', output_file: 'str', speed_factor: 'float' = 1.0, audio_pitch: 'bool' = True, *, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute typed video speed adjustment.
compress(self, input_file: 'str', output_file: 'str', *, target_size_kb: 'int | None' = None, crf: 'int' = 23, two_pass: 'bool' = True, video_codec: 'str' = 'libx264', audio_codec: 'str' = 'aac', video_bitrate: 'str | None' = None, audio_bitrate: 'str' = '128k', preset: 'str' = 'medium', pixel_format: 'str' = 'yuv420p', threads: 'int | None' = None, container_overhead_percent: 'float' = 5.0, minimum_video_bitrate: 'int' = 102400, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute typed single- or two-pass compression.
convert(self, input_file: 'str', output_file: 'str', *, video_codec: 'str | None' = None, audio_codec: 'str | None' = None, video_bitrate: 'str | None' = None, audio_bitrate: 'str | None' = None, pixel_format: 'str' = 'yuv420p', threads: 'int | None' = None, audio_only: 'bool' = False, hardware_acceleration: 'str | None' = None, preserve_all_streams: 'bool' = False, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute a typed conversion.
execute_plan(self, plan: 'ExecutionPlan', *, cancellation: 'threading.Event | None' = None, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Execute a typed plan and return a stable structured result.
extract_audio(self, input_file: 'str', output_file: 'str', *, audio_codec: 'str | None' = None, audio_bitrate: 'str' = '192k', sample_rate: 'int | None' = None, channels: 'int | None' = None, threads: 'int | None' = None, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute typed audio extraction.
extract_thumbnail(self, input_file: 'str', output_file: 'str', timestamp: 'str' = '00:00:01', width: 'int' = 320, height: 'int | None' = None, quality: 'int' = 2, *, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute typed thumbnail extraction.
generate_waveform(self, input_file: 'str', output_file: 'str', width: 'int' = 800, height: 'int' = 200, colors: 'str' = 'white', *, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute typed waveform rendering.
Return the FFmpeg version banner line.
resize(self, input_file: 'str', output_file: 'str', width: 'int', height: 'int', *, video_codec: 'str | None' = None, audio_codec: 'str | None' = None, pixel_format: 'str' = 'yuv420p', threads: 'int | None' = None, force: 'bool' = False, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'JobResult'
Plan, preflight, and execute a typed resize.
run(self, args: 'list[str]', progress_callback: 'Callable[[dict[str, object]], None] | None' = None, *, overwrite: 'OverwritePolicy' = <OverwritePolicy.REFUSE: 'refuse'>) -> 'subprocess.CompletedProcess[str]'
Run a raw argument vector without a shell and with explicit overwrite policy.
run_with_progress(self, args: 'list[str]', show_percentage: 'bool' = True, *, overwrite: 'OverwritePolicy' = <OverwritePolicy.REFUSE: 'refuse'>) -> 'subprocess.CompletedProcess[str]'
Run the low-level escape hatch and print its legacy progress stream.
Extract media metadata through FFprobe.
Media probes time out after 60 seconds by default; configure
probe_timeout_seconds when constructing the runner.
Get the bitrate of a media file.
Args: input_file: Path to the media file
Returns: Bitrate in bits per second
Get the duration of a media file in seconds.
Args: input_file: Path to the media file
Returns: Duration in seconds
Get the resolution of a video file.
Args: input_file: Path to the video file
Returns: Tuple of (width, height) or None if not a video
Get the FFprobe version.
Returns: Version string
Extract simplified metadata from a media file.
Args: input_file: Path to the media file
Returns: Simplified metadata dictionary derived from FFprobe JSON
Return typed metadata while retaining decision-relevant stream details.
Return the complete FFprobe JSON document without dropping fields.
A caller explicitly cancelled a running job.
FFmpeg or FFprobe started but the media job failed.
Stable execution result with diagnostics and output evidence.
Serialize the result with wire-format status and captured output evidence.
Python 3.10-compatible string enumeration.
A job exceeded its explicit timeout.
Typed container, stream, and chapter information from FFprobe.
Serialize stream, container, and chapter facts as nested mappings.
Python 3.10-compatible string enumeration.
Optional output-validity cache; content hashing is explicit.
Return JSON-compatible cache settings.
Resolve variables/dependencies and compile every step through the typed planner.
compile(self, spec: 'PipelineSpec', *, variables: 'dict[str, str] | None' = None, force: 'bool' = False, timeout_seconds: 'float | None' = None, cache_enabled: 'bool | None' = None) -> 'PipelinePlan'
Resolve pipeline variables and compile steps without running FFmpeg.
Dependency references become producer output paths. Secret values are retained only for redaction in the resulting plan and receipts.
PipelineEvent(sequence: 'int', event: 'str', step_id: 'str', detail: 'str | None' = None, schema_version: 'str' = '1.0')
Serialize this event and mask supplied secret values.
Compiled DAG whose steps contain argument arrays, never shell strings.
Render the dependency DAG as text, Mermaid, or Graphviz DOT.
Serialize compiled plans while masking declared secret values.
Preflight an entire DAG while explicitly deferring dependency outputs.
prepare(self, pipeline: 'PipelinePlan', *, allow_existing_outputs: 'bool' = False) -> 'PreparedPipeline'
Preflight each step and defer missing inputs produced by dependencies.
Existing outputs remain errors unless explicitly allowed for a later cache or resume check; this method never executes a step.
PipelineRun(pipeline: 'PipelinePlan', items: 'tuple[PipelineStepOutcome, ...]', schema_version: 'str' = '1.0')
Serialize ordered outcomes with a stable summary.
Execute a prepared DAG with dependency blocking, cancellation, resume, and caching.
run(self, pipeline: 'PipelinePlan', *, cancellation: 'threading.Event | None' = None, state_path: 'str | Path | None' = None, resume: 'bool' = False, overwrite_state: 'bool' = False, receipt_dir: 'str | Path | None' = None, overwrite_receipts: 'bool' = False, hash_content: 'bool' = False, event_callback: 'Any' = None) -> 'PipelineRun'
Execute steps in dependency order and return one outcome per step.
Failed dependencies block downstream steps. Optional state supports
resume and caching; receipts and event callbacks are opt-in. Existing
receipts are preserved unless overwrite_receipts is enabled. State
files are preserved unless resuming or overwrite_state is enabled,
fresh state files are claimed before the first runnable step, and state
files cannot alias media outputs or generated receipts.
Versioned pipeline source with strict variables, cache, and typed steps.
Serialize the versioned manifest without its local base directory.
PipelineStepOutcome(step_id: 'str', status: 'str', cache_key: 'str', execution: 'WorkflowExecution | None' = None, receipt: 'str | None' = None, detail: 'str | None' = None)
Serialize this step outcome and redact nested execution evidence.
One topologically ordered typed plan and its dependencies.
One strict declarative step before variable and dependency resolution.
Serialize the declarative step with JSON-compatible options.
A named, versioned set of choices for one supported workflow.
Serialize the versioned profile with JSON-compatible options and capabilities.
Resolve built-in profiles and strictly validate local profile files.
Return a built-in profile or raise ValidationError for an unknown name.
Return built-in profiles sorted by stable profile name.
Load one strict versioned profile from JSON or TOML.
plan(self, name: 'str', planner: 'WorkflowPlanner', input_file: 'str', output_file: 'str', *, subtitle_file: 'str | None' = None, subtitle_language: 'str | None' = None, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Compile a maintained built-in profile through the shared typed planner.
Whole-pipeline structural, capability, and external-input preflight facts.
Return per-step preflight facts and the aggregate pipeline status.
An immutable plan paired with its non-mutating preflight facts.
One deterministic preflight fact.
Check a plan without creating directories, outputs, or temporary files.
Check tools, capabilities, inputs, and output paths without executing.
Input streams may be probed when the plan requires them. The report records failures and remediation hints instead of raising for them.
Versioned preflight result shared by human and JSON presenters.
Render checks and available remedies as a concise human-readable report.
Return versioned JSON-ready preflight facts and overall status.
A helper class for creating progress callbacks with context.
Versioned progress fact suitable for callbacks or JSON Lines output.
Serialize this versioned progress event for callbacks or JSON Lines.
Tracks FFmpeg progress by parsing progress output.
Run a command and track progress.
Args: cmd: Command to run
Returns: CompletedProcess instance
A simple progress callback that prints progress to console.
Args: progress: Progress dictionary
Base error carrying a stable machine-readable category.
Build redacted receipts from the same prepared workflow and stable results.
Create a private-by-default receipt; content hashes are explicit opt-in.
ResizeOptions(width: 'int', height: 'int', video_codec: 'str | None' = None, audio_codec: 'str | None' = None, pixel_format: 'str' = 'yuv420p', threads: 'int | None' = None)
Validated schema 1.0 receipt suitable for storage or bug reports.
Return the validated receipt mapping.
Render the receipt as indented UTF-8-compatible JSON with a trailing newline.
Create parent directories and refuse replacement unless explicitly requested.
Typed stream facts while preserving metadata needed for safe decisions.
Python 3.10-compatible string enumeration.
User input or policy is invalid before execution starts.
Build deterministic plans used by CLI, Python, examples, and pipelines.
compress(self, input_file: 'str', output_file: 'str', options: 'CompressOptions | None' = None, *, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan CRF or target-size compression from CompressOptions.
A two-pass target-size plan probes the input duration and rejects video stream copy.
concat(self, input_files: 'list[str]', output_file: 'str', *, mode: 'str' = 'copy', video_codec: 'str' = 'libx264', audio_codec: 'str' = 'aac', force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan ordered clip concatenation using stream copy or re-encoding.
Stream-copy mode expects matching stream metadata. Re-encode mode accepts codec differences, but the first video and audio streams must share dimensions and stream layout.
convert(self, input_file: 'str', output_file: 'str', options: 'ConvertOptions | None' = None, *, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan conversion with explicit codec options and stream selection.
By default, map the first video and audio streams. Use
preserve_all_streams to copy every stream or audio_only to omit video.
extract_audio(self, input_file: 'str', output_file: 'str', *, audio_codec: 'str | None' = None, audio_bitrate: 'str' = '192k', sample_rate: 'int | None' = None, channels: 'int | None' = None, threads: 'int | None' = None, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan audio extraction with optional codec, bitrate, sample-rate, and channel settings.
Video streams are omitted from the output.
image(self, input_file: 'str', output_file: 'str', *, quality: 'int' = 85, resize: 'tuple[int, int] | None' = None, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan one still-image conversion without routing through a directory batch.
images(self, action: 'str', input_dir: 'str', output_dir: 'str', *, output_format: 'str' = 'jpg', quality: 'int' = 85, resize: 'tuple[int, int] | None' = None, max_width: 'int' = 1920, max_height: 'int' = 1080, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan a directory batch that converts, optimizes, or writes supported images as WebP.
mix_audio(self, action: 'str', input_files: 'list[str]', output_file: 'str', *, volumes: 'list[float] | None' = None, crossfade_duration: 'float' = 2.0, background_volume: 'float' = 0.3, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan audio mixing, concatenation, crossfade mashup, or background mixing.
volumes applies to a mix; crossfade_duration applies to a mashup, and
background_volume applies to a two-input background mix.
normalize_audio(self, input_file: 'str', output_file: 'str', *, method: 'str' = 'loudnorm', target_i: 'float' = -16.0, target_tp: 'float' = -1.5, target_lra: 'float' = 11.0, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan loudnorm normalization to the requested targets or the master chain.
The master chain applies fixed loudness targets, compression, and a limiter.
resize(self, input_file: 'str', output_file: 'str', options: 'ResizeOptions', *, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan scaling the input video to the dimensions in ResizeOptions.
speed(self, kind: 'str', input_file: 'str', output_file: 'str', *, factor: 'float', preserve_pitch: 'bool' = True, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan a video or audio speed change; pitch preservation applies to audio filtering.
subtitles(self, action: 'str', video_file: 'str', output_file: 'str', *, subtitle_file: 'str | None' = None, language: 'str' = 'eng', stream_index: 'int' = 0, font_size: 'int' = 24, font_color: 'str' = '&HFFFFFF', force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan adding, extracting, or burning subtitles; add and burn require subtitle_file.
thumbnail(self, input_file: 'str', output_file: 'str', *, timestamp: 'str' = '00:00:01', width: 'int' = 320, height: 'int | None' = None, quality: 'int' = 2, force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan one video frame as a still image at timestamp and the requested dimensions.
waveform(self, input_file: 'str', output_file: 'str', *, width: 'int' = 800, height: 'int' = 200, colors: 'str' = 'white', force: 'bool' = False, timeout_seconds: 'float | None' = None) -> 'ExecutionPlan'
Plan a waveform image from the input audio stream at the requested size and color.
Versioned machine-readable outcome for a single or multi-item plan.
Serialize the plan, preflight, ordered item results, and summary.
Compile, preflight, and execute every supported workflow through one public layer.
Preflight an already compiled plan without mutating media or output paths.
run(self, plan: 'ExecutionPlan | PreparedWorkflow', *, cancellation: 'threading.Event | None' = None, progress_callback: 'Callable[[ProgressEvent], None] | None' = None) -> 'WorkflowBatch'
Execute a single workflow or an item-aware image batch with stable results.
Preflight and execution facts for one input/output item.
Serialize item preflight, result, and measurable path/size proof.