Filters

apply

apply(filter_obj, *parent)

Apply a filter input streams.

This function connects the given input nodes (either BaseInput or StreamSpecifier) to a filter node and returns a single output stream from the filter.

Parameters:

Name	Type	Description	Default
filter_obj	BaseFilter	The filter node to apply.	required
*parent	BaseInput | StreamSpecifier	Input nodes to connect to the filter.	()

Returns:

Type	Description
StreamSpecifier	The resulting single output stream from the filter.

apply2

apply2(filter_obj, *parent)

Apply a filter input streams.

This function connects the given input nodes (either BaseInput or StreamSpecifier) to a filter node and returns a list of all output streams from the filter.

Parameters:

Name	Type	Description	Default
filter_obj	BaseFilter	The filter node to apply.	required
*parent	BaseInput | StreamSpecifier	Input nodes to connect to the filter.	()

Returns:

Type	Description
list[StreamSpecifier]	A list of output streams from the filter.

Text

Bases: BaseFilter, TimelineEditingMixin

Draw a text string or text from a specified file on top of a video, using the libfreetype library.

f_expression staticmethod

f_expression(expr)

Returns an FFmpeg drawtext expansion string that evaluate expression.

f_frame_num staticmethod

f_frame_num()

Returns an FFmpeg drawtext expansion string that expands to the local time with given strftime format.

f_gmtime staticmethod

f_gmtime(fmt='%a %b %d %Y')

Returns an FFmpeg drawtext expansion string that expands to the local time with given strftime format.

f_localtime staticmethod

f_localtime(fmt='%a %b %d %Y')

Returns an FFmpeg drawtext expansion string that expands to the local time with given strftime format.

f_pts staticmethod

f_pts(fmt='flt', offset=None, extra=None)

Returns an FFmpeg drawtext expansion string that expands to the PTS (presentation timestamp).

Parameters:

Name	Type	Description	Default
fmt	Literal['flt', 'hms', 'gmtime', 'localtime']	Format of the timestamp. - "flt" -> seconds with microsecond precision (default) - "hms" -> [-]HH:MM:SS.mmm - "gmtime" -> UTC timestamp (strftime supported if extra is given) - "localtime" -> local timestamp (strftime supported if extra is given)	'flt'
offset	Optional[str]	Offset to add to timestamp (e.g., "10" for +10s).	None
extra	Optional[str]	Optional third argument: - for "hms" format: "24HH" - for gmtime/localtime: strftime format string.	None

Examples:

f_pts() -> "%{pts}" f_pts("hms") -> "%{pts:hms}" f_pts("hms", "5") -> "%{pts:hms:5}" f_pts("localtime", "0", "%H\:%M\:%S") -> "%{pts:localtime:0:%H\:%M\:%S}"

Box

Bases: BaseFilter, TimelineEditingMixin

Split

Bases: BaseFilter

XFade

Bases: BaseFilter

__init__

__init__(name, offset=0, duration=1, expression=None)

Combine two videos with transition.

Note

Requires same size and fps and aspect ratio.

Subtitles

Bases: BaseFilter

Draw subtitles on top of input video using the libass library.

Overlay

Bases: BaseFilter, TimelineEditingMixin

Represents an overlay filter that combines two video streams.

Concat

Bases: BaseFilter

Represents a concat filter that joins multiple segments. See: https://ffmpeg.org/ffmpeg-filters.html#concat

Scale

Bases: BaseFilter

Represents the FFmpeg scale filter.

Parameters:

Name	Type	Description	Default
width	float	The width of the output video.	required
height	float	The height of the output video.	required

reset_sar

reset_sar(enable=True)

Reset the sample aspect ratio.

Parameters:

Name	Type	Description	Default
enable	bool	Whether to enable resetting SAR.	True

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_aspect_ratio_mode

set_aspect_ratio_mode(mode)

Set the aspect ratio mode.

Parameters:

Name	Type	Description	Default
mode	AspectRatioMode	The aspect ratio mode.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_eval

set_eval(mode)

Set the evaluation mode. Useful for dynamic scaling.

Parameters:

Name	Type	Description	Default
mode	EvalMode	The evaluation mode.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_force_divisible_by

set_force_divisible_by(n)

Set the force divisible by value.

Parameters:

Name	Type	Description	Default
n	int	The value to force divisibility by.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_in_chroma_location

set_in_chroma_location(loc)

Set the input chroma location.

Parameters:

Name	Type	Description	Default
loc	IOChromaLocation	The input chroma location.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_in_color_matrix

set_in_color_matrix(matrix)

Set the input color matrix.

Parameters:

Name	Type	Description	Default
matrix	ColorMatrix	The input color matrix.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_in_primaries

set_in_primaries(primaries)

Set the input color primaries.

Parameters:

Name	Type	Description	Default
primaries	IOPrimaries	The input color primaries.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_in_range

set_in_range(rng)

Set the input range.

Parameters:

Name	Type	Description	Default
rng	IORange	The input range.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_intent

set_intent(intent)

Set the color intent.

Parameters:

Name	Type	Description	Default
intent	Intent	The color intent.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_interlacing

set_interlacing(mode)

Set the interlacing mode.

Parameters:

Name	Type	Description	Default
mode	InterlacingMode	The interlacing mode.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_out_chroma_location

set_out_chroma_location(loc)

Set the output chroma location.

Parameters:

Name	Type	Description	Default
loc	IOChromaLocation	The output chroma location.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_out_color_matrix

set_out_color_matrix(matrix)

Set the output color matrix.

Parameters:

Name	Type	Description	Default
matrix	ColorMatrix	The output color matrix.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_out_primaries

set_out_primaries(primaries)

Set the output color primaries.

Parameters:

Name	Type	Description	Default
primaries	IOPrimaries	The output color primaries.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

set_out_range

set_out_range(rng)

Set the output range.

Parameters:

Name	Type	Description	Default
rng	IORange	The output range.	required

Returns:

Name	Type	Description
Self	Self	The current Scale instance.

SetTimeBase

Bases: BaseFilter, TimelineEditingMixin

SetSampleAspectRatio

Bases: BaseFilter

__init__

__init__(expression='1')

Set the Sample (or Pixel) Aspect Ratio (SAR or PAR) of the input video to the specified value.

The expression can be a float (e.g., 1.0, 1.3333) or a string representing a ratio (e.g., "4:3", "16:9").

TimelineEditingMixin

Mixin providing timeline-based activation control for FFmpeg filter graphs.

This mixin allows enabling filters conditionally based on the video timestamp, using FFmpeg's enable expression mechanism with between, gte, and lte.

Attributes:

Name	Type	Description
flags	dict	Dictionary storing FFmpeg filter options, such as enable expressions.

enable_after

enable_after(t)

Enable the filter only after the given timestamp.

Parameters:

Name	Type	Description	Default
t	float	Time (in seconds) after which the filter is enabled.	required

Returns:

Name	Type	Description
TimelineEditingMixin	Self	The current instance with the updated enable flag.

enable_before

enable_before(t)

Enable the filter only before the given timestamp.

Parameters:

Name	Type	Description	Default
t	float	Time (in seconds) before which the filter is enabled.	required

Returns:

Name	Type	Description
TimelineEditingMixin	Self	The current instance with the updated enable flag.

enable_between

enable_between(start, end)

Enable the filter only between the given start and end times.

Parameters:

Name	Type	Description	Default
start	float	Start time (in seconds).	required
end	float	End time (in seconds).	required

Returns:

Name	Type	Description
TimelineEditingMixin	Self	The current instance with the updated enable flag.

BaseFilter

Base class for all FFmpeg filters.

escape_arguments

escape_arguments(text)

Escapes all characters that require escaping in FFmpeg filter arguments.

Returns:

Type	Description
Any | str	None if text was None otherwise new str with escaped chars