run

Re-export from ffmpeg_core.utils.run.

Classes:

Name	Description
Default	Represents a default value for an FFmpeg option.
FrozenDict	An immutable dictionary implementation.
LazyValue	Abstract base class for lazy evaluation of expressions.

Functions:

Name	Description
command_line	Convert a list of command arguments to a properly escaped command-line string.
ignore_default	Filter out Default values from a dictionary of options.

Default

Bases: str

Represents a default value for an FFmpeg option.

This class is used for annotation purposes only and indicates that a parameter should use its default value. When a parameter is marked with Default, it will not be explicitly passed to the FFmpeg command line, letting FFmpeg use its built-in default value instead.

Example

# This will use FFmpeg's default crf value
video.output("output.mp4", crf=Default("23"))

FrozenDict

FrozenDict(data: dict[K, V])

Bases: Mapping[K, V], Generic[K, V]

An immutable dictionary implementation.

FrozenDict provides a hashable, immutable view of a dictionary. It implements the Mapping interface but does not allow modification after creation. This makes it suitable for use as dictionary keys or in sets where mutability would cause issues.

Parameters:

Name	Type	Description	Default
data	dict[K, V]	Dictionary to create a frozen copy of	required

LazyValue

Bases: ABC

Abstract base class for lazy evaluation of expressions.

LazyValue represents an expression that can be evaluated at a later time, when all required values are available. It supports various arithmetic operations, allowing complex expressions to be built and evaluated lazily.

This class serves as the foundation for the lazy evaluation system, with concrete implementations like Symbol and LazyOperator providing specific functionality.

Methods:

Name	Description
eval	Evaluate the lazy value with the given values.
keys	Get the keys that are required to evaluate the lazy value.
partial	Evaluate the lazy value with the given values.
ready	Check if the lazy value is ready to be evaluated.

eval

eval(**values: Any) -> Any

Evaluate the lazy value with the given values.

Parameters:

Name	Type	Description	Default
**values	Any	Values to be used for evaluation.	{}

Returns:

Name	Type	Description
Any	Any	The evaluated value.

Raises:

Type	Description
ValueError	If the lazy value is not ready to be evaluated.

keys abstractmethod

keys() -> set[str]

Get the keys that are required to evaluate the lazy value.

This method returns the set of symbol names that must be provided as values for the lazy value to be fully evaluated. For example, if the lazy value represents the expression 'width * height', this method would return {'width', 'height'}.

Returns:

Type	Description
set[str]	A set of strings representing the required symbol names

partial abstractmethod

partial(**values: Any) -> Any

Evaluate the lazy value with the given values.

Parameters:

Name	Type	Description	Default
**values	Any	Values to be used for evaluation.	{}

Returns:

Name	Type	Description
Any	Any	The partially evaluated value.

ready

ready() -> bool

Check if the lazy value is ready to be evaluated.

A lazy value is considered ready for evaluation when it doesn't require any additional values to be provided. This is determined by checking if the set of required keys is empty.

Returns:

Type	Description
bool	True if the lazy value can be evaluated without additional values,
bool	False otherwise

command_line

command_line(args: list[str]) -> str

Convert a list of command arguments to a properly escaped command-line string.

This function takes a list of command arguments and converts it to a single string with proper shell escaping applied to each argument. This is useful for logging commands or displaying them to users.

Parameters:

Name	Type	Description	Default
args	list[str]	The command arguments to convert to a string	required

Returns:

Type	Description
str	A properly escaped command-line string representation of the arguments

Example

cmd = ["ffmpeg", "-i", "input file.mp4", "-c:v", "libx264"]
print(command_line(cmd))  # 'ffmpeg -i "input file.mp4" -c:v libx264'

ignore_default

ignore_default(
    kwargs: Mapping[
        str, str | int | float | bool | Default
    ],
) -> FrozenDict[str, str | int | float | bool | LazyValue]

Filter out Default values from a dictionary of options.

This function is used to process FFmpeg filter options and command arguments, removing any values that are instances of the Default class. This ensures that only explicitly set options are passed to FFmpeg, allowing default values to be applied by FFmpeg itself.

Parameters:

Name	Type	Description	Default
kwargs	Mapping[str, str | int | float | bool | Default]	A mapping containing parameter names and values, which may include Default instances	required

Returns:

Type	Description
FrozenDict[str, str | int | float | bool | LazyValue]	An immutable FrozenDict containing only non-Default values

Example

options = {"width": 1920, "height": 1080, "format": Default("yuv420p")}
filtered = ignore_default(options)  # {"width": 1920, "height": 1080}