validate ¶

Graph validation and transformation for FFmpeg filter chains.

This module provides functionality to validate and fix FFmpeg filter graphs, particularly handling the case of stream reuse. In FFmpeg, a stream cannot be used as input to multiple filters without explicit split/asplit filters. This module detects such cases and automatically inserts the necessary split filters to ensure the graph is valid for FFmpeg processing.

Functions:

Name	Description
`remove_split`	Remove all split nodes from the graph to prepare for reconstruction.
`add_split`	Add split nodes to the graph where streams are reused.
`fix_graph`	Fix stream reuse issues in the filter graph by properly adding split nodes.
`validate`	Validate a filter graph and optionally fix stream reuse issues.

remove_split ¶

remove_split(
    current_stream: Stream,
    mapping: dict[Stream, Stream] = None,
) -> tuple[Stream, dict[Stream, Stream]]

Remove all split nodes from the graph to prepare for reconstruction.

This function performs the first step of graph repair by recursively traversing the graph and removing all existing split/asplit nodes. This creates a clean graph without any stream splitting, which will then be reconstructed with proper split nodes where needed.

The function works recursively, processing each node's inputs and creating a new graph structure with the split nodes removed.

Parameters:

Name	Type	Description	Default
`current_stream`	`Stream`	The starting stream to process	required
`mapping`	`dict[Stream, Stream]`	Dictionary mapping original streams to their new versions without splits (used for recursion, pass None for initial call)	`None`

Returns:

Type	Description
`Stream`	A tuple containing:
`dict[Stream, Stream]`	The new stream corresponding to the input stream but with splits removed
`tuple[Stream, dict[Stream, Stream]]`	A mapping dictionary relating original streams to their new versions

add_split ¶

add_split(
    current_stream: Stream,
    down_node: Node = None,
    down_index: int = None,
    context: DAGContext = None,
    mapping: dict[
        tuple[Stream, Node | None, int | None], Stream
    ] = None,
) -> tuple[
    Stream,
    dict[tuple[Stream, Node | None, int | None], Stream],
]

Add split nodes to the graph where streams are reused.

This function performs the second step of graph repair by traversing the graph and adding split/asplit nodes where a stream is used as input to multiple downstream nodes. In FFmpeg, each stream can only be used once unless explicitly split.

The function detects cases where a stream has multiple outgoing connections and inserts the appropriate split filter (split for video, asplit for audio), connecting each output of the split to the corresponding downstream node.

Parameters:

Name	Type	Description	Default
`current_stream`	`Stream`	The stream to process for potential splitting	required
`down_node`	`Node`	The downstream node that uses current_stream as input (for recursion)	`None`
`down_index`	`int`	The input index in down_node where current_stream connects (for recursion)	`None`
`context`	`DAGContext`	The DAG context containing graph relationship information	`None`
`mapping`	`dict[tuple[Stream, Node \| None, int \| None], Stream]`	Dictionary tracking the transformations (used for recursion, pass None for initial call)	`None`

Returns:

Name	Type	Description
`Stream`	`Stream`	The new stream (possibly from a split node output) for the specified downstream connection
`dict`	`dict[tuple[Stream, Node \| None, int \| None], Stream]`	A mapping dictionary relating original stream/connections to their new versions

Raises:

Type	Description
`FFMpegValueError`	If an unsupported stream type is encountered

fix_graph ¶

fix_graph(stream: Stream) -> Stream

Fix stream reuse issues in the filter graph by properly adding split nodes.

This function performs a complete graph repair operation by: 1. First removing all existing split/asplit nodes from the graph 2. Then adding new split/asplit nodes where needed to handle stream reuse

This ensures that the graph follows FFmpeg's requirement that each stream output can only be used as input to one filter unless explicitly split.

Parameters:

Name	Type	Description	Default
`stream`	`Stream`	The root stream of the graph to fix (typically an output stream)	required

Returns:

Type	Description
`Stream`	A new stream representing the fixed graph with proper splitting

Note

This function creates a new graph structure rather than modifying the existing one, preserving the original graph.

validate ¶

validate(stream: Stream, auto_fix: bool = True) -> Stream

Validate a filter graph and optionally fix stream reuse issues.

This function validates that the filter graph follows FFmpeg's rules, particularly regarding stream reuse. In FFmpeg, a stream cannot be used as input to multiple filters without an explicit split/asplit filter.

When auto_fix is True (the default), this function automatically inserts the necessary split filters where needed, ensuring the graph is valid for FFmpeg processing.

Parameters:

Name	Type	Description	Default
`stream`	`Stream`	The stream representing the filter graph to validate	required
`auto_fix`	`bool`	Whether to automatically fix stream reuse issues by adding appropriate split nodes	`True`

Returns:

Type	Description
`Stream`	Either the original stream (if no fixing needed/requested) or a new
`Stream`	stream representing the fixed graph

Example

# Create a graph where the same stream is used twice (reused)
input_stream = ffmpeg.input("input.mp4")
# Use the same stream for both scaling and blurring (invalid in FFmpeg)
scaled = input_stream.filter("scale", 1280, 720)
blurred = input_stream.filter("boxblur", 2)
# Validate will automatically insert a split filter
valid_stream = ffmpeg.dag.validate(scaled.output("output.mp4"))