dag ¶

DAG (Directed Acyclic Graph) layer for FFmpeg filter graphs.

This module provides the core classes for building and manipulating FFmpeg filter graphs as Python objects.

Modules:

Name	Description
`base_streams`	Base stream classes to avoid circular import dependencies.
`factory`	Factory functions for creating FFmpeg filter nodes.
`global_runnable`
`io`	Input/output utilities for FFmpeg DAG operations.
`nodes`	DAG node definitions for FFmpeg filter graphs.
`schema`	DAG schema definitions for FFmpeg filter graphs.
`utils`	Utility functions for working with directed acyclic graphs (DAGs).

Classes:

Name	Description
`FilterNode`	A node that represents an FFmpeg filter operation in the filter graph.
`GlobalNode`	A node that represents global FFmpeg options.
`GlobalStream`	A stream representing a set of global FFmpeg options.
`InputNode`	A node that represents an input file in the FFmpeg filter graph.
`LoopbackDecoderNode`	A node that represents an FFmpeg loopback decoder (FFmpeg >= 7.0).
`OutputNode`	A node that represents an output file in the FFmpeg filter graph.
`OutputStream`	A stream representing an output file with additional capabilities.
`Stream`	A 'Stream' represents a sequence of data flow in the Directed Acyclic Graph (DAG).

Functions:

Name	Description
`filter_node_factory`	Create a FilterNode from an FFmpeg filter definition.

FilterNode `dataclass` ¶

FilterNode(
    *,
    kwargs: FrozenDict[
        str, str | int | float | bool | LazyValue
    ] = FrozenDict({}),
    inputs: tuple[FilterableStream, ...] = (),
    name: str,
    input_typings: tuple[StreamType, ...] = (),
    output_typings: tuple[StreamType, ...] = ()
)

Bases: Node

A node that represents an FFmpeg filter operation in the filter graph.

FilterNode represents a single filter operation in the FFmpeg filter graph, such as scaling, cropping, or audio mixing. It connects input streams to output streams and defines the parameters for the filter operation.

Methods:

Name	Description
`audio`	Get an audio output stream from this filter node.
`replace`	Replace the old node in the graph with the new node.
`repr`	Get a string representation of this filter node.
`video`	Get a video output stream from this filter node.
`view`	Visualize the Node.

Attributes:

Name	Type	Description
`hex`	`str`	Get the hexadecimal hash of the object.
`input_typings`	`tuple[StreamType, ...]`	The expected types (audio/video) for each input stream
`inputs`	`tuple[FilterableStream, ...]`	The input streams that this filter processes
`kwargs`	`FrozenDict[str, str \| int \| float \| bool \| LazyValue]`	Represents the keyword arguments of the node.
`max_depth`	`int`	Get the maximum depth of the node (longest path from any input).
`name`	`str`	The name of the filter as used in FFmpeg (e.g., 'scale', 'overlay', 'amix')
`output_typings`	`tuple[StreamType, ...]`	The types (audio/video) of each output stream this filter produces
`upstream_nodes`	`set[Node]`	Get all upstream nodes of the node.

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

input_typings `class-attribute` `instance-attribute` ¶

input_typings: tuple[StreamType, ...] = ()

The expected types (audio/video) for each input stream

inputs `class-attribute` `instance-attribute` ¶

inputs: tuple[FilterableStream, ...] = ()

The input streams that this filter processes

kwargs `class-attribute` `instance-attribute` ¶

kwargs: FrozenDict[
    str, str | int | float | bool | LazyValue
] = FrozenDict({})

Represents the keyword arguments of the node.

max_depth `cached` `property` ¶

max_depth: int

Get the maximum depth of the node (longest path from any input).

The result is cached. The iterative computation also pre-populates the cache for all upstream nodes so that subsequent calls are O(1).

Returns:

Type	Description
`int`	The maximum depth of the node.

name `instance-attribute` ¶

name: str

The name of the filter as used in FFmpeg (e.g., 'scale', 'overlay', 'amix')

output_typings `class-attribute` `instance-attribute` ¶

output_typings: tuple[StreamType, ...] = ()

The types (audio/video) of each output stream this filter produces

upstream_nodes `property` ¶

upstream_nodes: set[Node]

Get all upstream nodes of the node.

Returns:

Type	Description
`set[Node]`	The upstream nodes of the node.

audio ¶

audio(index: int) -> AudioStream

Get an audio output stream from this filter node.

This method retrieves a specific audio output stream from the filter, identified by its index among all audio outputs. For example, if a filter produces multiple audio outputs (like 'asplit'), this method allows accessing each one individually.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the audio stream to retrieve (0-based) among all audio outputs of this filter	required

Returns:

Type	Description
`AudioStream`	An AudioStream object representing the specified output

Raises:

Type	Description
`FFMpegValueError`	If the specified index is out of range

replace ¶

replace(old_node: Node, new_node: Node) -> Node

Replace the old node in the graph with the new node.

Parameters:

Name	Type	Description	Default
`old_node`	`Node`	The old node to replace.	required
`new_node`	`Node`	The new node to replace with.	required

Returns:

Type	Description
`Node`	The new graph with the replaced node.

repr ¶

repr() -> str

Get a string representation of this filter node.

Returns:

Type	Description
`str`	The name of the filter

video ¶

video(index: int) -> VideoStream

Get a video output stream from this filter node.

This method retrieves a specific video output stream from the filter, identified by its index among all video outputs. For example, if a filter produces multiple video outputs (like 'split'), this method allows accessing each one individually.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the video stream to retrieve (0-based) among all video outputs of this filter	required

Returns:

Type	Description
`VideoStream`	A VideoStream object representing the specified output

Raises:

Type	Description
`FFMpegValueError`	If the specified index is out of range

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the Node.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

GlobalNode `dataclass` ¶

GlobalNode(
    *,
    kwargs: FrozenDict[
        str, str | int | float | bool | LazyValue
    ] = FrozenDict({}),
    inputs: tuple[OutputStream, ...]
)

Bases: Node

A node that represents global FFmpeg options.

GlobalNode represents options that apply to the entire FFmpeg command rather than to specific inputs or outputs. These include options like overwrite (-y), log level, and other general FFmpeg settings.

Methods:

Name	Description
`replace`	Replace the old node in the graph with the new node.
`repr`	Get the representation of the node.
`stream`	Get a global stream representing this global node.
`view`	Visualize the Node.

Attributes:

Name	Type	Description
`hex`	`str`	Get the hexadecimal hash of the object.
`inputs`	`tuple[OutputStream, ...]`	The output streams this node applies to
`kwargs`	`FrozenDict[str, str \| int \| float \| bool \| LazyValue]`	Represents the keyword arguments of the node.
`max_depth`	`int`	Get the maximum depth of the node (longest path from any input).
`upstream_nodes`	`set[Node]`	Get all upstream nodes of the node.

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

inputs `instance-attribute` ¶

inputs: tuple[OutputStream, ...]

The output streams this node applies to

kwargs `class-attribute` `instance-attribute` ¶

kwargs: FrozenDict[
    str, str | int | float | bool | LazyValue
] = FrozenDict({})

Represents the keyword arguments of the node.

max_depth `cached` `property` ¶

max_depth: int

Get the maximum depth of the node (longest path from any input).

The result is cached. The iterative computation also pre-populates the cache for all upstream nodes so that subsequent calls are O(1).

Returns:

Type	Description
`int`	The maximum depth of the node.

upstream_nodes `property` ¶

upstream_nodes: set[Node]

Get all upstream nodes of the node.

Returns:

Type	Description
`set[Node]`	The upstream nodes of the node.

replace ¶

replace(old_node: Node, new_node: Node) -> Node

Replace the old node in the graph with the new node.

Parameters:

Name	Type	Description	Default
`old_node`	`Node`	The old node to replace.	required
`new_node`	`Node`	The new node to replace with.	required

Returns:

Type	Description
`Node`	The new graph with the replaced node.

repr ¶

repr() -> str

Get the representation of the node.

Returns:

Type	Description
`str`	The representation of the node.

stream ¶

stream() -> GlobalStream

Get a global stream representing this global node.

This method creates a GlobalStream object that wraps this GlobalNode, allowing it to be used in operations that require a global stream, such as adding more global options or executing the command.

Returns:

Type	Description
`GlobalStream`	A GlobalStream representing this global node

Example

# Create a global node and get its stream
global_node = ffmpeg.global_args(y=True)
global_stream = global_node.stream()
# Execute the command
global_stream.run()

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the Node.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

GlobalStream `dataclass` ¶

GlobalStream(
    *,
    node: GlobalNode,
    index: int | None = None,
    optional: bool = False
)

Bases: Stream, GlobalRunable

A stream representing a set of global FFmpeg options.

GlobalStream wraps a GlobalNode and provides additional functionality, particularly the ability to add more global options or execute the FFmpeg command. This class is typically the final step in the FFmpeg command construction process.

Methods:

Name	Description
`compile`	Build command-line arguments for invoking FFmpeg.
`compile_line`	Build a command-line string for invoking FFmpeg.
`global_args`	Set global options.
`merge_outputs`	Merge multiple output streams into a single command.
`overwrite_output`	Set the FFmpeg command to overwrite output files without asking.
`run`	Run FFmpeg synchronously and wait for completion.
`run_async`	Run FFmpeg asynchronously as a subprocess.
`run_async_awaitable`	Run FFmpeg asynchronously using asyncio.
`view`	Visualize the stream.

Attributes:

Name	Type	Description
`hex`	`str`	Get the hexadecimal hash of the object.
`index`	`int \| None`	Represents the index of the stream in the node's output streams.
`node`	`GlobalNode`	The global node this stream represents
`optional`	`bool`	Represents whether the stream is optional.

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

index `class-attribute` `instance-attribute` ¶

index: int | None = None

Represents the index of the stream in the node's output streams.

Note

See Also: Stream specifiers stream_index

node `instance-attribute` ¶

node: GlobalNode

The global node this stream represents

optional `class-attribute` `instance-attribute` ¶

optional: bool = False

Represents whether the stream is optional.

Note

compile ¶

compile(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> list[str]

Build command-line arguments for invoking FFmpeg.

This method converts the filter graph into a list of command-line arguments that can be passed to subprocess functions or executed directly. It handles the FFmpeg executable name, overwrite options, and automatic fixing of the filter graph.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph, such as adding split filters for reused streams	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`list[str]`	A list of strings representing the complete FFmpeg command

Example

# Get the command-line arguments for a filter graph
args = ffmpeg.input("input.mp4").output("output.mp4").compile()
# Result: ['ffmpeg', '-i', 'input.mp4', 'output.mp4']

compile_line ¶

compile_line(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> str

Build a command-line string for invoking FFmpeg.

This method is similar to compile(), but returns a single string with proper escaping instead of a list of arguments. This is useful for logging or displaying the command to users.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`str`	A string representing the complete FFmpeg command with proper escaping

Example

# Get a command-line string for a filter graph
cmd_str = ffmpeg.input("input.mp4").output("output.mp4").compile_line()
# Result: 'ffmpeg -i input.mp4 output.mp4'

global_args ¶

global_args(
    *,
    loglevel: Func = None,
    v: Func = None,
    report: Func = None,
    max_alloc: Func = None,
    cpuflags: Func = None,
    cpucount: Func = None,
    hide_banner: Func = None,
    y: Func = None,
    n: Func = None,
    ignore_unknown: Func = None,
    copy_unknown: Func = None,
    recast_media: Func = None,
    benchmark: Func = None,
    benchmark_all: Func = None,
    progress: Func = None,
    stdin: Func = None,
    timelimit: Func = None,
    dump: Func = None,
    hex: Func = None,
    vsync: Func = None,
    frame_drop_threshold: Func = None,
    _async: Func = None,
    adrift_threshold: Func = None,
    copyts: Func = None,
    start_at_zero: Func = None,
    copytb: Func = None,
    dts_delta_threshold: Func = None,
    dts_error_threshold: Func = None,
    xerror: Func = None,
    abort_on: Func = None,
    filter_threads: Func = None,
    filter_complex: Func = None,
    filter_complex_threads: Func = None,
    lavfi: Func = None,
    filter_complex_script: Func = None,
    auto_conversion_filters: Func = None,
    stats: Func = None,
    stats_period: Func = None,
    debug_ts: Func = None,
    max_error_rate: Func = None,
    psnr: Func = None,
    vstats: Func = None,
    vstats_file: Func = None,
    vstats_version: Func = None,
    qphist: Func = None,
    vol: Func = None,
    vaapi_device: Func = None,
    init_hw_device: Func = None,
    filter_hw_device: Func = None,
    extra_options: dict[str, Any] | None = None
) -> GlobalStream

Set global options.

Parameters:

Name	Type	Description	Default
`loglevel`	`Func`	set logging level	`None`
`v`	`Func`	set logging level	`None`
`report`	`Func`	generate a report	`None`
`max_alloc`	`Func`	set maximum size of a single allocated block	`None`
`cpuflags`	`Func`	force specific cpu flags	`None`
`cpucount`	`Func`	force specific cpu count	`None`
`hide_banner`	`Func`	do not show program banner	`None`
`y`	`Func`	overwrite output files	`None`
`n`	`Func`	never overwrite output files	`None`
`ignore_unknown`	`Func`	Ignore unknown stream types	`None`
`copy_unknown`	`Func`	Copy unknown stream types	`None`
`recast_media`	`Func`	allow recasting stream type in order to force a decoder of different media type	`None`
`benchmark`	`Func`	add timings for benchmarking	`None`
`benchmark_all`	`Func`	add timings for each task	`None`
`progress`	`Func`	write program-readable progress information	`None`
`stdin`	`Func`	enable or disable interaction on standard input	`None`
`timelimit`	`Func`	set max runtime in seconds in CPU user time	`None`
`dump`	`Func`	dump each input packet	`None`
`hex`	`Func`	when dumping packets, also dump the payload	`None`
`vsync`	`Func`	set video sync method globally; deprecated, use -fps_mode	`None`
`frame_drop_threshold`	`Func`	frame drop threshold	`None`
`_async`	`Func`	audio sync method	`None`
`adrift_threshold`	`Func`	audio drift threshold	`None`
`copyts`	`Func`	copy timestamps	`None`
`start_at_zero`	`Func`	shift input timestamps to start at 0 when using copyts	`None`
`copytb`	`Func`	copy input stream time base when stream copying	`None`
`dts_delta_threshold`	`Func`	timestamp discontinuity delta threshold	`None`
`dts_error_threshold`	`Func`	timestamp error delta threshold	`None`
`xerror`	`Func`	exit on error	`None`
`abort_on`	`Func`	abort on the specified condition flags	`None`
`filter_threads`	`Func`	number of non-complex filter threads	`None`
`filter_complex`	`Func`	create a complex filtergraph	`None`
`filter_complex_threads`	`Func`	number of threads for -filter_complex	`None`
`lavfi`	`Func`	create a complex filtergraph	`None`
`filter_complex_script`	`Func`	read complex filtergraph description from a file	`None`
`auto_conversion_filters`	`Func`	enable automatic conversion filters globally	`None`
`stats`	`Func`	print progress report during encoding	`None`
`stats_period`	`Func`	set the period at which ffmpeg updates stats and -progress output	`None`
`debug_ts`	`Func`	print timestamp debugging info	`None`
`max_error_rate`	`Func`	ratio of decoding errors (0.0: no errors, 1.0: 100% errors) above which ffmpeg returns an error instead of success.	`None`
`psnr`	`Func`	calculate PSNR of compressed frames	`None`
`vstats`	`Func`	dump video coding statistics to file	`None`
`vstats_file`	`Func`	dump video coding statistics to file	`None`
`vstats_version`	`Func`	Version of the vstats format to use.	`None`
`qphist`	`Func`	show QP histogram	`None`
`vol`	`Func`	change audio volume (256=normal)	`None`
`vaapi_device`	`Func`	set VAAPI hardware device (DRM path or X11 display name)	`None`
`init_hw_device`	`Func`	initialise hardware device	`None`
`filter_hw_device`	`Func`	set hardware device used when filtering	`None`
`extra_options`	`dict[str, Any] \| None`	Additional options	`None`

Returns:

Name	Type	Description
`GlobalStream`	`GlobalStream`	GlobalStream instance

merge_outputs ¶

merge_outputs(*streams: OutputStream) -> GlobalStream

Merge multiple output streams into a single command.

This method allows combining multiple output files into a single FFmpeg command, which is more efficient than running separate commands for each output. It creates a GlobalNode that includes all the specified output streams.

Parameters:

Name	Type	Description	Default
`*streams`	`OutputStream`	Additional output streams to include in the same command	`()`

Returns:

Type	Description
`GlobalStream`	A GlobalStream that represents the combined outputs

Example

# Create two output files with one command
video = ffmpeg.input("input.mp4").video
output1 = video.output("output1.mp4")
output2 = video.output("output2.webm")
merged = output1.merge_outputs(output2)
merged.run()  # Creates both output files with one FFmpeg command

overwrite_output ¶

overwrite_output() -> GlobalStream

Set the FFmpeg command to overwrite output files without asking.

This method adds the -y option to the FFmpeg command, which causes FFmpeg to overwrite output files without prompting for confirmation. It's equivalent to calling global_args(y=True).

Returns:

Type	Description
`GlobalStream`	A GlobalStream with the overwrite option enabled

Example

# Overwrite output file if it already exists
ffmpeg.input("input.mp4").output("output.mp4").overwrite_output().run()

run ¶

run(
    cmd: str | list[str] = "ffmpeg",
    capture_stdout: bool = False,
    capture_stderr: bool = False,
    input: bytes | None = None,
    quiet: bool = False,
    tee_stderr: bool = False,
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> tuple[bytes, bytes]

Run FFmpeg synchronously and wait for completion.

This method executes the FFmpeg command in a separate process and waits for it to complete before returning. It's the most common way to run FFmpeg commands when you just want to process media files.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`capture_stdout`	`bool`	Whether to capture and return the process's stdout	`False`
`capture_stderr`	`bool`	Whether to capture and return the process's stderr. Note: This parameter is ignored when tee_stderr=True, as tee_stderr always captures stderr.	`False`
`input`	`bytes \| None`	Optional bytes to write to the process's stdin	`None`
`quiet`	`bool`	Whether to suppress output to the console	`False`
`tee_stderr`	`bool`	Whether to capture stderr and also display it to the console. When enabled, stderr will be captured and simultaneously displayed to the console (unless quiet=True). When tee_stderr=True, the capture_stderr parameter is ignored and stderr is always captured.	`False`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`bytes`	A tuple of (stdout_bytes, stderr_bytes), which will be empty bytes
`bytes`	objects if the respective capture_* parameter is False

Raises:

Type	Description
`FFMpegExecuteError`	If the FFmpeg process returns a non-zero exit code

Example

# Process a video file
stdout, stderr = ffmpeg.input("input.mp4").output("output.mp4").run()

# Capture FFmpeg's output
stdout, stderr = (
    ffmpeg.input("input.mp4").output("output.mp4").run(capture_stderr=True)
)
print(stderr.decode())  # Print FFmpeg's progress information

# Capture and display stderr at the same time
stdout, stderr = (
    ffmpeg.input("input.mp4").output("output.mp4").run(tee_stderr=True)
)
# stderr is both displayed in console and captured for later use

run_async ¶

run_async(
    cmd: str | list[str] = "ffmpeg",
    pipe_stdin: bool = False,
    pipe_stdout: bool = False,
    pipe_stderr: bool = False,
    quiet: bool = False,
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> Popen[bytes]

Run FFmpeg asynchronously as a subprocess.

This method executes the FFmpeg command in a separate process without waiting for it to complete. This is useful for long-running operations or when you need to interact with the process while it's running.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`pipe_stdin`	`bool`	Whether to create a pipe for writing to the process's stdin	`False`
`pipe_stdout`	`bool`	Whether to create a pipe for reading from the process's stdout	`False`
`pipe_stderr`	`bool`	Whether to create a pipe for reading from the process's stderr	`False`
`quiet`	`bool`	Whether to capture stderr (implies pipe_stderr=True)	`False`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`Popen[bytes]`	A subprocess.Popen object representing the running FFmpeg process

Example

# Start FFmpeg process and interact with it
process = ffmpeg.input("input.mp4").output("output.mp4").run_async()
# Do something while FFmpeg is running
process.wait()  # Wait for completion

run_async_awaitable `async` ¶

run_async_awaitable(
    cmd: str | list[str] = "ffmpeg",
    pipe_stdin: bool = False,
    pipe_stdout: bool = False,
    pipe_stderr: bool = False,
    quiet: bool = False,
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> Process

Run FFmpeg asynchronously using asyncio.

This method executes the FFmpeg command as an asyncio subprocess, returning an asyncio.subprocess.Process object that can be awaited. This is useful for long-running operations in async code or when you need to interact with the process while it's running in an async context.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`pipe_stdin`	`bool`	Whether to create a pipe for writing to the process's stdin	`False`
`pipe_stdout`	`bool`	Whether to create a pipe for reading from the process's stdout	`False`
`pipe_stderr`	`bool`	Whether to create a pipe for reading from the process's stderr	`False`
`quiet`	`bool`	Whether to capture stderr (implies pipe_stderr=True)	`False`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`Process`	An asyncio.subprocess.Process object representing the running FFmpeg process

Example

async def main():
    # Start FFmpeg process and interact with it
    process = (
        await ffmpeg.input("input.mp4")
        .output("output.mp4")
        .run_async_awaitable()
    )
    # Do something while FFmpeg is running
    await process.wait()  # Wait for completion


asyncio.run(main())

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the stream.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

InputNode `dataclass` ¶

InputNode(
    *,
    kwargs: FrozenDict[
        str, str | int | float | bool | LazyValue
    ] = FrozenDict({}),
    inputs: tuple[()] = (),
    filename: str
)

Bases: Node

A node that represents an input file in the FFmpeg filter graph.

InputNode represents a media file that serves as input to the FFmpeg command. It provides access to the video and audio streams contained in the file, which can then be processed by filters.

Methods:

Name	Description
`replace`	Replace the old node in the graph with the new node.
`repr`	Get a string representation of this input node.
`stream`	Get a combined audio-video stream from this input file.
`view`	Visualize the Node.

Attributes:

Name	Type	Description
`audio`	`AudioStream`	Get the audio stream from this input file.
`filename`	`str`	The path to the input media file
`hex`	`str`	Get the hexadecimal hash of the object.
`inputs`	`tuple[()]`	Input nodes have no inputs themselves (they are source nodes)
`kwargs`	`FrozenDict[str, str \| int \| float \| bool \| LazyValue]`	Represents the keyword arguments of the node.
`max_depth`	`int`	Get the maximum depth of the node (longest path from any input).
`upstream_nodes`	`set[Node]`	Get all upstream nodes of the node.
`video`	`VideoStream`	Get the video stream from this input file.

audio `property` ¶

audio: AudioStream

Get the audio stream from this input file.

This property provides access to the audio component of the input file. The resulting AudioStream can be used as input to audio filters.

Returns:

Type	Description
`AudioStream`	An AudioStream representing the audio content of this input file

Example

# Access the audio stream from an input file
input_node = ffmpeg.input("input.mp4")
audio = input_node.audio
# Apply a filter to the audio stream
volume_adjusted = audio.volume(volume=2.0)

filename `instance-attribute` ¶

filename: str

The path to the input media file

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

inputs `class-attribute` `instance-attribute` ¶

inputs: tuple[()] = ()

Input nodes have no inputs themselves (they are source nodes)

kwargs `class-attribute` `instance-attribute` ¶

kwargs: FrozenDict[
    str, str | int | float | bool | LazyValue
] = FrozenDict({})

Represents the keyword arguments of the node.

max_depth `cached` `property` ¶

max_depth: int

Get the maximum depth of the node (longest path from any input).

The result is cached. The iterative computation also pre-populates the cache for all upstream nodes so that subsequent calls are O(1).

Returns:

Type	Description
`int`	The maximum depth of the node.

upstream_nodes `property` ¶

upstream_nodes: set[Node]

Get all upstream nodes of the node.

Returns:

Type	Description
`set[Node]`	The upstream nodes of the node.

video `property` ¶

video: VideoStream

Get the video stream from this input file.

This property provides access to the video component of the input file. The resulting VideoStream can be used as input to video filters.

Returns:

Type	Description
`VideoStream`	A VideoStream representing the video content of this input file

Example

# Access the video stream from an input file
input_node = ffmpeg.input("input.mp4")
video = input_node.video
# Apply a filter to the video stream
scaled = video.scale(width=1280, height=720)

replace ¶

replace(old_node: Node, new_node: Node) -> Node

Replace the old node in the graph with the new node.

Parameters:

Name	Type	Description	Default
`old_node`	`Node`	The old node to replace.	required
`new_node`	`Node`	The new node to replace with.	required

Returns:

Type	Description
`Node`	The new graph with the replaced node.

repr ¶

repr() -> str

Get a string representation of this input node.

Returns:

Type	Description
`str`	The basename of the input file

stream ¶

stream() -> AVStream

Get a combined audio-video stream from this input file.

This method provides access to both the audio and video components of the input file as a single AVStream. This is useful when you need to work with both components together.

Returns:

Type	Description
`AVStream`	An AVStream representing both audio and video content

Example

# Access both audio and video from an input file
input_node = ffmpeg.input("input.mp4")
av_stream = input_node.stream()
# Output both audio and video to a new file
output = av_stream.output("output.mp4")

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the Node.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

LoopbackDecoderNode `dataclass` ¶

LoopbackDecoderNode(
    *,
    kwargs: FrozenDict[
        str, str | int | float | bool | LazyValue
    ] = FrozenDict({}),
    inputs: tuple[OutputStream, ...]
)

Bases: Node

A node that represents an FFmpeg loopback decoder (FFmpeg >= 7.0).

A loopback decoder (-dec of:ost) decodes the output of an existing encoder and exposes the decoded frames as a filtergraph input labeled [dec:N]. Its input references an already-defined output stream; its output is a filterable stream usable in filter graphs.

Methods:

Name	Description
`replace`	Replace the old node in the graph with the new node.
`repr`	Get a string representation of this loopback decoder node.
`view`	Visualize the Node.

Attributes:

Name	Type	Description
`audio`	`AudioStream`	Get the decoded audio stream from this loopback decoder.
`hex`	`str`	Get the hexadecimal hash of the object.
`inputs`	`tuple[OutputStream, ...]`	The tapped output stream (exactly one): its node is the OutputNode and its
`kwargs`	`FrozenDict[str, str \| int \| float \| bool \| LazyValue]`	Represents the keyword arguments of the node.
`max_depth`	`int`	Get the maximum depth of the node (longest path from any input).
`upstream_nodes`	`set[Node]`	Get all upstream nodes of the node.
`video`	`VideoStream`	Get the decoded video stream from this loopback decoder.

audio `property` ¶

audio: AudioStream

Get the decoded audio stream from this loopback decoder.

Returns:

Type	Description
`AudioStream`	An AudioStream usable as input to audio filters

Raises:

Type	Description
`FFMpegTypeError`	If the tapped output stream is statically known to not be an audio stream

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

inputs `instance-attribute` ¶

inputs: tuple[OutputStream, ...]

The tapped output stream (exactly one): its node is the OutputNode and its index is the output stream index (ost) within that output file

kwargs `class-attribute` `instance-attribute` ¶

kwargs: FrozenDict[
    str, str | int | float | bool | LazyValue
] = FrozenDict({})

Represents the keyword arguments of the node.

max_depth `cached` `property` ¶

max_depth: int

Get the maximum depth of the node (longest path from any input).

The result is cached. The iterative computation also pre-populates the cache for all upstream nodes so that subsequent calls are O(1).

Returns:

Type	Description
`int`	The maximum depth of the node.

upstream_nodes `property` ¶

upstream_nodes: set[Node]

Get all upstream nodes of the node.

Returns:

Type	Description
`set[Node]`	The upstream nodes of the node.

video `property` ¶

video: VideoStream

Get the decoded video stream from this loopback decoder.

Returns:

Type	Description
`VideoStream`	A VideoStream usable as input to video filters

Raises:

Type	Description
`FFMpegTypeError`	If the tapped output stream is statically known to not be a video stream

replace ¶

replace(old_node: Node, new_node: Node) -> Node

Replace the old node in the graph with the new node.

Parameters:

Name	Type	Description	Default
`old_node`	`Node`	The old node to replace.	required
`new_node`	`Node`	The new node to replace with.	required

Returns:

Type	Description
`Node`	The new graph with the replaced node.

repr ¶

repr() -> str

Get a string representation of this loopback decoder node.

Returns:

Type	Description
`str`	The string "loopback"

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the Node.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

OutputNode `dataclass` ¶

OutputNode(
    *,
    kwargs: FrozenDict[
        str, str | int | float | bool | LazyValue
    ] = FrozenDict({}),
    inputs: tuple[FilterableStream, ...],
    filename: str
)

Bases: Node

A node that represents an output file in the FFmpeg filter graph.

OutputNode represents a destination file where processed media streams will be written. It connects one or more streams (video, audio, or both) to an output file and specifies output options like codecs and formats.

Methods:

Name	Description
`replace`	Replace the old node in the graph with the new node.
`repr`	Get a string representation of this output node.
`stream`	Get an output stream representing this output file.
`view`	Visualize the Node.

Attributes:

Name	Type	Description
`filename`	`str`	The path to the output media file
`hex`	`str`	Get the hexadecimal hash of the object.
`inputs`	`tuple[FilterableStream, ...]`	The streams to be written to this output file
`kwargs`	`FrozenDict[str, str \| int \| float \| bool \| LazyValue]`	Represents the keyword arguments of the node.
`max_depth`	`int`	Get the maximum depth of the node (longest path from any input).
`upstream_nodes`	`set[Node]`	Get all upstream nodes of the node.

filename `instance-attribute` ¶

filename: str

The path to the output media file

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

inputs `instance-attribute` ¶

inputs: tuple[FilterableStream, ...]

The streams to be written to this output file

kwargs `class-attribute` `instance-attribute` ¶

kwargs: FrozenDict[
    str, str | int | float | bool | LazyValue
] = FrozenDict({})

Represents the keyword arguments of the node.

max_depth `cached` `property` ¶

max_depth: int

Get the maximum depth of the node (longest path from any input).

The result is cached. The iterative computation also pre-populates the cache for all upstream nodes so that subsequent calls are O(1).

Returns:

Type	Description
`int`	The maximum depth of the node.

upstream_nodes `property` ¶

upstream_nodes: set[Node]

Get all upstream nodes of the node.

Returns:

Type	Description
`set[Node]`	The upstream nodes of the node.

replace ¶

replace(old_node: Node, new_node: Node) -> Node

Replace the old node in the graph with the new node.

Parameters:

Name	Type	Description	Default
`old_node`	`Node`	The old node to replace.	required
`new_node`	`Node`	The new node to replace with.	required

Returns:

Type	Description
`Node`	The new graph with the replaced node.

repr ¶

repr() -> str

Get a string representation of this output node.

Returns:

Type	Description
`str`	The basename of the output file

stream ¶

stream() -> OutputStream

Get an output stream representing this output file.

This method creates an OutputStream object that wraps this OutputNode, allowing it to be used in operations that require an output stream, such as adding global options.

Returns:

Type	Description
`OutputStream`	An OutputStream representing this output file

Example

# Create an output file and add global options
output_node = video.output("output.mp4")
output_stream = output_node.stream()
with_global_opts = output_stream.global_args(y=True)

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the Node.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

OutputStream `dataclass` ¶

OutputStream(
    *,
    node: OutputNode,
    index: int | None = None,
    optional: bool = False
)

Bases: Stream, GlobalRunable

A stream representing an output file with additional capabilities.

OutputStream wraps an OutputNode and provides additional functionality, particularly the ability to add global FFmpeg options. This class serves as an intermediate step between creating an output file and executing the FFmpeg command.

Methods:

Name	Description
`compile`	Build command-line arguments for invoking FFmpeg.
`compile_line`	Build a command-line string for invoking FFmpeg.
`global_args`	Set global options.
`merge_outputs`	Merge multiple output streams into a single command.
`overwrite_output`	Set the FFmpeg command to overwrite output files without asking.
`run`	Run FFmpeg synchronously and wait for completion.
`run_async`	Run FFmpeg asynchronously as a subprocess.
`run_async_awaitable`	Run FFmpeg asynchronously using asyncio.
`view`	Visualize the stream.

Attributes:

Name	Type	Description
`hex`	`str`	Get the hexadecimal hash of the object.
`index`	`int \| None`	Represents the index of the stream in the node's output streams.
`node`	`OutputNode`	The output node this stream represents
`optional`	`bool`	Represents whether the stream is optional.

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

index `class-attribute` `instance-attribute` ¶

index: int | None = None

Represents the index of the stream in the node's output streams.

Note

See Also: Stream specifiers stream_index

node `instance-attribute` ¶

node: OutputNode

The output node this stream represents

optional `class-attribute` `instance-attribute` ¶

optional: bool = False

Represents whether the stream is optional.

Note

compile ¶

compile(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> list[str]

Build command-line arguments for invoking FFmpeg.

This method converts the filter graph into a list of command-line arguments that can be passed to subprocess functions or executed directly. It handles the FFmpeg executable name, overwrite options, and automatic fixing of the filter graph.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph, such as adding split filters for reused streams	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`list[str]`	A list of strings representing the complete FFmpeg command

Example

# Get the command-line arguments for a filter graph
args = ffmpeg.input("input.mp4").output("output.mp4").compile()
# Result: ['ffmpeg', '-i', 'input.mp4', 'output.mp4']

compile_line ¶

compile_line(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> str

Build a command-line string for invoking FFmpeg.

This method is similar to compile(), but returns a single string with proper escaping instead of a list of arguments. This is useful for logging or displaying the command to users.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`str`	A string representing the complete FFmpeg command with proper escaping

Example

# Get a command-line string for a filter graph
cmd_str = ffmpeg.input("input.mp4").output("output.mp4").compile_line()
# Result: 'ffmpeg -i input.mp4 output.mp4'

global_args ¶

global_args(
    *,
    loglevel: Func = None,
    v: Func = None,
    report: Func = None,
    max_alloc: Func = None,
    cpuflags: Func = None,
    cpucount: Func = None,
    hide_banner: Func = None,
    y: Func = None,
    n: Func = None,
    ignore_unknown: Func = None,
    copy_unknown: Func = None,
    recast_media: Func = None,
    benchmark: Func = None,
    benchmark_all: Func = None,
    progress: Func = None,
    stdin: Func = None,
    timelimit: Func = None,
    dump: Func = None,
    hex: Func = None,
    vsync: Func = None,
    frame_drop_threshold: Func = None,
    _async: Func = None,
    adrift_threshold: Func = None,
    copyts: Func = None,
    start_at_zero: Func = None,
    copytb: Func = None,
    dts_delta_threshold: Func = None,
    dts_error_threshold: Func = None,
    xerror: Func = None,
    abort_on: Func = None,
    filter_threads: Func = None,
    filter_complex: Func = None,
    filter_complex_threads: Func = None,
    lavfi: Func = None,
    filter_complex_script: Func = None,
    auto_conversion_filters: Func = None,
    stats: Func = None,
    stats_period: Func = None,
    debug_ts: Func = None,
    max_error_rate: Func = None,
    psnr: Func = None,
    vstats: Func = None,
    vstats_file: Func = None,
    vstats_version: Func = None,
    qphist: Func = None,
    vol: Func = None,
    vaapi_device: Func = None,
    init_hw_device: Func = None,
    filter_hw_device: Func = None,
    extra_options: dict[str, Any] | None = None
) -> GlobalStream

Set global options.

Parameters:

Name	Type	Description	Default
`loglevel`	`Func`	set logging level	`None`
`v`	`Func`	set logging level	`None`
`report`	`Func`	generate a report	`None`
`max_alloc`	`Func`	set maximum size of a single allocated block	`None`
`cpuflags`	`Func`	force specific cpu flags	`None`
`cpucount`	`Func`	force specific cpu count	`None`
`hide_banner`	`Func`	do not show program banner	`None`
`y`	`Func`	overwrite output files	`None`
`n`	`Func`	never overwrite output files	`None`
`ignore_unknown`	`Func`	Ignore unknown stream types	`None`
`copy_unknown`	`Func`	Copy unknown stream types	`None`
`recast_media`	`Func`	allow recasting stream type in order to force a decoder of different media type	`None`
`benchmark`	`Func`	add timings for benchmarking	`None`
`benchmark_all`	`Func`	add timings for each task	`None`
`progress`	`Func`	write program-readable progress information	`None`
`stdin`	`Func`	enable or disable interaction on standard input	`None`
`timelimit`	`Func`	set max runtime in seconds in CPU user time	`None`
`dump`	`Func`	dump each input packet	`None`
`hex`	`Func`	when dumping packets, also dump the payload	`None`
`vsync`	`Func`	set video sync method globally; deprecated, use -fps_mode	`None`
`frame_drop_threshold`	`Func`	frame drop threshold	`None`
`_async`	`Func`	audio sync method	`None`
`adrift_threshold`	`Func`	audio drift threshold	`None`
`copyts`	`Func`	copy timestamps	`None`
`start_at_zero`	`Func`	shift input timestamps to start at 0 when using copyts	`None`
`copytb`	`Func`	copy input stream time base when stream copying	`None`
`dts_delta_threshold`	`Func`	timestamp discontinuity delta threshold	`None`
`dts_error_threshold`	`Func`	timestamp error delta threshold	`None`
`xerror`	`Func`	exit on error	`None`
`abort_on`	`Func`	abort on the specified condition flags	`None`
`filter_threads`	`Func`	number of non-complex filter threads	`None`
`filter_complex`	`Func`	create a complex filtergraph	`None`
`filter_complex_threads`	`Func`	number of threads for -filter_complex	`None`
`lavfi`	`Func`	create a complex filtergraph	`None`
`filter_complex_script`	`Func`	read complex filtergraph description from a file	`None`
`auto_conversion_filters`	`Func`	enable automatic conversion filters globally	`None`
`stats`	`Func`	print progress report during encoding	`None`
`stats_period`	`Func`	set the period at which ffmpeg updates stats and -progress output	`None`
`debug_ts`	`Func`	print timestamp debugging info	`None`
`max_error_rate`	`Func`	ratio of decoding errors (0.0: no errors, 1.0: 100% errors) above which ffmpeg returns an error instead of success.	`None`
`psnr`	`Func`	calculate PSNR of compressed frames	`None`
`vstats`	`Func`	dump video coding statistics to file	`None`
`vstats_file`	`Func`	dump video coding statistics to file	`None`
`vstats_version`	`Func`	Version of the vstats format to use.	`None`
`qphist`	`Func`	show QP histogram	`None`
`vol`	`Func`	change audio volume (256=normal)	`None`
`vaapi_device`	`Func`	set VAAPI hardware device (DRM path or X11 display name)	`None`
`init_hw_device`	`Func`	initialise hardware device	`None`
`filter_hw_device`	`Func`	set hardware device used when filtering	`None`
`extra_options`	`dict[str, Any] \| None`	Additional options	`None`

Returns:

Name	Type	Description
`GlobalStream`	`GlobalStream`	GlobalStream instance

merge_outputs ¶

merge_outputs(*streams: OutputStream) -> GlobalStream

Merge multiple output streams into a single command.

This method allows combining multiple output files into a single FFmpeg command, which is more efficient than running separate commands for each output. It creates a GlobalNode that includes all the specified output streams.

Parameters:

Name	Type	Description	Default
`*streams`	`OutputStream`	Additional output streams to include in the same command	`()`

Returns:

Type	Description
`GlobalStream`	A GlobalStream that represents the combined outputs

Example

# Create two output files with one command
video = ffmpeg.input("input.mp4").video
output1 = video.output("output1.mp4")
output2 = video.output("output2.webm")
merged = output1.merge_outputs(output2)
merged.run()  # Creates both output files with one FFmpeg command

overwrite_output ¶

overwrite_output() -> GlobalStream

Set the FFmpeg command to overwrite output files without asking.

This method adds the -y option to the FFmpeg command, which causes FFmpeg to overwrite output files without prompting for confirmation. It's equivalent to calling global_args(y=True).

Returns:

Type	Description
`GlobalStream`	A GlobalStream with the overwrite option enabled

Example

# Overwrite output file if it already exists
ffmpeg.input("input.mp4").output("output.mp4").overwrite_output().run()

run ¶

run(
    cmd: str | list[str] = "ffmpeg",
    capture_stdout: bool = False,
    capture_stderr: bool = False,
    input: bytes | None = None,
    quiet: bool = False,
    tee_stderr: bool = False,
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> tuple[bytes, bytes]

Run FFmpeg synchronously and wait for completion.

This method executes the FFmpeg command in a separate process and waits for it to complete before returning. It's the most common way to run FFmpeg commands when you just want to process media files.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`capture_stdout`	`bool`	Whether to capture and return the process's stdout	`False`
`capture_stderr`	`bool`	Whether to capture and return the process's stderr. Note: This parameter is ignored when tee_stderr=True, as tee_stderr always captures stderr.	`False`
`input`	`bytes \| None`	Optional bytes to write to the process's stdin	`None`
`quiet`	`bool`	Whether to suppress output to the console	`False`
`tee_stderr`	`bool`	Whether to capture stderr and also display it to the console. When enabled, stderr will be captured and simultaneously displayed to the console (unless quiet=True). When tee_stderr=True, the capture_stderr parameter is ignored and stderr is always captured.	`False`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`bytes`	A tuple of (stdout_bytes, stderr_bytes), which will be empty bytes
`bytes`	objects if the respective capture_* parameter is False

Raises:

Type	Description
`FFMpegExecuteError`	If the FFmpeg process returns a non-zero exit code

Example

# Process a video file
stdout, stderr = ffmpeg.input("input.mp4").output("output.mp4").run()

# Capture FFmpeg's output
stdout, stderr = (
    ffmpeg.input("input.mp4").output("output.mp4").run(capture_stderr=True)
)
print(stderr.decode())  # Print FFmpeg's progress information

# Capture and display stderr at the same time
stdout, stderr = (
    ffmpeg.input("input.mp4").output("output.mp4").run(tee_stderr=True)
)
# stderr is both displayed in console and captured for later use

run_async ¶

run_async(
    cmd: str | list[str] = "ffmpeg",
    pipe_stdin: bool = False,
    pipe_stdout: bool = False,
    pipe_stderr: bool = False,
    quiet: bool = False,
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> Popen[bytes]

Run FFmpeg asynchronously as a subprocess.

This method executes the FFmpeg command in a separate process without waiting for it to complete. This is useful for long-running operations or when you need to interact with the process while it's running.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`pipe_stdin`	`bool`	Whether to create a pipe for writing to the process's stdin	`False`
`pipe_stdout`	`bool`	Whether to create a pipe for reading from the process's stdout	`False`
`pipe_stderr`	`bool`	Whether to create a pipe for reading from the process's stderr	`False`
`quiet`	`bool`	Whether to capture stderr (implies pipe_stderr=True)	`False`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`Popen[bytes]`	A subprocess.Popen object representing the running FFmpeg process

Example

# Start FFmpeg process and interact with it
process = ffmpeg.input("input.mp4").output("output.mp4").run_async()
# Do something while FFmpeg is running
process.wait()  # Wait for completion

run_async_awaitable `async` ¶

run_async_awaitable(
    cmd: str | list[str] = "ffmpeg",
    pipe_stdin: bool = False,
    pipe_stdout: bool = False,
    pipe_stderr: bool = False,
    quiet: bool = False,
    overwrite_output: bool | None = None,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> Process

Run FFmpeg asynchronously using asyncio.

This method executes the FFmpeg command as an asyncio subprocess, returning an asyncio.subprocess.Process object that can be awaited. This is useful for long-running operations in async code or when you need to interact with the process while it's running in an async context.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`pipe_stdin`	`bool`	Whether to create a pipe for writing to the process's stdin	`False`
`pipe_stdout`	`bool`	Whether to create a pipe for reading from the process's stdout	`False`
`pipe_stderr`	`bool`	Whether to create a pipe for reading from the process's stderr	`False`
`quiet`	`bool`	Whether to capture stderr (implies pipe_stderr=True)	`False`
`overwrite_output`	`bool \| None`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`
`use_filter_complex_script`	`bool`	If True, use -filter_complex_script with a temporary file instead of -filter_complex	`False`

Returns:

Type	Description
`Process`	An asyncio.subprocess.Process object representing the running FFmpeg process

Example

async def main():
    # Start FFmpeg process and interact with it
    process = (
        await ffmpeg.input("input.mp4")
        .output("output.mp4")
        .run_async_awaitable()
    )
    # Do something while FFmpeg is running
    await process.wait()  # Wait for completion


asyncio.run(main())

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the stream.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

Stream `dataclass` ¶

Stream(
    *,
    node: Node,
    index: int | None = None,
    optional: bool = False
)

Bases: HashableBaseModel

A 'Stream' represents a sequence of data flow in the Directed Acyclic Graph (DAG).

Note

Each stream in the DAG is a sequence of operations that transforms the data from its input form to its output form. The stream is an essential component of the DAG, as it defines the order and the nature of the operations that are performed on the data.

Methods:

Name	Description
`view`	Visualize the stream.

Attributes:

Name	Type	Description
`hex`	`str`	Get the hexadecimal hash of the object.
`index`	`int \| None`	Represents the index of the stream in the node's output streams.
`node`	`Node`	Represents the node that the stream is connected to in the upstream direction.
`optional`	`bool`	Represents whether the stream is optional.

hex `cached` `property` ¶

hex: str

Get the hexadecimal hash of the object.

index `class-attribute` `instance-attribute` ¶

index: int | None = None

Represents the index of the stream in the node's output streams.

Note

See Also: Stream specifiers stream_index

node `instance-attribute` ¶

node: Node

Represents the node that the stream is connected to in the upstream direction.

Note

In the context of a data stream, the 'upstream' refers to the source of the data, or where the data is coming from. Therefore, the 'upstream node' is the node that is providing the data to the current stream.

optional `class-attribute` `instance-attribute` ¶

optional: bool = False

Represents whether the stream is optional.

Note

view ¶

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the stream.

Parameters:

Name	Type	Description	Default
`format`	`Literal['png', 'svg', 'dot']`	The format of the view.	`'png'`

Returns:

Type	Description
`str`	The file path of the visualization.

filter_node_factory ¶

filter_node_factory(
    ffmpeg_filter_def: FFMpegFilterDef,
    *inputs: FilterableStream,
    **kwargs: Any
) -> FilterNode

Create a FilterNode from an FFmpeg filter definition.

This function creates a FilterNode based on the provided FFmpeg filter definition. It handles the evaluation of Auto parameters and the conversion of input/output typing specifications from the filter definition.

Parameters:

Name	Type	Description	Default
`ffmpeg_filter_def`	`FFMpegFilterDef`	The FFmpeg filter definition to create a node from	required
`*inputs`	`FilterableStream`	The input streams to connect to the filter	`()`
`**kwargs`	`Any`	Filter-specific parameters as keyword arguments	`{}`

Returns:

Type	Description
`FilterNode`	A FilterNode configured according to the filter definition

Note

This function is primarily used internally by the filter generation system to create filter nodes from the FFmpeg filter definitions.

dag ¶

FilterNode dataclass ¶

hex cached property ¶

input_typings class-attribute instance-attribute ¶

inputs class-attribute instance-attribute ¶

kwargs class-attribute instance-attribute ¶

max_depth cached property ¶

name instance-attribute ¶

output_typings class-attribute instance-attribute ¶

upstream_nodes property ¶

audio ¶

replace ¶

repr ¶

video ¶

view ¶

GlobalNode dataclass ¶

hex cached property ¶

inputs instance-attribute ¶

kwargs class-attribute instance-attribute ¶

max_depth cached property ¶

upstream_nodes property ¶

replace ¶

repr ¶

stream ¶

view ¶

GlobalStream dataclass ¶

hex cached property ¶

index class-attribute instance-attribute ¶

node instance-attribute ¶

optional class-attribute instance-attribute ¶

compile ¶

compile_line ¶

global_args ¶

merge_outputs ¶

overwrite_output ¶

run ¶

run_async ¶

run_async_awaitable async ¶

view ¶

InputNode dataclass ¶

audio property ¶

filename instance-attribute ¶

hex cached property ¶

inputs class-attribute instance-attribute ¶

kwargs class-attribute instance-attribute ¶

max_depth cached property ¶

upstream_nodes property ¶

video property ¶

replace ¶

repr ¶

stream ¶

view ¶

LoopbackDecoderNode dataclass ¶

audio property ¶

hex cached property ¶

inputs instance-attribute ¶

kwargs class-attribute instance-attribute ¶

max_depth cached property ¶

upstream_nodes property ¶

video property ¶

replace ¶

repr ¶

view ¶

OutputNode dataclass ¶

filename instance-attribute ¶

hex cached property ¶

inputs instance-attribute ¶

kwargs class-attribute instance-attribute ¶

max_depth cached property ¶

upstream_nodes property ¶

replace ¶

repr ¶

stream ¶

view ¶

OutputStream dataclass ¶

hex cached property ¶

index class-attribute instance-attribute ¶

node instance-attribute ¶

optional class-attribute instance-attribute ¶

compile ¶

FilterNode `dataclass` ¶

hex `cached` `property` ¶

input_typings `class-attribute` `instance-attribute` ¶

inputs `class-attribute` `instance-attribute` ¶

kwargs `class-attribute` `instance-attribute` ¶

max_depth `cached` `property` ¶

name `instance-attribute` ¶

output_typings `class-attribute` `instance-attribute` ¶

upstream_nodes `property` ¶

GlobalNode `dataclass` ¶

hex `cached` `property` ¶

inputs `instance-attribute` ¶

kwargs `class-attribute` `instance-attribute` ¶

max_depth `cached` `property` ¶

upstream_nodes `property` ¶

GlobalStream `dataclass` ¶

hex `cached` `property` ¶

index `class-attribute` `instance-attribute` ¶

node `instance-attribute` ¶

optional `class-attribute` `instance-attribute` ¶

run_async_awaitable `async` ¶

InputNode `dataclass` ¶

audio `property` ¶

filename `instance-attribute` ¶

hex `cached` `property` ¶

inputs `class-attribute` `instance-attribute` ¶

kwargs `class-attribute` `instance-attribute` ¶

max_depth `cached` `property` ¶

upstream_nodes `property` ¶

video `property` ¶

LoopbackDecoderNode `dataclass` ¶

audio `property` ¶

hex `cached` `property` ¶

inputs `instance-attribute` ¶

kwargs `class-attribute` `instance-attribute` ¶

max_depth `cached` `property` ¶

upstream_nodes `property` ¶

video `property` ¶

OutputNode `dataclass` ¶

filename `instance-attribute` ¶

hex `cached` `property` ¶

inputs `instance-attribute` ¶

kwargs `class-attribute` `instance-attribute` ¶

max_depth `cached` `property` ¶

upstream_nodes `property` ¶

OutputStream `dataclass` ¶

hex `cached` `property` ¶

index `class-attribute` `instance-attribute` ¶

node `instance-attribute` ¶

optional `class-attribute` `instance-attribute` ¶

run_async_awaitable `async` ¶

Stream `dataclass` ¶

hex `cached` `property` ¶

index `class-attribute` `instance-attribute` ¶

node `instance-attribute` ¶

optional `class-attribute` `instance-attribute` ¶