expressions

FFmpeg expression functions and utilities.

Classes:

Name	Description
Expression	A string-based expression class for FFmpeg expressions.

Functions:

Name	Description
abs	Compute absolute value of x.
acos	Compute arccosine of x.
asin	Compute arcsine of x.
atan	Compute arctangent of x.
atan2	Compute principal value of the arc tangent of y/x.
between	Return 1 if x is greater than or equal to min and lesser than or equal to max, 0 otherwise.
bitand	Compute bitwise and/or operation on x and y.
bitor	Compute bitwise and/or operation on x and y.
ceil	Round the value of expression expr upwards to the nearest integer. For example, "ceil(1.5)" is "2.0".
clip	Return the value of x clipped between min and max.
cos	Compute cosine of x.
cosh	Compute hyperbolic cosine of x.
eq	Return 1 if x and y are equivalent, 0 otherwise.
exp	Compute exponential of x (with base e, the Euler's number).
floor	Round the value of expression expr downwards to the nearest integer. For example, "floor(-1.5)" is "-2.0".
gauss	Compute Gauss function of x, corresponding to exp(-xx/2) / sqrt(2PI).
gcd	Return 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.
gt	Return 1 if x is greater than y, 0 otherwise.
gte	Return 1 if x is greater than or equal to y, 0 otherwise.
hypot	Return 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.
if_	Evaluate x, and if the result is non-zero return the result of the evaluation of y, return 0 otherwise.
ifnot	Evaluate x, and if the result is zero return the result of the evaluation of y, return 0 otherwise.
isinf	Return 1.0 if x is +/-INFINITY, 0.0 otherwise.
isnan	Return 1.0 if x is NAN, 0.0 otherwise.
ld	Load the value of the internal variable with index idx, which was previously stored with st(idx, expr). The function returns the loaded value.
lerp	Return linear interpolation between x and y by amount of z.
log	Compute natural logarithm of x.
lt	Return 1 if x is lesser than y, 0 otherwise.
lte	Return 1 if x is lesser than or equal to y, 0 otherwise.
max	Return the maximum between x and y.
min	Return the minimum between x and y.
mod	Compute the remainder of division of x by y.
not_	Return 1.0 if expr is zero, 0.0 otherwise.
pow	Compute the power of x elevated y, it is equivalent to "(x)^(y)".
print	Print 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.
random	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).
randomi	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).
root	Find an input value for which the function represented by expr with argument ld(0) is 0 in the interval 0..max.
round	Round the value of expression expr to the nearest integer. For example, "round(1.5)" is "2.0".
sgn	Compute sign of x.
sin	Compute sine of x.
sinh	Compute hyperbolic sine of x.
sqrt	Compute the square root of expr. This is equivalent to "(expr)^.5".
squish	Compute expression 1/(1 + exp(4*x)).
st	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.
tan	Compute tangent of x.
tanh	Compute hyperbolic tangent of x.
taylor	Evaluate a Taylor series at x, given an expression representing the ld(idx)-th derivative of a function at 0.
time	Return the current (wallclock) time in seconds.
trunc	Round the value of expression expr towards zero to the nearest integer. For example, "trunc(-1.5)" is "-1.0".
while_	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.

Attributes:

Name	Type	Description
E		exp(1) (Euler's number), approximately 2.718
PHI		golden ratio (1+sqrt(5))/2, approximately 1.618
PI		area of the unit disc, approximately 3.14

E module-attribute

E = Expression('E')

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

PHI module-attribute

PHI = Expression('PHI')

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

PI module-attribute

PI = Expression('PI')

area of the unit disc, approximately 3.14

Expression

Expression(expression: str)

Bases: str

A string-based expression class for FFmpeg expressions.

Parameters:

Name	Type	Description	Default
expression	str	The FFmpeg expression string.	required

abs

abs(x: Any) -> Expression

Compute absolute value of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute absolute value for.	required

Returns:

Type	Description
Expression	Expression representing the absolute value.

acos

acos(x: Any) -> Expression

Compute arccosine of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute arccosine for.	required

Returns:

Type	Description
Expression	Expression representing the arccosine.

asin

asin(x: Any) -> Expression

Compute arcsine of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute arcsine for.	required

Returns:

Type	Description
Expression	Expression representing the arcsine.

atan

atan(x: Any) -> Expression

Compute arctangent of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute arctangent for.	required

Returns:

Type	Description
Expression	Expression representing the arctangent.

atan2

atan2(x: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The value to compute arctangent for.	required

Returns:

Type	Description
Expression	Expression representing the arctangent.

between

between(x: Any, min: Any, max: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The value to check.	required
min	Any	The minimum value.	required
max	Any	The maximum value.	required

Returns:

Type	Description
Expression	Expression representing the comparison result.

bitand

bitand(x: Any, y: Any) -> Expression

Compute bitwise and/or operation on x and y.

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required

Returns:

Type	Description
Expression	Expression representing the bitwise AND result.

bitor

bitor(x: Any, y: Any) -> Expression

Compute bitwise and/or operation on x and y.

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required

Returns:

Type	Description
Expression	Expression representing the bitwise OR result.

ceil

ceil(expr: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression to round up.	required

Returns:

Type	Description
Expression	Expression representing the ceiling value.

clip

clip(x: Any, min: Any, max: Any) -> Expression

Return the value of x clipped between min and max.

Parameters:

Name	Type	Description	Default
x	Any	The value to clip.	required
min	Any	The minimum value.	required
max	Any	The maximum value.	required

Returns:

Type	Description
Expression	Expression representing the clipped value.

cos

cos(x: Any) -> Expression

Compute cosine of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute cosine for.	required

Returns:

Type	Description
Expression	Expression representing the cosine.

cosh

cosh(x: Any) -> Expression

Compute hyperbolic cosine of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute hyperbolic cosine for.	required

Returns:

Type	Description
Expression	Expression representing the hyperbolic cosine.

eq

eq(x: Any, y: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The first value to compare.	required
y	Any	The second value to compare.	required

Returns:

Type	Description
Expression	Expression representing the equality comparison.

exp

exp(x: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The value to compute exponential for.	required

Returns:

Type	Description
Expression	Expression representing the exponential.

floor

floor(expr: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression to round down.	required

Returns:

Type	Description
Expression	Expression representing the floor value.

gauss

gauss(x: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The value to compute Gauss function for.	required

Returns:

Type	Description
Expression	Expression representing the Gauss function.

gcd

gcd(x: Any, y: Any) -> Expression

Return 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.

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required

Returns:

Type	Description
Expression	Expression representing the greatest common divisor.

gt

gt(x: Any, y: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The first value to compare.	required
y	Any	The second value to compare.	required

Returns:

Type	Description
Expression	Expression representing the greater than comparison.

gte

gte(x: Any, y: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The first value to compare.	required
y	Any	The second value to compare.	required

Returns:

Type	Description
Expression	Expression representing the greater than or equal comparison.

hypot

hypot(x: Any, y: Any) -> Expression

Return 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.

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required

Returns:

Type	Description
Expression	Expression representing the hypotenuse length.

if_

if_(x: Any, y: Any, z: Any | None = None) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The condition to evaluate.	required
y	Any	The value to return if condition is true.	required
z	Any | None	Optional value to return if condition is false.	None

Returns:

Type	Description
Expression	Expression representing the conditional result.

ifnot

ifnot(x: Any, y: Any, z: Any | None = None) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The condition to evaluate.	required
y	Any	The value to return if condition is false.	required
z	Any | None	Optional value to return if condition is true.	None

Returns:

Type	Description
Expression	Expression representing the conditional result.

isinf

isinf(x: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The value to check for infinity.	required

Returns:

Type	Description
Expression	Expression representing the infinity check.

isnan

isnan(x: Any) -> Expression

Return 1.0 if x is NAN, 0.0 otherwise.

Parameters:

Name	Type	Description	Default
x	Any	The value to check for NaN.	required

Returns:

Type	Description
Expression	Expression representing the NaN check.

ld

ld(idx: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
idx	Any	The index of the internal variable to load.	required

Returns:

Type	Description
Expression	Expression representing the loaded value.

lerp

lerp(x: Any, y: Any, z: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required
z	Any	The interpolation amount.	required

Returns:

Type	Description
Expression	Expression representing the interpolated value.

log

log(x: Any) -> Expression

Compute natural logarithm of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute natural logarithm for.	required

Returns:

Type	Description
Expression	Expression representing the natural logarithm.

lt

lt(x: Any, y: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The first value to compare.	required
y	Any	The second value to compare.	required

Returns:

Type	Description
Expression	Expression representing the less than comparison.

lte

lte(x: Any, y: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The first value to compare.	required
y	Any	The second value to compare.	required

Returns:

Type	Description
Expression	Expression representing the less than or equal comparison.

max

max(x: Any, y: Any) -> Expression

Return the maximum between x and y.

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required

Returns:

Type	Description
Expression	Expression representing the maximum value.

min

min(x: Any, y: Any) -> Expression

Return the minimum between x and y.

Parameters:

Name	Type	Description	Default
x	Any	The first value.	required
y	Any	The second value.	required

Returns:

Type	Description
Expression	Expression representing the minimum value.

mod

mod(x: Any, y: Any) -> Expression

Compute the remainder of division of x by y.

Parameters:

Name	Type	Description	Default
x	Any	The dividend.	required
y	Any	The divisor.	required

Returns:

Type	Description
Expression	Expression representing the remainder.

not_

not_(expr: Any) -> Expression

Return 1.0 if expr is zero, 0.0 otherwise.

Parameters:

Name	Type	Description	Default
expr	Any	The expression to negate.	required

Returns:

Type	Description
Expression	Expression representing the logical NOT.

pow

pow(x: Any, y: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The base value.	required
y	Any	The exponent.	required

Returns:

Type	Description
Expression	Expression representing the power.

print

print(t: Any, l: Any | None = None) -> Expression

Print 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.

Parameters:

Name	Type	Description	Default
t	Any	The expression to print.	required
l	Any | None	Optional log level.	None

Returns:

Type	Description
Expression	Expression representing the printed value.

random

random(idx: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
idx	Any	The index of the internal variable for seed/state.	required

Returns:

Type	Description
Expression	Expression representing the random value.

randomi

randomi(idx: Any, min: Any, max: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
idx	Any	The index of the internal variable for seed/state.	required
min	Any	The minimum value.	required
max	Any	The maximum value.	required

Returns:

Type	Description
Expression	Expression representing the random integer value.

root

root(expr: Any, max: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression representing the function.	required
max	Any	The maximum value for the interval.	required

Returns:

Type	Description
Expression	Expression representing the root value.

round

round(expr: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression to round.	required

Returns:

Type	Description
Expression	Expression representing the rounded value.

sgn

sgn(x: Any) -> Expression

Compute sign of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute sign for.	required

Returns:

Type	Description
Expression	Expression representing the sign.

sin

sin(x: Any) -> Expression

Compute sine of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute sine for.	required

Returns:

Type	Description
Expression	Expression representing the sine.

sinh

sinh(x: Any) -> Expression

Compute hyperbolic sine of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute hyperbolic sine for.	required

Returns:

Type	Description
Expression	Expression representing the hyperbolic sine.

sqrt

sqrt(expr: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression to compute square root for.	required

Returns:

Type	Description
Expression	Expression representing the square root.

squish

squish(x: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
x	Any	The value to compute squish function for.	required

Returns:

Type	Description
Expression	Expression representing the squish function.

st

st(idx: Any, expr: Any) -> Expression

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.

Parameters:

Name	Type	Description	Default
idx	Any	The index of the internal variable (0-9).	required
expr	Any	The expression to store.	required

Returns:

Type	Description
Expression	Expression representing the stored value.

tan

tan(x: Any) -> Expression

Compute tangent of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute tangent for.	required

Returns:

Type	Description
Expression	Expression representing the tangent.

tanh

tanh(x: Any) -> Expression

Compute hyperbolic tangent of x.

Parameters:

Name	Type	Description	Default
x	Any	The value to compute hyperbolic tangent for.	required

Returns:

Type	Description
Expression	Expression representing the hyperbolic tangent.

taylor

taylor(
    expr: Any, x: Any, idx: Any | None = None
) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression representing the derivative.	required
x	Any	The value to evaluate at.	required
idx	Any | None	Optional index for the derivative.	None

Returns:

Type	Description
Expression	Expression representing the Taylor series evaluation.

time

time(x: Any) -> Expression

Return the current (wallclock) time in seconds.

Parameters:

Name	Type	Description	Default
x	Any	Unused parameter.	required

Returns:

Type	Description
Expression	Expression representing the current time.

trunc

trunc(expr: Any) -> Expression

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

Parameters:

Name	Type	Description	Default
expr	Any	The expression to truncate.	required

Returns:

Type	Description
Expression	Expression representing the truncated value.

while_

while_(cond: Any, expr: Any) -> Expression

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.

Parameters:

Name	Type	Description	Default
cond	Any	The condition to evaluate.	required
expr	Any	The expression to evaluate while condition is true.	required

Returns:

Type	Description
Expression	Expression representing the while loop result.