Api
This module provides methods to build and run FFmpeg with fine control commands.
For simple usecase use export
FFmpeg()
FFmpeg Command Builder
add_global_flag(*flags)
Adds additional FFmpeg flags
build_filter(last_node)
Builds the final FFmpeg chains
compile(overwrite=True)
Generate the command This fuction gather and combine all of the different part of the command.
generate_inlink_name(parent)
Get different types of links that ffmpeg uses with different types of Object
generate_link_name(i, j, stream_char='')
make names for link names
Note: stream_char should not be use in outlink name generation
handle_input_export(node)
Check if Output is Input without any filter applied
output(*maps, path, **kvflags)
Create output for the command with map and output specific flags and the path for the output
reset()
Reset all compilation data added
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
|
export(*nodes, path)
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
|
str
|
The output file path where the exported clip will be saved. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
FFmpeg |
FFmpeg
|
An FFmpeg instance configured with the given inputs and output path. |
BaseFilter(filter_name)
Base class for all FFmpeg filters.
Overlay(overlay_input, x, y)
Bases: BaseFilter, TimelineEditingMixin
Represents an overlay filter that combines two video streams.
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 |
The current instance with the updated |
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 |
The current instance with the updated |
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 |
The current instance with the updated |
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(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 |
The current instance with the updated |
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 |
The current instance with the updated |
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 |
The current instance with the updated |
XFade(name, offset=0, duration=1, expression=None)
Bases: BaseFilter
Combine two videos with transition.
Note
Requires same size and fps and aspect ratio.
apply(node, *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 |
|---|---|---|---|
node
|
BaseFilter
|
The filter node to apply. |
required |
*parent
|
BaseInput | StreamSpecifier
|
Input nodes to connect to the filter. |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
StreamSpecifier |
StreamSpecifier
|
The resulting single output stream from the filter. |
apply2(node, *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 |
|---|---|---|---|
node
|
BaseFilter
|
The filter node to apply. |
required |
*parent
|
BaseInput | StreamSpecifier
|
Input nodes to connect to the filter. |
()
|
Returns:
| Type | Description |
|---|---|
list[StreamSpecifier]
|
list[StreamSpecifier]: A list of output streams from the filter. |
build_flags(kwflags)
Generate flags
parse_value(value)
Convert FFmpeg progress values to appropriate data types.
FFmpegException(msg, return_code)
Bases: Exception
Exception raised when an FFmpeg command fails.
Attributes:
| Name | Type | Description |
|---|---|---|
msg |
str
|
The error message returned by FFmpeg. |
return_code |
int
|
The process return code from FFmpeg. |
Initialize FFmpegException.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
msg
|
str
|
Error message from FFmpeg. |
required |
return_code
|
int
|
Return code from FFmpeg process. |
required |
FFprobeException(msg, return_code)
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. |
Initialize FFprobeException.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
msg
|
str
|
Error message from FFprobe. |
required |
return_code
|
int
|
Return code from FFprobe process. |
required |
Use FFplay through easy to use function
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.
Use FFprobe through easy to use function or use flags to get specific data
ffprobe(file_path, options=None)
Run ffprobe with the given options on the specified file. :param file_path: Path to the media file. :param options: set ffprobe options (default extracts streams and format). :return: Parsed JSON output or None if an error occurs.
Variety of math and logic fuctions for ffmpeg evaluation during runtime.
f_abs(x)
Compute absolute value of x.
f_acos(x)
Compute arccosine of x.
f_asin(x)
Compute arcsine of x.
f_atan(x)
Compute arctangent of x.
f_atan2(y, x)
Compute principal value of the arc tangent of y/x.
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(x, y)
Compute bitwise and/or operation on x and y.
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(expr)
Round the value of expression expr upwards to the nearest integer. For example, "ceil(1.5)" is "2.0".
f_clip(x, min, max)
Return the value of x clipped between min and max.
f_cos(x)
Compute cosine of x.
f_cosh(x)
Compute hyperbolic cosine of x.
f_eq(x, y)
Return 1 if x and y are equivalent, 0 otherwise.
f_exp(x)
Compute exponential of x (with base e, the Euler’s number).
f_floor(expr)
Round the value of expression expr downwards to the nearest integer. For example, "floor(-1.5)" is "-2.0".
f_gauss(x)
Compute Gauss function of x, corresponding to exp(-xx/2) / sqrt(2PI).
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(x, y)
Return 1 if x is greater than y, 0 otherwise.
f_gte(x, y)
Return 1 if x is greater than or equal to y, 0 otherwise.
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(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(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(x)
Return 1.0 if x is +/-INFINITY, 0.0 otherwise.
f_isnan(x)
Return 1.0 if x is NAN, 0.0 otherwise.
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(x, y, z)
Return linear interpolation between x and y by amount of z.
f_log(x)
Compute natural logarithm of x.
f_lt(x, y)
Return 1 if x is lesser than y, 0 otherwise.
f_lte(x, y)
Return 1 if x is lesser than or equal to y, 0 otherwise.
f_max(x, y)
Return the maximum between x and y.
f_min(x, y)
Return the minimum between x and y.
f_mod(x, y)
Compute the remainder of division of x by y.
f_not(expr)
Return 1.0 if expr is zero, 0.0 otherwise.
f_pow(x, y)
Compute the power of x elevated y, it is equivalent to "(x)^(y)".
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(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(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(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(expr)
Round the value of expression expr to the nearest integer. For example, "round(1.5)" is "2.0".
f_sgn(x)
Compute sign of x.
f_sin(x)
Compute sine of x.
f_sinh(x)
Compute hyperbolic sine of x.
f_sqrt(expr)
Compute the square root of expr. This is equivalent to (expr)^.5
f_squish(x)
Compute expression 1/(1 + exp(4*x)).
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(x)
Compute tangent of x.
f_tanh(x)
Compute hyperbolic tangent of x.
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()
Return the current (wallclock) time in seconds.
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(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: