DAG node definitions for FFmpeg filter graphs.
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. |
GlobalStream |
A stream representing a set of global FFmpeg options. |
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. |
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. |
class-attribute
instance-attribute
¶
input_typings: tuple[StreamType, ...] = ()
The expected types (audio/video) for each input stream
class-attribute
instance-attribute
¶
inputs: tuple[FilterableStream, ...] = ()
The input streams that this filter processes
class-attribute
instance-attribute
¶
kwargs: FrozenDict[
str, str | int | float | bool | LazyValue
] = FrozenDict({})
Represents the keyword arguments of the node.
property
¶
max_depth: int
Get the maximum depth of the node.
Returns:
| Type | Description |
|---|---|
int
|
The maximum depth of the node. |
instance-attribute
¶
name: str
The name of the filter as used in FFmpeg (e.g., 'scale', 'overlay', 'amix')
class-attribute
instance-attribute
¶
output_typings: tuple[StreamType, ...] = ()
The types (audio/video) of each output stream this filter produces
property
¶
upstream_nodes: set[Node]
Get all upstream nodes of the node.
Returns:
| Type | Description |
|---|---|
set[Node]
|
The upstream nodes of the node. |
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 |
repr() -> str
Get a string representation of this filter node.
Returns:
| Type | Description |
|---|---|
str
|
The name of the filter |
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(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. |
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. |
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
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.
class-attribute
instance-attribute
¶
optional: bool = False
Represents whether the stream is optional.
Note
See Also: Advanced options
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(
*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(
*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(
*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(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. |
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. |
instance-attribute
¶
inputs: tuple[OutputStream, ...]
The output streams this node applies to
class-attribute
instance-attribute
¶
kwargs: FrozenDict[
str, str | int | float | bool | LazyValue
] = FrozenDict({})
Represents the keyword arguments of the node.
property
¶
max_depth: int
Get the maximum depth of the node.
Returns:
| Type | Description |
|---|---|
int
|
The maximum depth of the node. |
property
¶
upstream_nodes: set[Node]
Get all upstream nodes of the node.
Returns:
| Type | Description |
|---|---|
set[Node]
|
The upstream nodes of the node. |
repr() -> str
Get the representation of the node.
Returns:
| Type | Description |
|---|---|
str
|
The representation of the node. |
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(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. |
dataclass
¶
GlobalStream(
*,
node: GlobalNode,
index: int | None = None,
optional: bool = False
)
Bases: Stream, GlobalRunable
A stream representing a set of global FFmpeg options.
GlobalStream wraps a GlobalNode and provides additional functionality, particularly the ability to add more global options or execute the FFmpeg command. This class is typically the final step in the FFmpeg command construction process.
Methods:
| Name | Description |
|---|---|
compile |
Build command-line arguments for invoking FFmpeg. |
compile_line |
Build a command-line string for invoking FFmpeg. |
global_args |
Set global options. |
merge_outputs |
Merge multiple output streams into a single command. |
overwrite_output |
Set the FFmpeg command to overwrite output files without asking. |
run |
Run FFmpeg synchronously and wait for completion. |
run_async |
Run FFmpeg asynchronously as a subprocess. |
view |
Visualize the stream. |
Attributes:
| Name | Type | Description |
|---|---|---|
hex |
str
|
Get the hexadecimal hash of the object. |
index |
int | None
|
Represents the index of the stream in the node's output streams. |
node |
GlobalNode
|
The global node this stream represents |
optional |
bool
|
Represents whether the stream is optional. |
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
class-attribute
instance-attribute
¶
optional: bool = False
Represents whether the stream is optional.
Note
See Also: Advanced options
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(
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(
*,
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(*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() -> 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(
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(
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(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. |
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. |
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)
class-attribute
instance-attribute
¶
inputs: tuple[] = ()
Input nodes have no inputs themselves (they are source nodes)
class-attribute
instance-attribute
¶
kwargs: FrozenDict[
str, str | int | float | bool | LazyValue
] = FrozenDict({})
Represents the keyword arguments of the node.
property
¶
max_depth: int
Get the maximum depth of the node.
Returns:
| Type | Description |
|---|---|
int
|
The maximum depth of the node. |
property
¶
upstream_nodes: set[Node]
Get all upstream nodes of the node.
Returns:
| Type | Description |
|---|---|
set[Node]
|
The upstream nodes of the node. |
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)
repr() -> str
Get a string representation of this input node.
Returns:
| Type | Description |
|---|---|
str
|
The basename of the input file |
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(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. |
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. |
instance-attribute
¶
inputs: tuple[FilterableStream, ...]
The streams to be written to this output file
class-attribute
instance-attribute
¶
kwargs: FrozenDict[
str, str | int | float | bool | LazyValue
] = FrozenDict({})
Represents the keyword arguments of the node.
property
¶
max_depth: int
Get the maximum depth of the node.
Returns:
| Type | Description |
|---|---|
int
|
The maximum depth of the node. |
property
¶
upstream_nodes: set[Node]
Get all upstream nodes of the node.
Returns:
| Type | Description |
|---|---|
set[Node]
|
The upstream nodes of the node. |
repr() -> str
Get a string representation of this output node.
Returns:
| Type | Description |
|---|---|
str
|
The basename of the output file |
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(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. |
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. |
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
class-attribute
instance-attribute
¶
optional: bool = False
Represents whether the stream is optional.
Note
See Also: Advanced options
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(
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(
*,
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(*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() -> 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(
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(
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(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. |