Core functions for creating and manipulating FFmpeg filter graphs.
This module defines the fundamental functions for building FFmpeg filter graphs in typed-ffmpeg. It provides functions to create custom filters, handle multi-output filters, and merge output streams. These functions serve as the foundation for the more specialized filters defined in the filters module.
Functions:
| Name | Description |
|---|---|
input |
Input file URL (ffmpeg |
output |
Output file URL |
merge_outputs |
Merge multiple output streams into a single command execution. |
vfilter |
Apply a custom video filter that has a single video output. |
afilter |
Apply a custom audio filter that has a single audio output. |
filter_multi_output |
Apply a custom filter that produces multiple output streams. |
input(
filename: str | Path,
*,
f: String = None,
c: String = None,
codec: String = None,
t: Time = None,
to: Time = None,
ss: Time = None,
sseof: Time = None,
seek_timestamp: Int = None,
accurate_seek: Boolean = None,
isync: Int = None,
itsoffset: Time = None,
itsscale: Double = None,
re: Boolean = None,
readrate: Float = None,
readrate_initial_burst: Double = None,
bitexact: Boolean = None,
tag: String = None,
reinit_filter: Int = None,
dump_attachment: String = None,
stream_loop: Int = None,
discard: String = None,
thread_queue_size: Int = None,
find_stream_info: Boolean = None,
r: String = None,
s: String = None,
pix_fmt: String = None,
display_rotation: Double = None,
display_hflip: Boolean = None,
display_vflip: Boolean = None,
vn: Boolean = None,
vcodec: String = None,
vtag: String = None,
hwaccel: String = None,
hwaccel_device: String = None,
hwaccel_output_format: String = None,
autorotate: Boolean = None,
ar: Int = None,
ac: Int = None,
an: Boolean = None,
acodec: String = None,
sample_fmt: String = None,
channel_layout: String = None,
ch_layout: String = None,
guess_layout_max: Int = None,
sn: Boolean = None,
scodec: String = None,
fix_sub_duration: Boolean = None,
canvas_size: String = None,
bsf: String = None,
dcodec: String = None,
dn: Boolean = None,
top: Int = None,
extra_options: dict[str, Any] = None
) -> AVStream
Input file URL (ffmpeg -i option)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str | Path
|
Input file URL |
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
|
t
|
Time
|
stop transcoding after specified duration |
None
|
to
|
Time
|
stop transcoding after specified time is reached |
None
|
ss
|
Time
|
start transcoding at specified time |
None
|
sseof
|
Time
|
set the start time offset relative to EOF |
None
|
seek_timestamp
|
Int
|
enable/disable seeking by timestamp with -ss |
None
|
accurate_seek
|
Boolean
|
enable/disable accurate seeking with -ss |
None
|
isync
|
Int
|
Indicate the input index for sync reference |
None
|
itsoffset
|
Time
|
set the input ts offset |
None
|
itsscale
|
Double
|
set the input ts scale |
None
|
re
|
Boolean
|
read input at native frame rate; equivalent to -readrate 1 |
None
|
readrate
|
Float
|
read input at specified rate |
None
|
readrate_initial_burst
|
Double
|
The initial amount of input to burst read before imposing any readrate |
None
|
bitexact
|
Boolean
|
bitexact mode |
None
|
tag
|
String
|
force codec tag/fourcc |
None
|
reinit_filter
|
Int
|
reinit filtergraph on input parameter changes |
None
|
dump_attachment
|
String
|
extract an attachment into a file |
None
|
stream_loop
|
Int
|
set number of times input stream shall be looped |
None
|
discard
|
String
|
discard |
None
|
thread_queue_size
|
Int
|
set the maximum number of queued packets from the demuxer |
None
|
find_stream_info
|
Boolean
|
read and decode the streams to fill missing information with heuristics |
None
|
r
|
String
|
override input framerate/convert to given output framerate (Hz value, fraction or abbreviation) |
None
|
s
|
String
|
set frame size (WxH or abbreviation) |
None
|
pix_fmt
|
String
|
set pixel format |
None
|
display_rotation
|
Double
|
set pure counter-clockwise rotation in degrees for stream(s) |
None
|
display_hflip
|
Boolean
|
set display horizontal flip for stream(s) (overrides any display rotation if it is not set) |
None
|
display_vflip
|
Boolean
|
set display vertical flip for stream(s) (overrides any display rotation if it is not set) |
None
|
vn
|
Boolean
|
disable video |
None
|
vcodec
|
String
|
alias for -c:v (select encoder/decoder for video streams) |
None
|
vtag
|
String
|
force video tag/fourcc |
None
|
hwaccel
|
String
|
use HW accelerated decoding |
None
|
hwaccel_device
|
String
|
select a device for HW acceleration |
None
|
hwaccel_output_format
|
String
|
select output format used with HW accelerated decoding |
None
|
autorotate
|
Boolean
|
automatically insert correct rotate filters |
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
|
sample_fmt
|
String
|
set sample format |
None
|
channel_layout
|
String
|
set channel layout |
None
|
ch_layout
|
String
|
set channel layout |
None
|
guess_layout_max
|
Int
|
set the maximum number of channels to try to guess the channel layout |
None
|
sn
|
Boolean
|
disable subtitle |
None
|
scodec
|
String
|
alias for -c:s (select encoder/decoder for subtitle streams) |
None
|
fix_sub_duration
|
Boolean
|
fix subtitles duration |
None
|
canvas_size
|
String
|
set canvas size (WxH or abbreviation) |
None
|
bsf
|
String
|
A comma-separated list of bitstream filters |
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]
|
ffmpeg's input file options |
None
|
Returns:
| Type | Description |
|---|---|
AVStream
|
Input stream |
Examples:
>>> input('input.mp4')
<AVStream:input.mp4:0>
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 |
merge_outputs(*streams: OutputStream) -> GlobalStream
Merge multiple output streams into a single command execution.
This function combines multiple output streams that need to be executed together in a single FFmpeg command. This is useful when you need to generate multiple outputs from the same input(s) in a single pass, which is more efficient than running separate commands.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*streams
|
OutputStream
|
Two or more output streams to be merged together |
()
|
Returns:
| Type | Description |
|---|---|
GlobalStream
|
A global stream representing all merged outputs |
Example
input_video = ffmpeg.input("input.mp4")
output1 = input_video.output("output1.mp4", vcodec="libx264")
output2 = input_video.output("output2.mp4", vcodec="libx265")
merged = ffmpeg.merge_outputs(output1, output2)
merged.run() # Executes both outputs in a single FFmpeg command
vfilter(
*streams: FilterableStream,
name: str,
input_typings: tuple[StreamType, ...] = (video,),
**kwargs: Any
) -> VideoStream
Apply a custom video filter that has a single video output.
This function allows you to use any FFmpeg video filter that isn't explicitly implemented in typed-ffmpeg. It creates a FilterNode with a video output type and returns the resulting video stream.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*streams
|
FilterableStream
|
One or more input streams to apply the filter to |
()
|
name
|
str
|
The FFmpeg filter name (e.g., 'hflip', 'scale', etc.) |
required |
input_typings
|
tuple[StreamType, ...]
|
The expected types of the input streams (defaults to video) |
(video,)
|
**kwargs
|
Any
|
Filter-specific parameters as keyword arguments |
{}
|
Returns:
| Type | Description |
|---|---|
VideoStream
|
A VideoStream representing the filtered output |
Example
# Apply a custom deflicker filter (if not directly implemented)
filtered = ffmpeg.vfilter(stream, name="deflicker", mode="pm", size=10)
Note
This function is for custom filters not implemented in typed-ffmpeg. Use the built-in filters from the filters module when available.
afilter(
*streams: FilterableStream,
name: str,
input_typings: tuple[StreamType, ...] = (audio,),
**kwargs: Any
) -> AudioStream
Apply a custom audio filter that has a single audio output.
This function allows you to use any FFmpeg audio filter that isn't explicitly implemented in typed-ffmpeg. It creates a FilterNode with an audio output type and returns the resulting audio stream.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*streams
|
FilterableStream
|
One or more input streams to apply the filter to |
()
|
name
|
str
|
The FFmpeg filter name (e.g., 'equalizer', 'dynaudnorm', etc.) |
required |
input_typings
|
tuple[StreamType, ...]
|
The expected types of the input streams (defaults to audio) |
(audio,)
|
**kwargs
|
Any
|
Filter-specific parameters as keyword arguments |
{}
|
Returns:
| Type | Description |
|---|---|
AudioStream
|
An AudioStream representing the filtered output |
Example
# Apply a custom audio compressor filter (if not directly implemented)
compressed = ffmpeg.afilter(stream, name="acompressor", threshold=0.1, ratio=2)
Note
This function is for custom filters not implemented in typed-ffmpeg. Use the built-in filters from the filters module when available.
filter_multi_output(
*streams: FilterableStream,
name: str,
input_typings: tuple[StreamType, ...] = (),
output_tyings: tuple[StreamType, ...] = (),
**kwargs: Any
) -> FilterNode
Apply a custom filter that produces multiple output streams.
This function allows you to use any FFmpeg filter that generates multiple outputs (like split, asplit, or complex filters). Unlike vfilter and afilter which return a single stream, this returns a FilterNode that you can extract specific outputs from.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*streams
|
FilterableStream
|
One or more input streams to apply the filter to |
()
|
name
|
str
|
The FFmpeg filter name (e.g., 'split', 'channelsplit', etc.) |
required |
input_typings
|
tuple[StreamType, ...]
|
The expected types of the input streams |
()
|
output_tyings
|
tuple[StreamType, ...]
|
The expected types of each output stream |
()
|
**kwargs
|
Any
|
Filter-specific parameters as keyword arguments |
{}
|
Returns:
| Type | Description |
|---|---|
FilterNode
|
A FilterNode object that you can extract specific outputs from |
FilterNode
|
using methods like .video(0), .audio(1), etc. |
Example
# Split a video into two identical streams
split_node = ffmpeg.filter_multi_output(
stream, name="split", output_tyings=(StreamType.video, StreamType.video)
)
stream1 = split_node.video(0)
stream2 = split_node.video(1)
Note
This function is for custom filters not implemented in typed-ffmpeg. Use the built-in filters from the filters module when available.