nodes

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.
InputNode	A node that represents an input file in the FFmpeg filter graph.
OutputNode	A node that represents an output file in the FFmpeg filter graph.
OutputStream	A stream representing an output file with additional capabilities.
GlobalNode	A node that represents global FFmpeg options.
GlobalStream	A stream representing a set of global FFmpeg options.

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
repr	Get a string representation of this filter node.
video	Get a video output stream from this filter node.
audio	Get an audio output stream from this filter node.
get_args	Generate the FFmpeg filter string for this filter node.
replace	Replace the old node in the graph with the new node.
view	Visualize the Node.

Attributes:

Name	Type	Description
name	str	The name of the filter as used in FFmpeg (e.g., 'scale', 'overlay', 'amix')
inputs	tuple[FilterableStream, ...]	The input streams that this filter processes
input_typings	tuple[StreamType, ...]	The expected types (audio/video) for each input stream
output_typings	tuple[StreamType, ...]	The types (audio/video) of each output stream this filter produces
hex	str	Get the hexadecimal hash of the object.
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.

name instance-attribute

name: str

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

inputs class-attribute instance-attribute

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

The input streams that this filter processes

input_typings class-attribute instance-attribute

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

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

output_typings class-attribute instance-attribute

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

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

hex cached property

hex: str

Get the hexadecimal hash of the object.

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.

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

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

get_args

get_args(context: DAGContext = None) -> list[str]

Generate the FFmpeg filter string for this filter node.

This method creates the filter string that will be used in the filter_complex argument of the FFmpeg command. The format follows FFmpeg's syntax where input labels are followed by the filter name and parameters, and then output labels.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context for resolving stream labels. If not provided, a new context will be built.	None

Returns:

Type	Description
list[str]	A list of strings that, when joined, form the filter string
list[str]	for this node in the filter_complex argument

Example

For a scale filter with width=1280 and height=720, this might return: ['[0:v]', 'scale=', 'width=1280:height=720', '[s0]']

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.

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
)

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
vfilter	Apply a custom video filter to this stream.
afilter	Apply a custom audio filter to this stream.
filter_multi_output	Apply a custom filter with multiple outputs to this stream.
label	Generate the FFmpeg label for this stream in filter graphs.
output	Output file URL
view	Visualize the stream.

Attributes:

Name	Type	Description
node	FilterNode | InputNode	Represents the node that the stream is connected to in the upstream direction.
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 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.

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

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)

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)

label

label(context: DAGContext = None) -> str

Generate the FFmpeg label for this stream in filter graphs.

This method creates the label string used to identify this stream in FFmpeg filter graphs. The format of the label depends on the stream's source (input file or filter) and type (video or audio).

For input streams, labels follow FFmpeg's stream specifier syntax: - Video streams: "0:v" (first input, video stream) - Audio streams: "0:a" (first input, audio stream) - AV streams: "0" (first input, all streams)

For filter outputs, labels use the filter's label: - Single output filters: "filterlabel" - Multi-output filters: "filterlabel#index"

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context for resolving node labels. If not provided, a new context will be built.	None

Returns:

Type	Description
str	A string label for this stream in FFmpeg filter syntax

Raises:

Type	Description
FFMpegValueError	If the stream has an unknown type or node type

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

Returns:

Type	Description
OutputStream	the output stream

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
repr	Get a string representation of this input node.
stream	Get a combined audio-video stream from this input file.
get_args	Generate the FFmpeg command-line arguments for this input file.
replace	Replace the old node in the graph with the new node.
view	Visualize the Node.

Attributes:

Name	Type	Description
filename	str	The path to the input media file
inputs	tuple[]	Input nodes have no inputs themselves (they are source nodes)
video	VideoStream	Get the video stream from this input file.
audio	AudioStream	Get the audio stream from this input file.
hex	str	Get the hexadecimal hash of the object.
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 input media file

inputs class-attribute instance-attribute

inputs: tuple[] = ()

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

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)

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)

hex cached property

hex: str

Get the hexadecimal hash of the object.

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.

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")

get_args

get_args(context: DAGContext = None) -> list[str]

Generate the FFmpeg command-line arguments for this input file.

This method creates the command-line arguments needed to specify this input file to FFmpeg, including any input-specific options.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context (not used for input nodes)	None

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For an input file "input.mp4" with options like seeking to 10 seconds: ['-ss', '10', '-i', 'input.mp4']

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.

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
repr	Get a string representation of this output node.
stream	Get an output stream representing this output file.
get_args	Generate the FFmpeg command-line arguments for this output file.
replace	Replace the old node in the graph with the new node.
view	Visualize the Node.

Attributes:

Name	Type	Description
filename	str	The path to the output media file
inputs	tuple[FilterableStream, ...]	The streams to be written to this output file
hex	str	Get the hexadecimal hash of the object.
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

inputs instance-attribute

inputs: tuple[FilterableStream, ...]

The streams to be written to this output file

hex cached property

hex: str

Get the hexadecimal hash of the object.

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.

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)

get_args

get_args(context: DAGContext = None) -> list[str]

Generate the FFmpeg command-line arguments for this output file.

This method creates the command-line arguments needed to specify this output file to FFmpeg, including stream mapping and output-specific options like codecs and formats.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context for resolving stream labels. If not provided, a new context will be built.	None

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For an output file "output.mp4" with H.264 video codec: ['-map', '[v0]', '-c:v', 'libx264', 'output.mp4']

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.

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)

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
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.
compile	Build command-line arguments for invoking FFmpeg.
compile_line	Build a command-line string for invoking FFmpeg.
run_async	Run FFmpeg asynchronously as a subprocess.
run	Run FFmpeg synchronously and wait for completion.
view	Visualize the stream.

Attributes:

Name	Type	Description
node	OutputNode	The output node this stream represents
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 instance-attribute

node: OutputNode

The output node this stream represents

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

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
) -> 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]	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()

compile

compile(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool = None,
    auto_fix: bool = True,
) -> 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	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

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,
    auto_fix: bool = True,
) -> 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	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

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'

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,
    auto_fix: bool = True,
) -> 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	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

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

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,
    auto_fix: bool = True,
) -> 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	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

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

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
repr	Get a string representation of this global node.
stream	Get a global stream representing this global node.
get_args	Generate the FFmpeg command-line arguments for these global options.
replace	Replace the old node in the graph with the new node.
view	Visualize the Node.

Attributes:

Name	Type	Description
inputs	tuple[OutputStream, ...]	The output streams this node applies to
hex	str	Get the hexadecimal hash of the object.
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.

inputs instance-attribute

inputs: tuple[OutputStream, ...]

The output streams this node applies to

hex cached property

hex: str

Get the hexadecimal hash of the object.

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.

repr

repr() -> str

Get a string representation of this global node.

Returns:

Type	Description
str	A space-separated string of the global options

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()

get_args

get_args(context: DAGContext = None) -> list[str]

Generate the FFmpeg command-line arguments for these global options.

This method creates the command-line arguments needed to specify global options to FFmpeg, such as -y for overwrite or -loglevel for controlling log output.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context (not used for global options)	None

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For global options like overwrite and quiet logging: ['-y', '-loglevel', 'quiet']

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.

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)

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
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.
compile	Build command-line arguments for invoking FFmpeg.
compile_line	Build a command-line string for invoking FFmpeg.
run_async	Run FFmpeg asynchronously as a subprocess.
run	Run FFmpeg synchronously and wait for completion.
view	Visualize the stream.

Attributes:

Name	Type	Description
node	GlobalNode	The global node this stream represents
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 instance-attribute

node: GlobalNode

The global node this stream represents

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

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
) -> 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]	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()

compile

compile(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool = None,
    auto_fix: bool = True,
) -> 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	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

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,
    auto_fix: bool = True,
) -> 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	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

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'

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,
    auto_fix: bool = True,
) -> 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	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

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

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,
    auto_fix: bool = True,
) -> 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	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

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

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.