typed-ffmpeg-compatible 2.6.3__py3-none-any.whl → 2.6.4__py3-none-any.whl

typed_ffmpeg/dag/schema.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, replace
 from functools import cached_property
 from typing import TYPE_CHECKING, Literal
 
+from ..utils.forzendict import FrozenDict
 from ..utils.lazy_eval.schema import LazyValue
 from .utils import is_dag
 
@@ -84,7 +85,8 @@ class Node(HashableBaseModel, ABC):
     """
 
     # Filter_Node_Option_Type
-    kwargs: tuple[tuple[str, str | int | float | bool | LazyValue], ...] = ()
+    # kwargs: tuple[tuple[str, str | int | float | bool | LazyValue], ...] = ()
+    kwargs: FrozenDict[str, str | int | float | bool | LazyValue] = FrozenDict({})
     """
     Represents the keyword arguments of the node.
     """

typed_ffmpeg/dag/utils.py

@@ -1,22 +1,43 @@
+"""
+Utility functions for working with directed acyclic graphs (DAGs).
+
+This module provides functions for validating and analyzing graph structures,
+particularly for ensuring that filter graphs are properly formed as DAGs
+without cycles, which is a requirement for FFmpeg filter chains.
+"""
+
 from __future__ import annotations
 
 from collections import deque
 
-# Another approach to determine if a graph is a DAG is to try to perform a topological sort.
-# If the topological sort is successful (i.e., all vertices are visited exactly once),
-# the graph is a DAG. If the topological sort cannot include all vertices (i.e., the graph has a cycle),
-# it is not a DAG. Here is a basic implementation using Kahn's Algorithm:
-
 
 def is_dag(graph: dict[str, set[str]]) -> bool:
     """
-    Determine if a graph is a directed acyclic graph (DAG).
+    Determine if a graph is a directed acyclic graph (DAG) using topological sorting.
+
+    This function implements Kahn's algorithm for topological sorting to check
+    if the given graph is a DAG. A graph is a DAG if it has no directed cycles.
+    The algorithm works by repeatedly removing nodes with no incoming edges
+    and their outgoing edges. If all nodes can be removed this way, the graph
+    is a DAG; otherwise, it contains at least one cycle.
 
     Args:
-        graph: The graph to check.
+        graph: A dictionary representing the graph, where keys are node IDs and
+               values are sets of node IDs that the key node points to
 
     Returns:
-        Whether the graph is a DAG.
+        True if the graph is a DAG (has no cycles), False otherwise
+
+    Example:
+        ```python
+        # A simple linear graph (A -> B -> C)
+        graph = {"A": {"B"}, "B": {"C"}, "C": set()}
+        assert is_dag(graph) == True
+
+        # A graph with a cycle (A -> B -> C -> A)
+        graph = {"A": {"B"}, "B": {"C"}, "C": {"A"}}
+        assert is_dag(graph) == False
+        ```
     """
 
     in_degree = {u: 0 for u in graph}  # Initialize in-degree of each node to 0

typed_ffmpeg/dag/validate.py

@@ -1,3 +1,13 @@
+"""
+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.
+"""
+
 from __future__ import annotations
 
 from dataclasses import replace
@@ -14,14 +24,25 @@ def remove_split(
     current_stream: Stream, mapping: dict[Stream, Stream] = None
 ) -> tuple[Stream, dict[Stream, Stream]]:
     """
-    Rebuild the graph with the given mapping.
+    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.
 
     Args:
-        current_stream: The stream to rebuild the graph with.
-        mapping: The mapping to rebuild the graph with.
+        current_stream: The starting stream to process
+        mapping: Dictionary mapping original streams to their new versions without splits
+                (used for recursion, pass None for initial call)
 
     Returns:
-        A tuple of the new node and the new mapping.
+        A tuple containing:
+        - The new stream corresponding to the input stream but with splits removed
+        - A mapping dictionary relating original streams to their new versions
     """
 
     # remove all split nodes
@@ -76,17 +97,31 @@ def add_split(
     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.
+    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.
 
     Args:
-        current_stream: The stream to add split nodes to.
-        down_node: The node use current_stream as input.
-        down_index: The index of the input stream in down_node.
-        context: The DAG context.
-        mapping: The mapping to add split nodes to.
+        current_stream: The stream to process for potential splitting
+        down_node: The downstream node that uses current_stream as input (for recursion)
+        down_index: The input index in down_node where current_stream connects (for recursion)
+        context: The DAG context containing graph relationship information
+        mapping: Dictionary tracking the transformations (used for recursion,
+                 pass None for initial call)
 
     Returns:
-        A tuple of the new node and the new mapping.
+        Stream: The new stream (possibly from a split node output) for the specified downstream connection
+        dict: A mapping dictionary relating original stream/connections to their new versions
+
+    Raises:
+        FFMpegValueError: If an unsupported stream type is encountered
     """
 
     if not context:
@@ -149,17 +184,24 @@ def add_split(
 
 def fix_graph(stream: Stream) -> Stream:
     """
-    Fix the graph by removing and adding split nodes.
+    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.
 
     Args:
-        stream: The stream to fix.
+        stream: The root stream of the graph to fix (typically an output stream)
 
     Returns:
-        The fixed stream.
+        A new stream representing the fixed graph with proper splitting
 
     Note:
-        Fix the graph by resetting split nodes.
-        This function is for internal use only.
+        This function creates a new graph structure rather than modifying the
+        existing one, preserving the original graph.
     """
 
     stream, _ = remove_split(stream)
@@ -169,14 +211,35 @@ def fix_graph(stream: Stream) -> Stream:
 
 def validate(stream: Stream, auto_fix: bool = True) -> Stream:
     """
-    Validate the given DAG. If auto_fix is True, the graph will be automatically fixed to follow ffmpeg's rule.
+    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.
 
     Args:
-        stream: The DAG to validate.
-        auto_fix: Whether to automatically fix the graph.
+        stream: The stream representing the filter graph to validate
+        auto_fix: Whether to automatically fix stream reuse issues by adding
+                  appropriate split nodes
 
     Returns:
-        The validated DAG context.
+        Either the original stream (if no fixing needed/requested) or a new
+        stream representing the fixed graph
+
+    Example:
+        ```python
+        # 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"))
+        ```
     """
     if auto_fix:
         stream = fix_graph(stream)

typed_ffmpeg/exceptions.py

@@ -1,6 +1,18 @@
+"""
+Exception classes for handling FFmpeg-related errors.
+
+This module defines a hierarchy of exceptions that can be raised during
+FFmpeg operations, providing detailed error reporting for type errors,
+value errors, and execution failures.
+"""
+
+
 class FFMpegError(Exception):
     """
-    Base exception for all ffmpeg errors.
+    Base exception for all FFmpeg errors.
+
+    This is the parent class for all exceptions that may be raised by the
+    typed-ffmpeg library. It inherits from the standard Python Exception class.
     """
 
     ...
@@ -8,30 +20,51 @@ class FFMpegError(Exception):
 
 class FFMpegTypeError(FFMpegError, TypeError):
     """
-    Base exception for all ffmpeg type errors.
+    Exception raised for FFmpeg-related type errors.
+
+    This exception is raised when an operation receives an argument of incorrect
+    type, such as passing a string when a numeric value is expected, or vice versa.
+
+    Inherits from both FFMpegError and the standard Python TypeError.
     """
 
 
 class FFMpegValueError(FFMpegError, ValueError):
     """
-    Base exception for all ffmpeg value errors.
+    Exception raised for FFmpeg-related value errors.
+
+    This exception is raised when an operation receives an argument with the correct
+    type but an inappropriate value, such as a negative duration or invalid codec name.
+
+    Inherits from both FFMpegError and the standard Python ValueError.
     """
 
 
 class FFMpegExecuteError(FFMpegError):
     """
-    FFmpeg error
+    Exception raised when an FFmpeg command fails during execution.
+
+    This exception is raised when an FFmpeg process returns a non-zero exit code,
+    indicating that the command failed to execute properly. The exception captures
+    the return code, command string, and stdout/stderr output to help diagnose
+    the issue.
+
+    Attributes:
+        stdout: The standard output of the failed command
+        stderr: The standard error output of the failed command
+        cmd: The command string that was executed
+        retcode: The process return code
     """
 
     def __init__(self, retcode: int | None, cmd: str, stdout: bytes, stderr: bytes):
         """
-        Initialize the exception.
+        Initialize the FFMpegExecuteError with execution details.
 
         Args:
-            retcode: The return code of the command.
-            cmd: The command that was run.
-            stdout: The stdout of the command.
-            stderr: The stderr of the command.
+            retcode: The return code of the FFmpeg command
+            cmd: The FFmpeg command string that was executed
+            stdout: The captured standard output from the process
+            stderr: The captured standard error from the process
         """
 
         self.stdout = stdout

typed_ffmpeg/info.py

@@ -1,3 +1,12 @@
+"""
+Module for querying FFmpeg codec and encoder information.
+
+This module provides functionality to query the available FFmpeg codecs,
+decoders, and encoders on the system. It parses the output of FFmpeg's
+command-line tools to extract information about supported formats and
+capabilities.
+"""
+
 import logging
 import subprocess
 from dataclasses import dataclass
@@ -10,24 +19,56 @@ logger = logging.getLogger(__name__)
 
 
 class CodecFlags(Flag):
-    video = auto()
-    audio = auto()
-    subtitle = auto()
-    frame_level_multithreading = auto()
-    slice_level_multithreading = auto()
-    experimental = auto()
-    draw_horiz_band = auto()
-    direct_rendering_method_1 = auto()
+    """
+    Flag enumeration representing the capabilities of a codec.
+
+    These flags correspond to the character flags in FFmpeg's codec information
+    output and indicate what features a codec supports.
+    """
+
+    video = auto()  # Codec supports video encoding/decoding
+    audio = auto()  # Codec supports audio encoding/decoding
+    subtitle = auto()  # Codec supports subtitle processing
+    frame_level_multithreading = auto()  # Codec supports frame-level multithreading
+    slice_level_multithreading = auto()  # Codec supports slice-level multithreading
+    experimental = auto()  # Codec is considered experimental
+    draw_horiz_band = auto()  # Codec supports drawing horizontal bands
+    direct_rendering_method_1 = auto()  # Codec supports direct rendering method 1
 
 
 @dataclass(frozen=True)
 class Codec:
+    """
+    Represents an FFmpeg codec with its capabilities and description.
+
+    This immutable dataclass stores information about a codec identified by the
+    `ffmpeg -codecs` command, including its name, supported features (as flags),
+    and its textual description.
+
+    Attributes:
+        name: The codec identifier used in FFmpeg commands
+        flags: Bitmap of capabilities supported by the codec
+        description: Human-readable description of the codec
+    """
+
     name: str
     flags: CodecFlags
     description: str
 
 
 def parse_codec_flags(flags: str) -> CodecFlags:
+    """
+    Parse the FFmpeg codec flags string into a CodecFlags enum.
+
+    This function interprets the character flags from FFmpeg's codec listing
+    and converts them to the corresponding CodecFlags enum values.
+
+    Args:
+        flags: A string of flag characters from FFmpeg codec information
+
+    Returns:
+        A CodecFlags bitmap with the appropriate flags set
+    """
     flags_enum = CodecFlags(0)
     if flags[0] == "V":
         flags_enum |= CodecFlags.video
@@ -49,6 +90,18 @@ def parse_codec_flags(flags: str) -> CodecFlags:
 
 
 def get_codecs() -> tuple[Codec, ...]:
+    """
+    Query the system for all available FFmpeg codecs.
+
+    This function calls `ffmpeg -codecs` and parses the output to create
+    a tuple of Codec objects representing all codecs available on the system.
+
+    Returns:
+        A tuple of Codec objects with information about each codec
+
+    Raises:
+        FFMpegExecuteError: If the ffmpeg command fails
+    """
     args = ["ffmpeg", "-hide_banner", "-codecs"]
     logger.info("Running ffmpeg command: %s", command_line(args))
     p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -79,17 +132,36 @@ def get_codecs() -> tuple[Codec, ...]:
 
 
 class CoderFlags(Flag):
-    video = auto()
-    audio = auto()
-    subtitle = auto()
-    frame_level_multithreading = auto()
-    slice_level_multithreading = auto()
-    experimental = auto()
-    draw_horiz_band = auto()
-    direct_rendering_method_1 = auto()
+    """
+    Flag enumeration representing the capabilities of a coder (encoder/decoder).
+
+    These flags correspond to the character flags in FFmpeg's encoder/decoder
+    information output and indicate what features a coder supports.
+    """
+
+    video = auto()  # Coder supports video processing
+    audio = auto()  # Coder supports audio processing
+    subtitle = auto()  # Coder supports subtitle processing
+    frame_level_multithreading = auto()  # Coder supports frame-level multithreading
+    slice_level_multithreading = auto()  # Coder supports slice-level multithreading
+    experimental = auto()  # Coder is considered experimental
+    draw_horiz_band = auto()  # Coder supports drawing horizontal bands
+    direct_rendering_method_1 = auto()  # Coder supports direct rendering method 1
 
 
 def parse_coder_flags(flags: str) -> CoderFlags:
+    """
+    Parse the FFmpeg coder flags string into a CoderFlags enum.
+
+    This function interprets the character flags from FFmpeg's encoder/decoder
+    listing and converts them to the corresponding CoderFlags enum values.
+
+    Args:
+        flags: A string of flag characters from FFmpeg encoder/decoder information
+
+    Returns:
+        A CoderFlags bitmap with the appropriate flags set
+    """
     flags_enum = CoderFlags(0)
     if flags[0] == "V":
         flags_enum |= CoderFlags.video
@@ -112,12 +184,37 @@ def parse_coder_flags(flags: str) -> CoderFlags:
 
 @dataclass
 class Coder:
+    """
+    Represents an FFmpeg encoder or decoder with its capabilities and description.
+
+    This dataclass stores information about a coder identified by the
+    `ffmpeg -encoders` or `ffmpeg -decoders` command, including its name,
+    supported features (as flags), and its textual description.
+
+    Attributes:
+        name: The coder identifier used in FFmpeg commands
+        flags: Bitmap of capabilities supported by the coder
+        description: Human-readable description of the coder
+    """
+
     name: str
     flags: CoderFlags
     description: str
 
 
 def get_coders(codes: str) -> tuple[Coder, ...]:
+    """
+    Parse the output of an FFmpeg encoder/decoder listing into Coder objects.
+
+    This function parses the text output from `ffmpeg -encoders` or
+    `ffmpeg -decoders` commands and constructs Coder objects for each entry.
+
+    Args:
+        codes: String output from the FFmpeg encoders/decoders command
+
+    Returns:
+        A tuple of Coder objects representing the available encoders/decoders
+    """
     codecs_lines = codes.strip().split("\n")
     # Skip header lines until we find the separator
     for i, line in enumerate(codecs_lines):
@@ -136,6 +233,18 @@ def get_coders(codes: str) -> tuple[Coder, ...]:
 
 
 def get_decoders() -> tuple[Coder, ...]:
+    """
+    Query the system for all available FFmpeg decoders.
+
+    This function calls `ffmpeg -decoders` and parses the output to create
+    a tuple of Coder objects representing all decoders available on the system.
+
+    Returns:
+        A tuple of Coder objects with information about each decoder
+
+    Raises:
+        FFMpegExecuteError: If the ffmpeg command fails
+    """
     args = ["ffmpeg", "-hide_banner", "-decoders"]
     logger.info("Running ffmpeg command: %s", command_line(args))
     p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -152,6 +261,18 @@ def get_decoders() -> tuple[Coder, ...]:
 
 
 def get_encoders() -> tuple[Coder, ...]:
+    """
+    Query the system for all available FFmpeg encoders.
+
+    This function calls `ffmpeg -encoders` and parses the output to create
+    a tuple of Coder objects representing all encoders available on the system.
+
+    Returns:
+        A tuple of Coder objects with information about each encoder
+
+    Raises:
+        FFMpegExecuteError: If the ffmpeg command fails
+    """
     args = ["ffmpeg", "-hide_banner", "-encoders"]
     logger.info("Running ffmpeg command: %s", command_line(args))
     p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

typed_ffmpeg/probe.py

@@ -1,3 +1,11 @@
+"""
+Module for analyzing media files with ffprobe.
+
+This module provides functionality to extract detailed metadata from media files
+using FFmpeg's ffprobe utility. It returns a structured representation of the
+file's format, streams, and other relevant information.
+"""
+
 import json
 import logging
 import subprocess
@@ -18,16 +26,33 @@ def probe(
     **kwargs: Any,
 ) -> dict[str, Any]:
     """
-    Run ffprobe on the given file and return a JSON representation of the output
+    Analyze a media file using ffprobe and return its metadata as a dictionary.
+
+    This function executes ffprobe to extract detailed information about a media file,
+    including format metadata (container format, duration, bitrate) and stream information
+    (codecs, resolution, sample rate, etc). The result is returned as a Python dictionary
+    parsed from ffprobe's JSON output.
 
     Args:
-        filename: The path to the file to probe.
-        cmd: The ffprobe command to run. Defaults to "ffprobe".
-        timeout: The timeout for the command. Defaults to None.
-        **kwargs: The arguments for the ffprobe command.
+        filename: Path to the media file to analyze
+        cmd: Path or name of the ffprobe executable (default: "ffprobe")
+        timeout: Maximum time in seconds to wait for ffprobe to complete (default: None, wait indefinitely)
+        **kwargs: Additional arguments to pass to ffprobe as command line parameters
+            (e.g., loglevel="quiet", skip_frame="nokey")
 
     Returns:
-        The JSON representation of the ffprobe output.
+        A dictionary containing the parsed JSON output from ffprobe with format and stream information
+
+    Raises:
+        FFMpegExecuteError: If ffprobe returns a non-zero exit code
+        subprocess.TimeoutExpired: If the timeout is reached before ffprobe completes
+
+    Example:
+        ```python
+        info = probe("video.mp4")
+        print(f"Duration: {float(info['format']['duration']):.2f} seconds")
+        print(f"Streams: {len(info['streams'])}")
+        ```
     """
     args = [cmd, "-show_format", "-show_streams", "-of", "json"]
     args += convert_kwargs_to_cmd_line_args(kwargs)

typed_ffmpeg/schema.py

@@ -1,5 +1,10 @@
 """
-Defines the basic schema for the ffmpeg command line options.
+Defines the basic schema for the FFmpeg command line options.
+
+This module contains base classes used throughout the typed-ffmpeg library to handle
+default values, automatic parameter derivation, and stream type definitions.
+These components form the foundation of the type annotation system that
+enables static type checking in the FFmpeg filter graph.
 """
 
 from .common.schema import StreamType
@@ -7,8 +12,18 @@ from .common.schema import StreamType
 
 class Default(str):
     """
-    This is the default value for an option. It is used for annotation purposes only
-    and will not be passed to the ffmpeg command line.
+    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:
+        ```python
+        # This will use FFmpeg's default crf value
+        video.output("output.mp4", crf=Default("23"))
+        ```
     """
 
     ...
@@ -16,8 +31,20 @@ class Default(str):
 
 class Auto(Default):
     """
-    This is the auto value for an option. It is used for annotation purposes only
-    and will not be passed to the ffmpeg command line.
+    Represents an automatically derived value for an FFmpeg option.
+
+    This is a special case of Default that indicates the value should be
+    calculated automatically based on the context. For example, the number
+    of inputs to a filter might be derived from the number of streams passed
+    to that filter.
+
+    Auto contains an expression string that defines how the value should be computed.
+
+    Example:
+        ```python
+        # The number of inputs is automatically derived from the length of streams
+        hstack(*streams, inputs=Auto("len(streams)"))
+        ```
     """
 
 

typed_ffmpeg/streams/channel_layout.py

@@ -1,3 +1,16 @@
+"""
+Audio channel layout definitions for FFmpeg.
+
+This module defines a mapping between FFmpeg's channel layout names and
+the corresponding number of audio channels. This information is used for
+audio stream processing, filtering, and conversion operations.
+
+Channel layouts in FFmpeg represent different speaker configurations,
+such as mono (1 channel), stereo (2 channels), 5.1 (6 channels), etc.
+The names used in this dictionary match the standard names used by FFmpeg's
+channel layout API.
+"""
+
 CHANNEL_LAYOUT = {
     "mono": 1,
     "stereo": 2,