context ¶

Context management for FFmpeg filter graph traversal and manipulation.

This module provides the DAGContext class, which represents the context of a Directed Acyclic Graph (DAG) of FFmpeg filter nodes. It provides methods for traversing, manipulating, and rendering the graph structure, and is used during graph validation and command-line compilation.

Classes:

Name	Description
`DAGContext`	Context class for working with a Directed Acyclic Graph (DAG) of FFmpeg filter nodes.

DAGContext `dataclass` ¶

DAGContext(
    *,
    node: Node,
    nodes: tuple[Node, ...],
    streams: tuple[Stream, ...]
)

Context class for working with a Directed Acyclic Graph (DAG) of FFmpeg filter nodes.

This immutable class provides methods and properties for analyzing, traversing, and manipulating a filter graph. It maintains information about nodes and streams in the graph, their relationships, and provides efficient lookups for graph operations.

The context is built from a "root" node (typically an output node) and captures all upstream dependencies (input nodes, filter nodes, and connecting streams).

Methods:

Name	Description
`build`	Create a DAG context by traversing the graph from the specified root node.
`get_outgoing_nodes`	Get all nodes that receive a specific stream as input.
`get_node_label`	Get the string label for a specific node in the filter graph.
`get_outgoing_streams`	Get all streams that originate from a specific node.
`render`	Recursively convert graph objects to a human-readable representation.

Attributes:

Name	Type	Description
`node`	`Node`	The root node (the destination) of the DAG.
`nodes`	`tuple[Node, ...]`	All nodes in the graph as an immutable tuple.
`streams`	`tuple[Stream, ...]`	All streams in the graph as an immutable tuple.
`all_nodes`	`list[Node]`	Get all nodes in the graph sorted by their position in the processing chain.
`all_streams`	`list[Stream]`	Get all streams in the graph sorted by their position in the processing chain.
`outgoing_nodes`	`dict[Stream, list[tuple[Node, int]]]`	Get a mapping of streams to the nodes they connect to.
`outgoing_streams`	`dict[Node, list[Stream]]`	Get a mapping of nodes to the streams they output.
`node_labels`	`dict[Node, str]`	Get a mapping of nodes to their string labels used in FFmpeg filter graphs.

node `instance-attribute` ¶

node: Node

The root node (the destination) of the DAG.

This is typically an output node where the graph traversal begins. All nodes collected in the context are upstream from this node.

nodes `instance-attribute` ¶

nodes: tuple[Node, ...]

All nodes in the graph as an immutable tuple.

This includes the root node and all upstream nodes (inputs, filters) that contribute to the filter graph.

streams `instance-attribute` ¶

streams: tuple[Stream, ...]

All streams in the graph as an immutable tuple.

These streams represent the connections between nodes in the filter graph.

all_nodes `cached` `property` ¶

all_nodes: list[Node]

Get all nodes in the graph sorted by their position in the processing chain.

This property returns a list of all nodes in the graph, sorted by the number of upstream nodes. This ensures that nodes earlier in the processing chain (closer to inputs) come before nodes later in the chain (closer to outputs).

Returns:

Type	Description
`list[Node]`	A sorted list of all nodes in the graph

all_streams `cached` `property` ¶

all_streams: list[Stream]

Get all streams in the graph sorted by their position in the processing chain.

This property returns a list of all streams in the graph, sorted first by the number of upstream nodes of the source node, and then by the stream index. This ensures a consistent and logical ordering of streams based on their position in the processing pipeline.

Returns:

Type	Description
`list[Stream]`	A sorted list of all streams in the graph

outgoing_nodes `cached` `property` ¶

outgoing_nodes: dict[Stream, list[tuple[Node, int]]]

Get a mapping of streams to the nodes they connect to.

This property builds a dictionary that maps each stream to a list of tuples containing (node, input_index) pairs. Each tuple represents a node that receives this stream as input, along with the index position where the stream connects to that node.

Returns:

Type	Description
`dict[Stream, list[tuple[Node, int]]]`	A dictionary mapping streams to their destination nodes and connection indices

outgoing_streams `cached` `property` ¶

outgoing_streams: dict[Node, list[Stream]]

Get a mapping of nodes to the streams they output.

This property builds a dictionary that maps each node to a list of streams that originate from it. This is particularly useful for determining all the outputs from a specific filter or input node.

Returns:

Type	Description
`dict[Node, list[Stream]]`	A dictionary mapping nodes to their output streams

node_labels `cached` `property` ¶

node_labels: dict[Node, str]

Get a mapping of nodes to their string labels used in FFmpeg filter graphs.

This property assigns a unique label to each node in the graph, following the FFmpeg filter graph labeling conventions: - Input nodes are labeled with sequential numbers (0, 1, 2...) - Filter nodes are labeled with 's' followed by a number (s0, s1, s2...) - Output nodes are labeled as 'out'

These labels are used when generating the filter_complex argument for FFmpeg.

Returns:

Type	Description
`dict[Node, str]`	A dictionary mapping nodes to their string labels

build `classmethod` ¶

build(node: Node) -> DAGContext

Create a DAG context by traversing the graph from the specified root node.

This factory method builds a complete DAGContext by recursively collecting all nodes and streams that are upstream from the specified node. It removes duplicates to ensure each node and stream is represented only once in the context.

Parameters:

Name	Type	Description	Default
`node`	`Node`	The root node to build the context from (typically an output node)	required

Returns:

Type	Description
`DAGContext`	A fully initialized DAGContext containing all nodes and streams in the graph

get_outgoing_nodes ¶

get_outgoing_nodes(
    stream: Stream,
) -> list[tuple[Node, int]]

Get all nodes that receive a specific stream as input.

This method returns a list of (node, index) tuples representing the nodes that receive the given stream as input, along with the input index position where the stream connects to each node.

Parameters:

Name	Type	Description	Default
`stream`	`Stream`	The stream to get the destination nodes for	required

Returns:

Type	Description
`list[tuple[Node, int]]`	A list of (node, input_index) tuples for nodes that receive this stream

get_node_label ¶

get_node_label(node: Node) -> 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...)

Parameters:

Name	Type	Description	Default
`node`	`Node`	The node to get the label for (must be an InputNode or FilterNode)	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_outgoing_streams ¶

get_outgoing_streams(node: Node) -> list[Stream]

Get all streams that originate from a specific node.

This method returns all streams where the given node is the source. It's particularly useful because nodes natively only track their inputs, not their outputs, so this context method provides a way to look up a node's outputs.

Parameters:

Name	Type	Description	Default
`node`	`Node`	The node to get the output streams for	required

Returns:

Type	Description
`list[Stream]`	A list of streams that originate from this node

render ¶

render(obj: Any) -> Any

Recursively convert graph objects to a human-readable representation.

This method processes arbitrary objects, with special handling for graph elements like nodes and streams. It converts them to a readable string format that includes node labels. It recursively handles nested structures like lists, tuples, and dictionaries.

This is primarily used for debugging, logging, and visualization purposes.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to render, which may be a Node, Stream, or a container with these objects nested inside	required

Returns:

Type	Description
`Any`	The rendered representation of the object:
`Any`	For nodes: "Node(repr#label)"
`Any`	For streams: "Stream(node_repr#label#index)"
`Any`	For containers: recursively rendered contents
`Any`	For other objects: the original object unchanged

context ¶

DAGContext dataclass ¶

node instance-attribute ¶

nodes instance-attribute ¶

streams instance-attribute ¶

all_nodes cached property ¶

all_streams cached property ¶

outgoing_nodes cached property ¶

outgoing_streams cached property ¶

node_labels cached property ¶

build classmethod ¶

get_outgoing_nodes ¶

get_node_label ¶

get_outgoing_streams ¶

render ¶

DAGContext `dataclass` ¶

node `instance-attribute` ¶

nodes `instance-attribute` ¶

streams `instance-attribute` ¶

all_nodes `cached` `property` ¶

all_streams `cached` `property` ¶

outgoing_nodes `cached` `property` ¶

outgoing_streams `cached` `property` ¶

node_labels `cached` `property` ¶

build `classmethod` ¶