Index

ffmpeg

This module provides methods to build and run FFmpeg with fine control commands.

Example

from ffmpeg import FFmpeg, InputFile, Map

ffmpeg = FFmpeg()

ffmpeg.output(Map(clip), path="output.mp4").run()

# or for async
await ffmpeg.output(Map(clip), path="output.mp4").run_async()

or multiple outputs
ffmpeg.output(Map(clip1), path="output1.mp4").output(Map(clip2), path="output2.mp4").run()

For simple usecase use export function it allows to export in one line, see example below

from ffmpeg import export, InputFile

clip = InputFile("input.mp4")
export(clip, path="output.mkv").run()

FFmpeg

__init__

__init__(path='ffmpeg', use_filter_file=False, filter_script_file='filters.txt')

This class provides methods to construct and execute FFmpeg commands. either Run or Compile the command to get the command list and run it manually.

Initialize the FFmpeg command builder.

Parameters:

Name	Type	Description	Default
path	str	Path to the ffmpeg executable.".	'ffmpeg'
use_filter_file	bool	Whether to use a filter script file,useful for very long filter graphs.	False
filter_script_file	str	Path to the filter script file if use_filter_file is True.	'filters.txt'

add_global_flag

add_global_flag(key, value=None)

Adds additional FFmpeg flags, avoiding duplicates

compile

compile(overwrite=True)

Generate the full FFmpeg command as a list of arguments.

This method collects and combines all the necessary parts of the FFmpeg command, including global flags, input definitions, filter graphs, mapping, output flags, and output file paths. It ensures that the command is constructed in the correct order and with all required options for execution.

Returns:

Type	Description
list[str]	The complete FFmpeg command as a list of arguments.

output

output(*maps, path, metadata=None, **kwargs)

Create output for the with streams mapped to it.

Parameters:

Name	Type	Description	Default
*maps	Map | BaseInput | StreamSpecifier	One or more Map objects or input nodes to include in the output.	()
path	str	The file path for the output media file.	required
metadata	Optional[dict[str, str]]	Metadata to be added to the output file.	None
**kwargs	dict[str, Any]	Additional keyword arguments representing output-specific	{}

reset

reset(reset_global=True)

Reset all compilation data added

run

run(progress_callback=None, progress_period=0.5, overwrite=True)

Run the FFmpeg command.

Parameters:

Name	Type	Description	Default
progress_callback	Optional[Callable[[dict], None]]	Function that can be used to track progress of the process running data can be mix of None and actual values	None
progress_period	float	Set period at which progress_callback is called	0.5
overwrite	bool	overwrite the output if already exists	True

run_async async

run_async(progress_callback=None, progress_period=0.5, overwrite=True)

Asynchronously run the FFmpeg command.

Parameters:

Name	Type	Description	Default
progress_callback	Optional[Callable[[dict], Coroutine[Any, Any, None]]]	Function that can be used to track progress of the process running data can be mix of None and actual values	None
progress_period	float	Set period at which progress_callback is called	0.5
overwrite	bool	overwrite the output if already exists	True

set_ffmpeg_path

set_ffmpeg_path(path)

Set the path to the ffmpeg executable.

export

export(*nodes, path, **kwargs)

Exports a clip by processing the given input nodes and saving the output to the specified path.

Parameters:

Name	Type	Description	Default
nodes	BaseInput | StreamSpecifier	One or more input nodes representing media sources.	()
path		The output file path where the exported clip will be saved.	required
kwargs	dict[str, Any]	flags for Output	{}

Returns:

Type	Description
FFmpeg	FFmpeg instance configured with the given inputs and output path.

filters

This module contains various FFmpeg filters as Python classes. The filters Always Inherit from BaseFilter class and Optionally TimelineEditingMixin if they support timeline editing.

AudioDelay

Bases: BaseFilter, TimelineEditingMixin

Add Delay in Audio using FFmpeg's adelay filter.

AudioFormat

Bases: BaseFilter

__init__

__init__(sample_rates=None, sample_fmts=None, channel_layouts=None)

Represents an audio format filter that sets audio parameters. At least one of sample_rates, sample_fmts, or channel_layouts must be provided.

Parameters:

Name	Type	Description	Default
sample_rates	Optional[list[str | float]]	Optional list of sample rates (e.g., ["44100", "48000"]).	None
sample_fmts	Optional[list[str | float]]	Optional list of sample formats (e.g., ["fltp", "s16"]).	None
channel_layouts	Optional[list[str | float]]	Optional list of channel layouts (e.g., ["stereo", "5.1"]).	None

AudioMix

Bases: BaseFilter

AudioMix using FFmpeg's amix filter.

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

Concat

Bases: BaseFilter

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

Format

Bases: BaseFilter

Represents a format filter that sets the pixel format of a video stream.

__init__

__init__(pixel_format, color_space=None, color_range=None, alpha_mode=None)

Convert the input video to one of the specified pixel formats. Libavfilter will try to pick one that is suitable as input to the next filter.

It accepts the following parameters:

Parameters:

Name	Type	Description	Default
pixel_format	str	A |-separated list of pixel format names, such as "pix_fmts=yuv420p|monow|rgb24".	required
color_space	Optional[str]	A |-separated list of color space names, such as "color_spaces=bt709|bt470bg|bt2020nc".	None
color_range	Optional[str]	A |-separated list of color range names, such as "color_ranges=tv|pc".	None
alpha_mode	Optional[str]	A |-separated list of color range names, such as "alpha_modes=straight|premultiplied".	None

HorizontalStack

Bases: BaseFilter

Represents an hstack filter that combines streams.

Overlay

Bases: BaseFilter, TimelineEditingMixin

Represents an overlay filter that combines two video streams.

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.

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

Subtitles

Bases: BaseFilter

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

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

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.

VerticalStack

Bases: BaseFilter

Represents an vstack filter that combines streams.

Volume

Bases: BaseFilter, TimelineEditingMixin

Volume Adjust using FFmpeg's volume filter.

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.

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.

utils

build_flags

build_flags(kwflags)

Generate flags for FFmpeg command from key-value pairs. if value is bool, convert to int (True=1, False=0) if value is None, skip the flag value part (y=None, ["-y"]).

Parameters:

Name	Type	Description	Default
kwflags	dict	Dictionary of key-value pairs representing flags.	required

Returns:

Name	Type	Description
list	list[str]	List of command-line flags for FFmpeg.

build_name_kvargs_format

build_name_kvargs_format(name, flags)

Build a formatted string for FFmpeg filter options. Automatically skips None values and converts bool int. Args: name (str): The name of the filter. flags (dict): A dictionary of key-value pairs representing filter options.

Example

build_name_kvargs_format("scale", {"w": 1280, "h": 720, "force_original_aspect_ratio": "decrease"})
returns "scale=w=1280:h=720:force_original_aspect_ratio=decrease"

parse_value

parse_value(value)

Convert FFmpeg progress values to appropriate data types.

exception

FFmpegException

Bases: Exception

Exception raised when an FFmpeg command fails.

Attributes:

Name	Type	Description
msg		The error message returned by FFmpeg.
return_code		The process return code from FFmpeg.

__init__

__init__(msg, return_code)

Initialize FFmpegException.

Parameters:

Name	Type	Description	Default
msg	str	Error message from FFmpeg.	required
return_code	int	Return code from FFmpeg process.	required

FFprobeException

Bases: FFmpegException

Exception raised when an FFprobe command fails.

Inherits from FFmpegException and is specific to FFprobe failures.

Attributes:

Name	Type	Description
msg	str	The error message returned by FFprobe.
return_code	int	The process return code from FFprobe.

__init__

__init__(msg, return_code)

Initialize FFprobeException.

Parameters:

Name	Type	Description	Default
msg	str	Error message from FFprobe.	required
return_code	int	Return code from FFprobe process.	required

ffplay

Use FFplay through easy to use function

ffplay

ffplay

ffplay(file_path, width=None, height=None, fullscreen=False, disable_audio=False, disable_video=False, disable_subtitles=False, seek_position=None, duration=None, seek_by_bytes=False, seek_interval=None, nodisp=False, noborder=False, alwaysontop=False, volume=None, force_format=None, window_title=None, left=None, top=None, loop=None, showmode=None, video_filter=None, audio_filter=None, autoexit=False, fbuf=False, sync=None, fast=False, stats=False, drp=False, fflags=None, vf=None, af=None, framedrop=False)

Run ffplay to play the specified media file with customizable options.

ffprobe

Use FFprobe through easy to use function or use flags to get specific data

ffprobe

ffprobe

ffprobe(file_path, options=None)

Run ffprobe with the given options on the specified file.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the media file.	required
options	Optional[Iterable[str]]	set ffprobe options (default extracts streams and format).	None

Returns:

Type	Description
Any	Parsed JSON dictionary output.

math

Variety of math and logic fuctions for ffmpeg evaluation during runtime.

E module-attribute

E = 'E'

exp(1) (Euler’s number), approximately 2.718

PHI module-attribute

PHI = 'PHI'

golden ratio (1+sqrt(5))/2, approximately 1.618

PI module-attribute

PI = 'PI'

Area of the unit disc, approximately 3.14

f_abs

f_abs(x)

Compute absolute value of x.

f_acos

f_acos(x)

Compute arccosine of x.

f_asin

f_asin(x)

Compute arcsine of x.

f_atan

f_atan(x)

Compute arctangent of x.

f_atan2

f_atan2(y, x)

Compute principal value of the arc tangent of y/x.

f_between

f_between(x, min, max)

Return 1 if x is greater than or equal to min and lesser than or equal to max, 0 otherwise.

f_bitand

f_bitand(x, y)

Compute bitwise and/or operation on x and y.

f_bitor

f_bitor(x, y)

The results of the evaluation of x and y are converted to integers before executing the bitwise operation. Note that both the conversion to integer and the conversion back to floating point can lose precision. Beware of unexpected results for large numbers (usually 2^53 and larger).

f_ceil

f_ceil(expr)

Round the value of expression expr upwards to the nearest integer. For example, "ceil(1.5)" is "2.0".

f_clip

f_clip(x, min, max)

Return the value of x clipped between min and max.

f_cos

f_cos(x)

Compute cosine of x.

f_cosh

f_cosh(x)

Compute hyperbolic cosine of x.

f_eq

f_eq(x, y)

Return 1 if x and y are equivalent, 0 otherwise.

f_exp

f_exp(x)

Compute exponential of x (with base e, the Euler’s number).

f_floor

f_floor(expr)

Round the value of expression expr downwards to the nearest integer. For example, "floor(-1.5)" is "-2.0".

f_gauss

f_gauss(x)

Compute Gauss function of x, corresponding to exp(-xx/2) / sqrt(2PI).

f_gcd

f_gcd(x, y)

Return f_the greatest common divisor of x and y. If both x and y are 0 or either or both are less than zero then behavior is undefined.

f_gt

f_gt(x, y)

Return 1 if x is greater than y, 0 otherwise.

f_gte

f_gte(x, y)

Return 1 if x is greater than or equal to y, 0 otherwise.

f_hypot

f_hypot(x, y)

This function is similar to the C function with the same name; it returns "sqrt(xx + yy)", the length of the hypotenuse of a right triangle with sides of length x and y, or the distance of the point (x, y) from the origin.:

f_if

f_if(x, y, z)

Evaluate x, and if the result is non-zero return the evaluation result of y, otherwise the evaluation result of z.

f_ifnot

f_ifnot(x, y, z)

Evaluate x, and if the result is zero return the evaluation result of y, otherwise the evaluation result of z.

f_isinf

f_isinf(x)

Return 1.0 if x is +/-INFINITY, 0.0 otherwise.

f_isnan

f_isnan(x)

Return 1.0 if x is NAN, 0.0 otherwise.

f_ld

f_ld(idx)

Load the value of the internal variable with index idx, which was previously stored with st(idx, expr). The function returns the loaded value.

f_lerp

f_lerp(x, y, z)

Return linear interpolation between x and y by amount of z.

f_log

f_log(x)

Compute natural logarithm of x.

f_lt

f_lt(x, y)

Return 1 if x is lesser than y, 0 otherwise.

f_lte

f_lte(x, y)

Return 1 if x is lesser than or equal to y, 0 otherwise.

f_max

f_max(x, y)

Return the maximum between x and y.

f_min

f_min(x, y)

Return the minimum between x and y.

f_mod

f_mod(x, y)

Compute the remainder of division of x by y.

f_not

f_not(expr)

Return 1.0 if expr is zero, 0.0 otherwise.

f_pow

f_pow(x, y)

Compute the power of x elevated y, it is equivalent to "(x)^(y)".

f_print

f_print(t, l)

Pf_rint the value of expression t with loglevel l. If l is not specified then a default log level is used. Return the value of the expression printed.:

f_random

f_random(idx)

Return a pseudo random value between 0.0 and 1.0. idx is the index of the internal variable used to save the seed/state, which can be previously stored with st(idx). To initialize the seed, you need to store the seed value as a 64-bit unsigned integer in the internal variable with index idx. For example, to store the seed with value 42 in the internal variable with index 0 and print a few random values:

f_randomi

f_randomi(idx, min, max)

Return a pseudo random value in the interval between min and max. idx is the index of the internal variable which will be used to save the seed/state, which can be previously stored with st(idx). To initialize the seed, you need to store the seed value as a 64-bit unsigned integer in the internal variable with index idx.

f_root

f_root(expr, max)

Find an input value for which the function represented by expr with argument ld(0) is 0 in the interval 0..max.

The expression in expr must denote a continuous function or the result is undefif_ned. ld(0) is used to represent the function input value, which means that the given expression will be evaluated multiple times with various input values that the expression can access through ld(0). When the expression evaluates to 0 then the corresponding input value will be returned.

f_round

f_round(expr)

Round the value of expression expr to the nearest integer. For example, "round(1.5)" is "2.0".

f_sgn

f_sgn(x)

Compute sign of x.

f_sin

f_sin(x)

Compute sine of x.

f_sinh

f_sinh(x)

Compute hyperbolic sine of x.

f_sqrt

f_sqrt(expr)

Compute the square root of expr. This is equivalent to (expr)^.5

f_squish

f_squish(x)

Compute expression 1/(1 + exp(4*x)).

f_st

f_st(idx, expr)

Store the value of the expression expr in an internal variable. idx specifies the index of the variable where to store the value, and it is a value ranging from 0 to 9. The function returns the value stored in the internal variable.

The stored value can be retrieved with ld(var).

Note: variables are currently not shared between expressions.

f_tan

f_tan(x)

Compute tangent of x.

f_tanh

f_tanh(x)

Compute hyperbolic tangent of x.

f_taylor

f_taylor(expr, x, idx)

Evaluate a Taylor series at x, given an expression representing the ld(idx)-th derivative of a function at 0.

When the series does not converge the result is undefined.

ld(idx) is used to represent the derivative order in expr, which means that the given expression will be evaluated multiple times with various input values that the expression can access through ld(idx). If idx is not specified then 0 is assumed.

Note, when you have the derivatives at y instead of 0, taylor(expr, x-y) can be used.

f_time

f_time()

Return the current (wallclock) time in seconds.

f_trunc

f_trunc(expr)

Round the value of expression expr towards zero to the nearest integer. For example, trunc(-1.5) is -1.0

f_while

f_while(cond, expr)

Evaluate expression expr while the expression cond is non-zero, and returns the value of the last expr evaluation, or NAN if cond was always false. The following constants are available: