dag

Directed Acyclic Graph (DAG) implementation for FFmpeg filter chains.

This package provides the core components for representing FFmpeg filter chains as directed acyclic graphs. It includes classes for different types of nodes (inputs, filters, outputs) and streams, as well as utilities for validating, compiling, and manipulating these graphs.

The DAG structure enables type-safe construction and validation of complex FFmpeg filter chains, ensuring that the resulting FFmpeg commands are valid and correctly structured.

Modules:

Name	Description
factory	Factory functions for creating FFmpeg filter nodes.
global_runnable	Global runnable utilities for FFmpeg DAG operations.
io	Input/output utilities for FFmpeg DAG operations.
nodes	DAG node definitions for FFmpeg filter graphs.
schema	DAG schema definitions for FFmpeg filter graphs.
tests
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.
FilterableStream	A stream that can be used as input to an FFmpeg filter.
GlobalNode	A node that represents global FFmpeg options.
InputNode	A node that represents an input file in the FFmpeg filter graph.
Node	A 'Node' represents a single operation in the Directed Acyclic Graph (DAG).
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).

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.
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 property

max_depth: int

Get the maximum depth of the node.

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.

FilterableStream dataclass

FilterableStream(
    *,
    node: FilterNode | InputNode,
    index: int | None = None,
    optional: bool = False
)

Bases: Stream, OutputArgs

A stream that can be used as input to an FFmpeg filter.

FilterableStream represents a media stream (audio or video) that can be processed by FFmpeg filters. It provides methods for applying various filters to the stream and for outputting the stream to a file.

This class serves as a base for specific stream types like VideoStream and AudioStream, providing common functionality for filter operations.

Methods:

Name	Description
afilter	Apply a custom audio filter to this stream.
filter_multi_output	Apply a custom filter with multiple outputs to this stream.
output	Output file URL.
vfilter	Apply a custom video filter to this stream.
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	FilterNode | InputNode	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: FilterNode | InputNode

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

See Also: Advanced options

afilter

afilter(
    *streams: FilterableStream,
    name: str,
    input_typings: tuple[StreamType, ...] = (audio,),
    **kwargs: Any
) -> AudioStream

Apply a custom audio filter to this stream.

This method applies a custom FFmpeg audio filter to this stream and returns the resulting audio stream. It's a convenience wrapper around filter_multi_output that handles the case of filters with a single audio output.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	Additional input streams for the filter	()
name	str	The name of the FFmpeg filter to apply	required
input_typings	tuple[StreamType, ...]	The expected types of the input streams (defaults to all audio)	(audio,)
**kwargs	Any	Filter-specific parameters as keyword arguments	{}

Returns:

Type	Description
AudioStream	An AudioStream representing the filter's output

Example

# Apply a volume filter to an audio stream
louder = stream.afilter(name="volume", volume=2.0)

filter_multi_output

filter_multi_output(
    *streams: FilterableStream,
    name: str,
    input_typings: tuple[StreamType, ...] = (),
    output_typings: tuple[StreamType, ...] = (),
    **kwargs: Any
) -> FilterNode

Apply a custom filter with multiple outputs to this stream.

This method creates a FilterNode that applies a custom FFmpeg filter to this stream (and optionally additional streams). Unlike vfilter and afilter which return a single stream, this method returns the FilterNode itself, allowing access to multiple output streams.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	Additional input streams for the filter	()
name	str	The name of the FFmpeg filter to apply	required
input_typings	tuple[StreamType, ...]	The expected types of the input streams	()
output_typings	tuple[StreamType, ...]	The types of output streams this filter produces	()
**kwargs	Any	Filter-specific parameters as keyword arguments	{}

Returns:

Type	Description
FilterNode	A FilterNode that can be used to access the filter's outputs

Example

# Split a video into two identical streams
split_node = stream.filter_multi_output(
    name="split", output_typings=(StreamType.video, StreamType.video)
)
stream1 = split_node.video(0)
stream2 = split_node.video(1)

output

output(
    *streams: FilterableStream,
    filename: str | Path,
    f: String = None,
    c: String = None,
    codec: String = None,
    pre: String = None,
    map: Func = None,
    map_metadata: String = None,
    map_chapters: Int = None,
    t: Time = None,
    to: Time = None,
    fs: Int64 = None,
    ss: Time = None,
    timestamp: Func = None,
    metadata: String = None,
    program: String = None,
    stream_group: String = None,
    dframes: Int64 = None,
    target: Func = None,
    shortest: Boolean = None,
    shortest_buf_duration: Float = None,
    bitexact: Boolean = None,
    apad: String = None,
    copyinkf: Boolean = None,
    copypriorss: Int = None,
    frames: Int64 = None,
    tag: String = None,
    q: Func = None,
    qscale: Func = None,
    profile: Func = None,
    filter: String = None,
    filter_script: String = None,
    attach: Func = None,
    disposition: String = None,
    thread_queue_size: Int = None,
    bits_per_raw_sample: Int = None,
    stats_enc_pre: String = None,
    stats_enc_post: String = None,
    stats_mux_pre: String = None,
    stats_enc_pre_fmt: String = None,
    stats_enc_post_fmt: String = None,
    stats_mux_pre_fmt: String = None,
    vframes: Int64 = None,
    r: String = None,
    fpsmax: String = None,
    s: String = None,
    aspect: String = None,
    pix_fmt: String = None,
    vn: Boolean = None,
    rc_override: String = None,
    vcodec: String = None,
    timecode: Func = None,
    _pass: Int = None,
    passlogfile: String = None,
    vf: String = None,
    intra_matrix: String = None,
    inter_matrix: String = None,
    chroma_intra_matrix: String = None,
    vtag: String = None,
    fps_mode: String = None,
    force_fps: Boolean = None,
    streamid: Func = None,
    force_key_frames: String = None,
    b: Func = None,
    autoscale: Boolean = None,
    fix_sub_duration_heartbeat: Boolean = None,
    aframes: Int64 = None,
    aq: Func = None,
    ar: Int = None,
    ac: Int = None,
    an: Boolean = None,
    acodec: String = None,
    ab: Func = None,
    atag: String = None,
    sample_fmt: String = None,
    channel_layout: String = None,
    ch_layout: String = None,
    af: String = None,
    sn: Boolean = None,
    scodec: String = None,
    stag: String = None,
    muxdelay: Float = None,
    muxpreload: Float = None,
    sdp_file: Func = None,
    time_base: String = None,
    enc_time_base: String = None,
    bsf: String = None,
    apre: String = None,
    vpre: String = None,
    spre: String = None,
    fpre: String = None,
    max_muxing_queue_size: Int = None,
    muxing_queue_data_threshold: Int = None,
    dcodec: String = None,
    dn: Boolean = None,
    top: Int = None,
    encoder_options: FFMpegEncoderOption | None = None,
    muxer_options: FFMpegMuxerOption | None = None,
    format_options: (
        FFMpegAVFormatContextEncoderOption | None
    ) = None,
    codec_options: (
        FFMpegAVCodecContextEncoderOption | None
    ) = None,
    extra_options: dict[str, Any] | None = None
) -> OutputStream

Output file URL.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	the streams to output	()
filename	str | Path	the filename to output to	required
f	String	force container format (auto-detected otherwise)	None
c	String	select encoder/decoder ('copy' to copy stream without reencoding)	None
codec	String	alias for -c (select encoder/decoder)	None
pre	String	preset name	None
map	Func	set input stream mapping	None
map_metadata	String	set metadata information of outfile from infile	None
map_chapters	Int	set chapters mapping	None
t	Time	stop transcoding after specified duration	None
to	Time	stop transcoding after specified time is reached	None
fs	Int64	set the limit file size in bytes	None
ss	Time	start transcoding at specified time	None
timestamp	Func	set the recording timestamp ('now' to set the current time)	None
metadata	String	add metadata	None
program	String	add program with specified streams	None
stream_group	String	add stream group with specified streams and group type-specific arguments	None
dframes	Int64	set the number of data frames to output	None
target	Func	specify target file type (\"vcd\", \"svcd\", \"dvd\", \"dv\" or \"dv50\	None

"with optional prefixes \"pal-\", \"ntsc-\" or \"film-\") shortest: finish encoding within shortest input shortest_buf_duration: maximum buffering duration (in seconds) for the -shortest option bitexact: bitexact mode apad: audio pad copyinkf: copy initial non-keyframes copypriorss: copy or discard frames before start time frames: set the number of frames to output tag: force codec tag/fourcc q: use fixed quality scale (VBR) qscale: use fixed quality scale (VBR) profile: set profile filter: apply specified filters to audio/video filter_script: deprecated, use -/filter attach: add an attachment to the output file disposition: disposition thread_queue_size: set the maximum number of queued packets from the demuxer bits_per_raw_sample: set the number of bits per raw sample stats_enc_pre: write encoding stats before encoding stats_enc_post: write encoding stats after encoding stats_mux_pre: write packets stats before muxing stats_enc_pre_fmt: format of the stats written with -stats_enc_pre stats_enc_post_fmt: format of the stats written with -stats_enc_post stats_mux_pre_fmt: format of the stats written with -stats_mux_pre vframes: set the number of video frames to output r: override input framerate/convert to given output framerate (Hz value, fraction or abbreviation) fpsmax: set max frame rate (Hz value, fraction or abbreviation) s: set frame size (WxH or abbreviation) aspect: set aspect ratio (4:3, 16:9 or 1.3333, 1.7777) pix_fmt: set pixel format vn: disable video rc_override: rate control override for specific intervals vcodec: alias for -c:v (select encoder/decoder for video streams) timecode: set initial TimeCode value. _pass: select the pass number (1 to 3) passlogfile: select two pass log file name prefix vf: alias for -filter:v (apply filters to video streams) intra_matrix: specify intra matrix coeffs inter_matrix: specify inter matrix coeffs chroma_intra_matrix: specify intra matrix coeffs vtag: force video tag/fourcc fps_mode: set framerate mode for matching video streams; overrides vsync force_fps: force the selected framerate, disable the best supported framerate selection streamid: set the value of an outfile streamid force_key_frames: force key frames at specified timestamps b: video bitrate (please use -b:v) autoscale: automatically insert a scale filter at the end of the filter graph fix_sub_duration_heartbeat: set this video output stream to be a heartbeat stream for fix_sub_duration, according to which subtitles should be split at random access points aframes: set the number of audio frames to output aq: set audio quality (codec-specific) ar: set audio sampling rate (in Hz) ac: set number of audio channels an: disable audio acodec: alias for -c:a (select encoder/decoder for audio streams) ab: alias for -b:a (select bitrate for audio streams) atag: force audio tag/fourcc sample_fmt: set sample format channel_layout: set channel layout ch_layout: set channel layout af: alias for -filter:a (apply filters to audio streams) sn: disable subtitle scodec: alias for -c:s (select encoder/decoder for subtitle streams) stag: force subtitle tag/fourcc muxdelay: set the maximum demux-decode delay muxpreload: set the initial demux-decode delay sdp_file: specify a file in which to print sdp information time_base: set the desired time base hint for output stream (1:24, 1:48000 or 0.04166, 2.0833e-5) enc_time_base: set the desired time base for the encoder (1:24, 1:48000 or 0.04166, 2.0833e-5). two special values are defined - 0 = use frame rate (video) or sample rate (audio),-1 = match source time base bsf: A comma-separated list of bitstream filters apre: set the audio options to the indicated preset vpre: set the video options to the indicated preset spre: set the subtitle options to the indicated preset fpre: set options from indicated preset file max_muxing_queue_size: maximum number of packets that can be buffered while waiting for all streams to initialize muxing_queue_data_threshold: set the threshold after which max_muxing_queue_size is taken into account dcodec: alias for -c:d (select encoder/decoder for data streams) dn: disable data top: deprecated, use the setfield video filter encoder_options: ffmpeg's encoder options muxer_options: FFMpegMuxerOption format_options: FFMpegAVFormatContextEncoderOption codec_options: FFMpegAVCodecContextEncoderOption extra_options: the arguments for the output

Returns:

Type	Description
OutputStream	the output stream

vfilter

vfilter(
    *streams: FilterableStream,
    name: str,
    input_typings: tuple[StreamType, ...] = (video,),
    **kwargs: Any
) -> VideoStream

Apply a custom video filter to this stream.

This method applies a custom FFmpeg video filter to this stream and returns the resulting video stream. It's a convenience wrapper around filter_multi_output that handles the case of filters with a single video output.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	Additional input streams for the filter	()
name	str	The name of the FFmpeg filter to apply	required
input_typings	tuple[StreamType, ...]	The expected types of the input streams (defaults to all video)	(video,)
**kwargs	Any	Filter-specific parameters as keyword arguments	{}

Returns:

Type	Description
VideoStream	A VideoStream representing the filter's output

Example

# Apply a blur filter to a video stream
blurred = stream.vfilter(name="boxblur", luma_radius=2)

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.

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.
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 property

max_depth: int

Get the maximum depth of the node.

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.

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.
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 property

max_depth: int

Get the maximum depth of the node.

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.

Node dataclass

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

Bases: HashableBaseModel

A 'Node' represents a single operation in the Directed Acyclic Graph (DAG).

Note

Each node in the DAG represents a single operation that transforms the data from its input form to its output form. The node is an essential component of the DAG, as it defines the nature of the operations that are performed on the data.

Methods:

Name	Description
replace	Replace the old node in the graph with the new node.
repr	Get the representation of the node.
view	Visualize the Node.

Attributes:

Name	Type	Description
hex	str	Get the hexadecimal hash of the object.
inputs	tuple[Stream, ...]	Represents the input streams of the node.
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.
upstream_nodes	set[Node]	Get all upstream nodes of the node.

hex cached property

hex: str

Get the hexadecimal hash of the object.

inputs class-attribute instance-attribute

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

Represents the input streams of the node.

kwargs class-attribute instance-attribute

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

Represents the keyword arguments of the node.

max_depth property

max_depth: int

Get the maximum depth of the node.

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.

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.
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 property

max_depth: int

Get the maximum depth of the node.

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.
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

See Also: Advanced options

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: Boolean = None,
    y: Boolean = None,
    n: Boolean = None,
    ignore_unknown: Boolean = None,
    copy_unknown: Boolean = None,
    recast_media: Boolean = None,
    benchmark: Boolean = None,
    benchmark_all: Boolean = None,
    progress: Func = None,
    stdin: Boolean = None,
    timelimit: Func = None,
    dump: Boolean = None,
    hex: Boolean = None,
    frame_drop_threshold: Float = None,
    copyts: Boolean = None,
    start_at_zero: Boolean = None,
    copytb: Int = None,
    dts_delta_threshold: Float = None,
    dts_error_threshold: Float = None,
    xerror: Boolean = None,
    abort_on: Func = None,
    filter_threads: Func = None,
    filter_complex: Func = None,
    filter_complex_threads: Int = None,
    lavfi: Func = None,
    filter_complex_script: Func = None,
    auto_conversion_filters: Boolean = None,
    stats: Boolean = None,
    stats_period: Func = None,
    debug_ts: Boolean = None,
    max_error_rate: Float = None,
    vstats: Func = None,
    vstats_file: Func = None,
    vstats_version: Int = None,
    init_hw_device: Func = None,
    filter_hw_device: Func = None,
    adrift_threshold: Func = None,
    qphist: Func = None,
    vsync: 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	Boolean	do not show program banner	None
y	Boolean	overwrite output files	None
n	Boolean	never overwrite output files	None
ignore_unknown	Boolean	Ignore unknown stream types	None
copy_unknown	Boolean	Copy unknown stream types	None
recast_media	Boolean	allow recasting stream type in order to force a decoder of different media type	None
benchmark	Boolean	add timings for benchmarking	None
benchmark_all	Boolean	add timings for each task	None
progress	Func	write program-readable progress information	None
stdin	Boolean	enable or disable interaction on standard input	None
timelimit	Func	set max runtime in seconds in CPU user time	None
dump	Boolean	dump each input packet	None
hex	Boolean	when dumping packets, also dump the payload	None
frame_drop_threshold	Float	frame drop threshold	None
copyts	Boolean	copy timestamps	None
start_at_zero	Boolean	shift input timestamps to start at 0 when using copyts	None
copytb	Int	copy input stream time base when stream copying	None
dts_delta_threshold	Float	timestamp discontinuity delta threshold	None
dts_error_threshold	Float	timestamp error delta threshold	None
xerror	Boolean	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	Int	number of threads for -filter_complex	None
lavfi	Func	create a complex filtergraph	None
filter_complex_script	Func	deprecated, use -/filter_complex instead	None
auto_conversion_filters	Boolean	enable automatic conversion filters globally	None
stats	Boolean	print progress report during encoding	None
stats_period	Func	set the period at which ffmpeg updates stats and -progress output	None
debug_ts	Boolean	print timestamp debugging info	None
max_error_rate	Float	ratio of decoding errors (0.0: no errors, 1.0: 100% errors) above which ffmpeg returns an error instead of success.	None
vstats	Func	dump video coding statistics to file	None
vstats_file	Func	dump video coding statistics to file	None
vstats_version	Int	Version of the vstats format to use.	None
init_hw_device	Func	initialise hardware device	None
filter_hw_device	Func	set hardware device used when filtering	None
adrift_threshold	Func	deprecated, does nothing	None
qphist	Func	deprecated, does nothing	None
vsync	Func	set video sync method globally; deprecated, use -fps_mode	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,
    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	False
input	bytes | None	Optional bytes to write to the process's stdin	None
quiet	bool	Whether to suppress output to the console	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

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

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

See Also: Advanced options

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.