compile_cli

Compiles FFmpeg filter graphs into command-line arguments.

This module provides functionality to convert the internal DAG (Directed Acyclic Graph) representation of an FFmpeg filter chain into the actual command-line arguments that would be passed to FFmpeg. It handles the following components:

1. Global Options: General FFmpeg settings like log level, overwrite flags
2. Input Files: Source media files with their specific options
3. Filter Graphs: Complex filter chains with proper stream labeling
4. Output Files: Destination files with codec and format settings

The module ensures proper ordering of arguments and handles stream mapping, filter graph syntax, and escaping of special characters in FFmpeg commands.

Functions:

Name	Description
compile	Compile a stream into a command-line string.
compile_as_list	Compile a stream into a list of FFmpeg command-line arguments.
get_args	Get the FFmpeg command-line arguments for a specific node.
get_args_filter_node	Generate the FFmpeg filter string for this filter node.
get_args_global_node	Generate the FFmpeg command-line arguments for these global options.
get_args_input_node	Generate the FFmpeg command-line arguments for this input file.
get_args_output_node	Generate the FFmpeg command-line arguments for this output file.
get_filter_dict	Load and index FFmpeg filters from the cache.
get_node_label	Get the string label for a specific node in the filter graph.
get_options_dict	Load and index FFmpeg options from the cache.
get_stream_label	Generate the FFmpeg label for this stream in filter graphs.
parse	Parse a complete FFmpeg command line into a Stream object.
parse_filter_complex	Parse an FFmpeg filter_complex string into a stream mapping.
parse_global	Parse global FFmpeg options from command-line tokens.
parse_input	Parse input file specifications and their options.
parse_options	Parse FFmpeg command-line options into a structured dictionary.
parse_output	Parse output file specifications and their options.
parse_stream_selector	Parse a stream selector string and return the corresponding stream.

compile

compile(
    stream: Stream,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> str

Compile a stream into a command-line string.

This function takes a Stream object representing an FFmpeg filter graph and converts it into a command-line string that can be passed to FFmpeg.

Parameters:

Name	Type	Description	Default
stream	Stream	The Stream object to compile into a command-line string	required
auto_fix	bool	Whether to automatically fix issues in the stream	True
use_filter_complex_script	bool	If True, use -filter_complex_script with a temporary file instead of -filter_complex	False

Returns:

Type	Description
str	A command-line string that can be passed to FFmpeg

compile_as_list

compile_as_list(
    stream: Stream,
    auto_fix: bool = True,
    use_filter_complex_script: bool = False,
) -> list[str]

Compile a stream into a list of FFmpeg command-line arguments.

This function takes a Stream object representing an FFmpeg filter graph and converts it into a list of command-line arguments that can be passed to FFmpeg. The compilation process follows these steps:

1. Validation: The graph is validated to ensure it's properly formed
2. Checks for cycles in the graph
3. Verifies stream types match filter requirements

4. Ensures all streams are properly connected

5. Global Options: Processes global FFmpeg settings

6. Log level, overwrite flags, etc.

7. These affect the entire FFmpeg process

8. Input Files: Handles source media files

9. File paths and input-specific options
10. Stream selection and format options

11. Timestamp and duration settings

12. Filter Graph: Combines all filters into a -filter_complex argument

13. Properly labels all streams
14. Maintains correct filter chain order
15. Handles stream splitting and merging

16. If use_filter_complex_script is True, creates a temporary file with the filter complex content and uses -filter_complex_script

17. Output Files: Processes destination files

18. File paths and output options
19. Codec and format settings
20. Stream mapping and selection

If auto_fix is enabled, the function will attempt to fix common issues: - Reconnecting disconnected nodes - Adding missing split filters - Fixing stream type mismatches

Parameters:

Name	Type	Description	Default
stream	Stream	The Stream object to compile into arguments	required
auto_fix	bool	Whether to automatically fix issues in the stream (e.g., reconnecting disconnected nodes)	True
use_filter_complex_script	bool	If True, use -filter_complex_script with a temporary file instead of -filter_complex	False

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Raises:

Type	Description
FFMpegValueError	If the stream contains invalid configurations that cannot be fixed

Example

# Create a simple video scaling filter graph
input_stream = ffmpeg.input("input.mp4")
scaled = input_stream.filter("scale", 1280, 720)
output_stream = scaled.output("output.mp4")

# Compile to FFmpeg arguments
args = ffmpeg.dag.compile(output_stream)
print(
    args
)  # ['ffmpeg', '-i', 'input.mp4', '-filter_complex', '...', 'output.mp4']

get_args

get_args(
    node: Node, context: DAGContext | None = None
) -> list[str]

Get the FFmpeg command-line arguments for a specific node.

This function dispatches to the appropriate argument generation function based on the node type. It handles all node types in the FFmpeg DAG: FilterNode, InputNode, OutputNode, and GlobalNode.

Parameters:

Name	Type	Description	Default
node	Node	The node to generate arguments for	required
context	DAGContext | None	Optional DAG context for resolving stream labels. If not provided, a new context will be built.	None

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Raises:

Type	Description
FFMpegValueError	If the node type is not recognized

get_args_filter_node

get_args_filter_node(
    node: FilterNode, context: DAGContext
) -> list[str]

Generate the FFmpeg filter string for this filter node.

This method creates the filter string that will be used in the filter_complex argument of the FFmpeg command. The format follows FFmpeg's syntax where input labels are followed by the filter name and parameters, and then output labels.

The filter string format is: [input_label]filter_name=param1=value1:param2=value2[output_label]

Parameters:

Name	Type	Description	Default
node	FilterNode	The FilterNode to generate arguments for	required
context	DAGContext	DAG context for resolving stream labels	required

Returns:

Type	Description
list[str]	A list of strings that, when joined, form the filter string
list[str]	for this node in the filter_complex argument

Example

For a scale filter with width=1280 and height=720, this might return: ['[0:v]', 'scale=', 'width=1280:height=720', '[s0]']

get_args_global_node

get_args_global_node(
    node: GlobalNode, context: DAGContext
) -> list[str]

Generate the FFmpeg command-line arguments for these global options.

This method creates the command-line arguments needed to specify global options to FFmpeg, such as -y for overwrite or -loglevel for controlling log output. Boolean options are converted to -option or -nooption syntax.

Parameters:

Name	Type	Description	Default
node	GlobalNode	The GlobalNode to generate arguments for	required
context	DAGContext	DAG context (not used for global options)	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For global options like overwrite and quiet logging: ['-y', '-loglevel', 'quiet']

get_args_input_node

get_args_input_node(
    node: InputNode, context: DAGContext
) -> list[str]

Generate the FFmpeg command-line arguments for this input file.

This method creates the command-line arguments needed to specify this input file to FFmpeg, including any input-specific options. Options are converted to FFmpeg's command-line format, with boolean options using -option or -nooption syntax.

Parameters:

Name	Type	Description	Default
node	InputNode	The InputNode to generate arguments for	required
context	DAGContext	DAG context (not used for input nodes)	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For an input file "input.mp4" with options like seeking to 10 seconds: ['-ss', '10', '-i', 'input.mp4']

get_args_output_node

get_args_output_node(
    node: OutputNode, context: DAGContext
) -> list[str]

Generate the FFmpeg command-line arguments for this output file.

This method creates the command-line arguments needed to specify this output file to FFmpeg, including stream mapping and output-specific options like codecs and formats. It handles both direct input streams and filter output streams appropriately.

Parameters:

Name	Type	Description	Default
node	OutputNode	The OutputNode to generate arguments for	required
context	DAGContext	DAG context for resolving stream labels	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For an output file "output.mp4" with H.264 video codec: ['-map', '[v0]', '-c:v', 'libx264', 'output.mp4']

get_filter_dict

get_filter_dict() -> dict[str, FFMpegFilter]

Load and index FFmpeg filters from the cache.

Returns:

Type	Description
dict[str, FFMpegFilter]	Dictionary mapping filter names to their FFMpegFilter definitions

get_node_label

get_node_label(node: Node, context: DAGContext) -> str

Get the string label for a specific node in the filter graph.

This method returns the label assigned to the node, which is used in FFmpeg filter graph notation. The label format depends on the node type: - Input nodes: sequential numbers (0, 1, 2...) - Filter nodes: 's' prefix followed by a number (s0, s1, s2...) - Output nodes: 'out'

Parameters:

Name	Type	Description	Default
node	Node	The node to get the label for	required
context	DAGContext	DAG context containing node ID mappings	required

Returns:

Type	Description
str	The string label for the node

Raises:

Type	Description
AssertionError	If the node is not an InputNode or FilterNode

get_options_dict

get_options_dict() -> dict[str, FFMpegOption]

Load and index FFmpeg options from the cache.

Returns:

Type	Description
dict[str, FFMpegOption]	Dictionary mapping option names to their FFMpegOption definitions

get_stream_label

get_stream_label(
    stream: Stream, context: DAGContext | None = None
) -> str

Generate the FFmpeg label for this stream in filter graphs.

This method creates the label string used to identify this stream in FFmpeg filter graphs. The format of the label depends on the stream's source (input file or filter) and type (video or audio).

For input streams, labels follow FFmpeg's stream specifier syntax: - Video streams: "0:v" (first input, video stream) - Audio streams: "0:a" (first input, audio stream) - Subtitle streams: "0:s" (first input, subtitle stream) - AV streams: "0" (first input, all streams)

For filter outputs, labels use the filter's label: - Single output filters: "filterlabel" - Multi-output filters: "filterlabel#index"

Parameters:

Name	Type	Description	Default
stream	Stream	The stream to generate a label for	required
context	DAGContext | None	Optional DAG context for resolving node labels. If not provided, a new context will be built.	None

Returns:

Type	Description
str	A string label for this stream in FFmpeg filter syntax

Raises:

Type	Description
FFMpegValueError	If the stream has an unknown type or node type

parse

parse(cli: str) -> Stream

Parse a complete FFmpeg command line into a Stream object.

This function takes a full FFmpeg command line string and converts it into a Stream object representing the filter graph. It handles all components: - Global options - Input files and their options - Filter complex - Output files and their options

Parameters:

Name	Type	Description	Default
cli	str	Complete FFmpeg command line string	required

Returns:

Type	Description
Stream	Stream object representing the parsed command line

Example

stream = parse(
    "ffmpeg -i input.mp4 -filter_complex '[0:v]scale=1280:720[v]' -map '[v]' output.mp4"
)

parse_filter_complex

parse_filter_complex(
    filter_complex: str,
    stream_mapping: dict[str, FilterableStream],
    ffmpeg_filters: dict[str, FFMpegFilter],
) -> dict[str, FilterableStream]

Parse an FFmpeg filter_complex string into a stream mapping.

This function processes a filter_complex string (e.g. "[0:v]scale=1280:720[v0]") and converts it into a mapping of stream labels to their corresponding FilterableStream objects. It handles: - Input stream references (e.g. [0:v]) - Filter definitions with parameters - Output stream labels (e.g. [v0])

Parameters:

Name	Type	Description	Default
filter_complex	str	The filter_complex string to parse	required
stream_mapping	dict[str, FilterableStream]	Existing mapping of stream labels to streams	required
ffmpeg_filters	dict[str, FFMpegFilter]	Dictionary of available FFmpeg filters	required

Returns:

Type	Description
dict[str, FilterableStream]	Updated stream mapping with new filter outputs added

Raises:

Type	Description
FFMpegValueError	If the stream type is unknown

parse_global

parse_global(
    tokens: list[str],
    ffmpeg_options: dict[str, FFMpegOption],
) -> tuple[dict[str, str | bool], list[str]]

Parse global FFmpeg options from command-line tokens.

This function processes the global options that appear before any input files in the FFmpeg command line. These options affect the entire FFmpeg process, such as log level, overwrite flags, etc.

Parameters:

Name	Type	Description	Default
tokens	list[str]	List of command-line tokens to parse	required
ffmpeg_options	dict[str, FFMpegOption]	Dictionary of valid FFmpeg options	required

Returns:

Type	Description
dict[str, str | bool]	A tuple containing:
list[str]	Dictionary of parsed global options and their values
tuple[dict[str, str | bool], list[str]]	Remaining tokens after global options are consumed

Example

For tokens like ['-y', '-loglevel', 'quiet', '-i', 'input.mp4']: Returns ({'y': True, 'loglevel': 'quiet'}, ['-i', 'input.mp4'])

parse_input

parse_input(
    tokens: list[str],
    ffmpeg_options: dict[str, FFMpegOption],
) -> dict[str, FilterableStream]

Parse input file specifications and their options.

This function processes the input portion of an FFmpeg command line, handling input file paths and input-specific options.

Parameters:

Name	Type	Description	Default
tokens	list[str]	List of command-line tokens for input specifications	required
ffmpeg_options	dict[str, FFMpegOption]	Dictionary of valid FFmpeg options	required

Returns:

Type	Description
dict[str, FilterableStream]	Dictionary mapping input indices to their FilterableStream objects

parse_options

parse_options(
    tokens: list[str],
) -> dict[str, list[str | None | bool]]

Parse FFmpeg command-line options into a structured dictionary.

This function processes a list of command-line tokens and converts them into a dictionary where keys are option names (without the leading '-') and values are lists of their corresponding values. Boolean options are handled specially: - '-option' becomes {'option': [None]} - '-nooption' becomes {'option': [False]}

Parameters:

Name	Type	Description	Default
tokens	list[str]	List of command-line tokens to parse	required

Returns:

Type	Description
dict[str, list[str | None | bool]]	Dictionary mapping option names to lists of their values

parse_output

parse_output(
    source: list[str],
    in_streams: Mapping[str, FilterableStream],
    ffmpeg_options: dict[str, FFMpegOption],
) -> list[OutputStream]

Parse output file specifications and their options.

This function processes the output portion of an FFmpeg command line, handling output file paths, stream mapping, and output-specific options.

Parameters:

Name	Type	Description	Default
source	list[str]	List of command-line tokens for output specifications	required
in_streams	Mapping[str, FilterableStream]	Dictionary of available input streams	required
ffmpeg_options	dict[str, FFMpegOption]	Dictionary of valid FFmpeg options	required

Returns:

Type	Description
list[OutputStream]	List of OutputStream objects representing the output specifications

parse_stream_selector

parse_stream_selector(
    selector: str, mapping: Mapping[str, FilterableStream]
) -> FilterableStream

Parse a stream selector string and return the corresponding stream.

This function handles FFmpeg's stream selector syntax: - Simple selectors: "[0]" (first input) - Type selectors: "[0:v]" (first input, video stream) - Index selectors: "[0:v:0]" (first input, first video stream)

Parameters:

Name	Type	Description	Default
selector	str	Stream selector string to parse	required
mapping	Mapping[str, FilterableStream]	Dictionary of available streams	required

Returns:

Type	Description
FilterableStream	The selected FilterableStream

Raises:

Type	Description
AssertionError	If the stream label is not found in the mapping
FFMpegValueError	If the stream type is unknown