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

typed_ffmpeg/__init__.py

@@ -1,3 +1,27 @@
+"""
+typed-ffmpeg: A strongly-typed FFmpeg binding for Python.
+
+This module provides a high-level, type-safe interface to FFmpeg, enabling
+Python developers to process audio and video with compile-time validation.
+The library uses Python's type annotations to ensure correct filter graphs
+and parameter usage.
+
+Key components:
+- Input/output handling via `input` and `output` functions
+- Stream manipulation with `VideoStream`, `AudioStream`, and `AVStream` classes
+- Filter application through the `filters` module
+- Media information analysis using `probe` function
+- Codec and encoder detection with `get_codecs`, `get_decoders`, and `get_encoders`
+
+Example:
+    ```python
+    import ffmpeg
+
+    # Simple video transcoding
+    (ffmpeg.input("input.mp4").output("output.mp4").run())
+    ```
+"""
+
 from . import dag, filters, sources
 from .base import afilter, filter_multi_output, input, merge_outputs, output, vfilter
 from .dag import Stream

typed_ffmpeg/base.py

@@ -1,5 +1,10 @@
 """
-This module defined the basic functions for creating the ffmpeg filter graph.
+Core functions for creating and manipulating FFmpeg filter graphs.
+
+This module defines the fundamental functions for building FFmpeg filter graphs
+in typed-ffmpeg. It provides functions to create custom filters, handle
+multi-output filters, and merge output streams. These functions serve as the
+foundation for the more specialized filters defined in the filters module.
 """
 
 from typing import Any
@@ -16,17 +21,32 @@ from .dag.nodes import (
 from .schema import StreamType
 from .streams.audio import AudioStream
 from .streams.video import VideoStream
+from .utils.forzendict import FrozenDict
 
 
 def merge_outputs(*streams: OutputStream) -> GlobalStream:
     """
-    Merge multiple output streams into one.
+    Merge multiple output streams into a single command execution.
+
+    This function combines multiple output streams that need to be executed together
+    in a single FFmpeg command. This is useful when you need to generate multiple
+    outputs from the same input(s) in a single pass, which is more efficient than
+    running separate commands.
 
     Args:
-        *streams: The output streams to merge.
+        *streams: Two or more output streams to be merged together
 
     Returns:
-        The merged output stream.
+        A global stream representing all merged outputs
+
+    Example:
+        ```python
+        input_video = ffmpeg.input("input.mp4")
+        output1 = input_video.output("output1.mp4", vcodec="libx264")
+        output2 = input_video.output("output2.mp4", vcodec="libx265")
+        merged = ffmpeg.merge_outputs(output1, output2)
+        merged.run()  # Executes both outputs in a single FFmpeg command
+        ```
     """
     return GlobalNode(inputs=streams).stream()
 
@@ -38,26 +58,37 @@ def vfilter(
     **kwargs: Any,
 ) -> VideoStream:
     """
-    Apply a custom video filter which has only one output to this stream
+    Apply a custom video filter that has a single video output.
+
+    This function allows you to use any FFmpeg video filter that isn't explicitly
+    implemented in typed-ffmpeg. It creates a FilterNode with a video output type
+    and returns the resulting video stream.
 
     Args:
-        *streams: the streams to apply the filter to
-        name: the name of the filter
-        input_typings: the input typings of the filter
-        **kwargs: the arguments for the filter
+        *streams: One or more input streams to apply the filter to
+        name: The FFmpeg filter name (e.g., 'hflip', 'scale', etc.)
+        input_typings: The expected types of the input streams (defaults to video)
+        **kwargs: Filter-specific parameters as keyword arguments
 
     Returns:
-        the output stream
+        A VideoStream representing the filtered output
+
+    Example:
+        ```python
+        # Apply a custom deflicker filter (if not directly implemented)
+        filtered = ffmpeg.vfilter(stream, name="deflicker", mode="pm", size=10)
+        ```
 
     Note:
-        This function is for custom filter which is not implemented in typed-ffmpeg
+        This function is for custom filters not implemented in typed-ffmpeg.
+        Use the built-in filters from the filters module when available.
     """
     return FilterNode(
         name=name,
         inputs=streams,
         output_typings=(StreamType.video,),
         input_typings=input_typings,
-        kwargs=tuple(kwargs.items()),
+        kwargs=FrozenDict(kwargs),
     ).video(0)
 
 
@@ -68,26 +99,37 @@ def afilter(
     **kwargs: Any,
 ) -> AudioStream:
     """
-    Apply a custom audio filter which has only one output to this stream
+    Apply a custom audio filter that has a single audio output.
+
+    This function allows you to use any FFmpeg audio filter that isn't explicitly
+    implemented in typed-ffmpeg. It creates a FilterNode with an audio output type
+    and returns the resulting audio stream.
 
     Args:
-        *streams: the streams to apply the filter to
-        name: the name of the filter
-        input_typings: the input typings of the filter
-        **kwargs: the arguments for the filter
+        *streams: One or more input streams to apply the filter to
+        name: The FFmpeg filter name (e.g., 'equalizer', 'dynaudnorm', etc.)
+        input_typings: The expected types of the input streams (defaults to audio)
+        **kwargs: Filter-specific parameters as keyword arguments
 
     Returns:
-        the output stream
+        An AudioStream representing the filtered output
+
+    Example:
+        ```python
+        # Apply a custom audio compressor filter (if not directly implemented)
+        compressed = ffmpeg.afilter(stream, name="acompressor", threshold=0.1, ratio=2)
+        ```
 
     Note:
-        This function is for custom filter which is not implemented in typed-ffmpeg
+        This function is for custom filters not implemented in typed-ffmpeg.
+        Use the built-in filters from the filters module when available.
     """
     return FilterNode(
         name=name,
         inputs=streams,
         output_typings=(StreamType.audio,),
         input_typings=input_typings,
-        kwargs=tuple(kwargs.items()),
+        kwargs=FrozenDict(kwargs),
     ).audio(0)
 
 
@@ -99,24 +141,40 @@ def filter_multi_output(
     **kwargs: Any,
 ) -> FilterNode:
     """
-    Apply a custom filter which has multiple outputs to this stream
+    Apply a custom filter that produces multiple output streams.
+
+    This function allows you to use any FFmpeg filter that generates multiple outputs
+    (like split, asplit, or complex filters). Unlike vfilter and afilter which return
+    a single stream, this returns a FilterNode that you can extract specific outputs from.
 
     Args:
-        *streams: the streams to apply the filter to
-        name: the name of the filter
-        input_typings: the input typings of the filter
-        output_tyings: the output typings of the filter
-        **kwargs: the arguments for the filter
+        *streams: One or more input streams to apply the filter to
+        name: The FFmpeg filter name (e.g., 'split', 'channelsplit', etc.)
+        input_typings: The expected types of the input streams
+        output_tyings: The expected types of each output stream
+        **kwargs: Filter-specific parameters as keyword arguments
 
     Returns:
-        the FilterNode
+        A FilterNode object that you can extract specific outputs from
+        using methods like .video(0), .audio(1), etc.
+
+    Example:
+        ```python
+        # Split a video into two identical streams
+        split_node = ffmpeg.filter_multi_output(
+            stream, name="split", output_tyings=(StreamType.video, StreamType.video)
+        )
+        stream1 = split_node.video(0)
+        stream2 = split_node.video(1)
+        ```
 
     Note:
-        This function is for custom filter which is not implemented in typed-ffmpeg
+        This function is for custom filters not implemented in typed-ffmpeg.
+        Use the built-in filters from the filters module when available.
     """
     return FilterNode(
         name=name,
-        kwargs=tuple(kwargs.items()),
+        kwargs=FrozenDict(kwargs),
         inputs=streams,
         input_typings=input_typings,
         output_typings=output_tyings,

typed_ffmpeg/common/schema.py

@@ -1,22 +1,47 @@
+"""
+Schema definitions for FFmpeg filters and options.
+
+This module defines the core data structures and enumerations used to represent
+FFmpeg filters, their options, and stream types. These schemas are used throughout
+the typed-ffmpeg library to provide type-safe interfaces to FFmpeg functionality.
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
 from typing import Literal
 
+from ffmpeg.common.serialize import Serializable, serializable
 
+
+@serializable
 class StreamType(str, Enum):
     """
-    The type of a stream. (audio or video)
+    Enumeration of possible stream types in FFmpeg.
+
+    This enum defines the fundamental types of media streams that can be
+    processed by FFmpeg filters. Each stream in FFmpeg is either an audio
+    stream or a video stream, and filters are designed to work with
+    specific stream types.
     """
 
     audio = "audio"
-    """it is an audio stream"""
+    """Represents an audio stream containing sound data"""
+
     video = "video"
-    """it is a video stream"""
+    """Represents a video stream containing visual frame data"""
 
 
 class FFMpegFilterOptionType(str, Enum):
+    """
+    Enumeration of possible data types for FFmpeg filter options.
+
+    This enum defines the various data types that can be used for options
+    in FFmpeg filters. Each type corresponds to a specific kind of value
+    that can be passed to a filter parameter.
+    """
+
     boolean = "boolean"
     duration = "duration"
     color = "color"
@@ -36,86 +61,232 @@ class FFMpegFilterOptionType(str, Enum):
 
 
 class FFMpegFilterType(str, Enum):
+    """
+    Enumeration of FFmpeg filter types based on input/output stream types.
+
+    This enum categorizes filters according to what types of streams they
+    process and produce. The naming convention follows FFmpeg's internal
+    categorization of filters.
+    """
+
     af = "af"
+    """Audio filter: processes audio and outputs audio"""
+
     asrc = "asrc"
+    """Audio source: generates audio without input"""
+
     asink = "asink"
+    """Audio sink: consumes audio without producing output"""
+
     vf = "vf"
+    """Video filter: processes video and outputs video"""
+
     vsrc = "vsrc"
+    """Video source: generates video without input"""
+
     vsink = "vsink"
+    """Video sink: consumes video without producing output"""
+
     avsrc = "avsrc"
+    """Audio-video source: generates both audio and video without input"""
+
     avf = "avf"
+    """Audio-video filter: processes and outputs both audio and video"""
+
     vaf = "vaf"
+    """Video-to-audio filter: processes video and outputs audio"""
 
 
 @dataclass(frozen=True, kw_only=True)
 class FFMpegFilterOptionChoice:
+    """
+    Represents a single choice for an FFmpeg filter option with enumerated values.
+
+    Some FFmpeg filter options accept only specific enumerated values. This class
+    represents one such value along with its description and internal representation.
+    """
+
     name: str
+    """The name of the choice as it appears in FFmpeg documentation"""
+
     help: str
+    """Description of what this choice does"""
+
     value: str | int
+    """The actual value to pass to FFmpeg when this choice is selected"""
+
     flags: str | None = None
+    """Optional flags associated with this choice"""
 
 
 @dataclass(frozen=True, kw_only=True)
 class FFMpegFilterOption:
+    """
+    Represents a configurable option for an FFmpeg filter.
+
+    This class defines the metadata for a single option that can be passed to
+    an FFmpeg filter, including its type, constraints, and default value.
+    """
+
     name: str
+    """The primary name of the option as used in FFmpeg"""
+
     alias: tuple[str, ...] = ()
+    """Alternative names that can be used for this option"""
+
     description: str
+    """Human-readable description of what the option does"""
+
     type: FFMpegFilterOptionType
+    """The data type of the option (boolean, int, string, etc.)"""
+
     min: str | None = None
+    """Minimum allowed value for numeric options"""
+
     max: str | None = None
+    """Maximum allowed value for numeric options"""
+
     default: bool | int | float | str | None = None
+    """Default value used by FFmpeg if the option is not specified"""
+
     required: bool = False
+    """Whether the option must be provided or can be omitted"""
+
     choices: tuple[FFMpegFilterOptionChoice, ...] = ()
+    """Enumerated values that this option accepts, if applicable"""
+
     flags: str | None = None
+    """Optional flags that modify the behavior of this option"""
 
 
 @dataclass(frozen=True, kw_only=True)
 class FFMpegIOType:
+    """
+    Defines the type information for a filter's input or output stream.
+
+    This class associates a name with a stream type (audio or video) for
+    a specific input or output of an FFmpeg filter.
+    """
+
     name: str | None = None
+    """Optional name for this input/output stream"""
+
     type: StreamType
+    """The type of the stream (audio or video)"""
 
 
 @dataclass(frozen=True, kw_only=True)
 class FFMpegFilterDef:
+    """
+    Defines the basic structure of an FFmpeg filter.
+
+    This class provides a simplified representation of an FFmpeg filter,
+    focusing on its name and the types of its inputs and outputs.
+    """
+
     name: str
+    """The name of the filter as used in FFmpeg"""
 
     typings_input: str | tuple[Literal["video", "audio"], ...] = ()
+    """
+    The types of input streams this filter accepts.
+    Can be a tuple of stream types or a string expression that evaluates to a tuple.
+    """
+
     typings_output: str | tuple[Literal["video", "audio"], ...] = ()
+    """
+    The types of output streams this filter produces.
+    Can be a tuple of stream types or a string expression that evaluates to a tuple.
+    """
 
 
 @dataclass(frozen=True, kw_only=True)
-class FFMpegFilter:
+class FFMpegFilter(Serializable):
+    """
+    Comprehensive representation of an FFmpeg filter with all its metadata.
+
+    This class contains the complete definition of an FFmpeg filter, including
+    its name, description, capabilities, input/output specifications, and options.
+    It serves as the central schema for representing filters in typed-ffmpeg.
+    """
+
     id: str | None = None
+    """Optional unique identifier for the filter"""
 
     name: str
+    """The name of the filter as used in FFmpeg commands"""
+
     description: str
+    """Human-readable description of what the filter does"""
+
     ref: str | None = None
+    """Optional reference to documentation or source code"""
 
     # Flags
     is_support_slice_threading: bool | None = None
+    """Whether the filter supports slice-based multithreading"""
+
     is_support_timeline: bool | None = None
+    """Whether the filter supports timeline editing features"""
+
     is_support_framesync: bool | None = None
+    """Whether the filter supports frame synchronization"""
+
     is_support_command: bool | None = None
+    """Whether the filter supports runtime commands"""
+
     is_filter_sink: bool | None = None
+    """Whether the filter is a sink (consumes input without producing output)"""
+
     is_filter_source: bool | None = None
+    """Whether the filter is a source (produces output without requiring input)"""
 
     # IO Typing
     is_dynamic_input: bool = False
+    """Whether the filter can accept a variable number of inputs"""
+
     is_dynamic_output: bool = False
+    """Whether the filter can produce a variable number of outputs"""
+
     stream_typings_input: tuple[FFMpegIOType, ...] = ()
+    """The types of input streams this filter accepts"""
+
     stream_typings_output: tuple[FFMpegIOType, ...] = ()
+    """The types of output streams this filter produces"""
+
     formula_typings_input: str | None = None
+    """Optional formula to dynamically determine input types"""
+
     formula_typings_output: str | None = None
+    """Optional formula to dynamically determine output types"""
 
     pre: tuple[tuple[str, str], ...] = ()
+    """Pre-defined parameter pairs for the filter"""
+
     options: tuple[FFMpegFilterOption, ...] = ()
+    """The configurable options this filter accepts"""
 
     @property
     def pre_dict(self) -> dict[str, str]:
+        """
+        Convert the pre-defined parameter pairs to a dictionary.
+
+        Returns:
+            A dictionary mapping parameter names to their values
+        """
         return dict(self.pre)
 
     @property
     def to_def(self) -> FFMpegFilterDef:
+        """
+        Convert this comprehensive filter definition to a simplified FFMpegFilterDef.
+
+        This creates a simplified representation of the filter focusing only on
+        its name and input/output types, which is useful for filter node creation.
+
+        Returns:
+            A simplified FFMpegFilterDef representation of this filter
+        """
         return FFMpegFilterDef(
             name=self.name,
             typings_input=self.formula_typings_input
@@ -126,6 +297,18 @@ class FFMpegFilter:
 
     @property
     def input_typings(self) -> set[StreamType]:
+        """
+        Determine the set of input stream types this filter accepts.
+
+        This property analyzes the filter's input specifications to determine
+        what types of streams (audio, video, or both) it can accept as input.
+
+        Returns:
+            A set of StreamType values representing accepted input types
+
+        Raises:
+            AssertionError: If a dynamic input filter has no input formula
+        """
         if self.is_filter_source:
             return set()
         if not self.is_dynamic_input:
@@ -150,6 +333,18 @@ class FFMpegFilter:
 
     @property
     def output_typings(self) -> set[StreamType]:
+        """
+        Determine the set of output stream types this filter produces.
+
+        This property analyzes the filter's output specifications to determine
+        what types of streams (audio, video, or both) it can produce as output.
+
+        Returns:
+            A set of StreamType values representing produced output types
+
+        Raises:
+            AssertionError: If a dynamic output filter has no output formula
+        """
         if self.is_filter_sink:
             return set()
         if not self.is_dynamic_output:
@@ -174,6 +369,22 @@ class FFMpegFilter:
 
     @property
     def filter_type(self) -> FFMpegFilterType:
+        """
+        Determine the FFmpeg filter type based on input and output stream types.
+
+        This property analyzes the filter's input and output specifications to
+        determine which category of filter it belongs to according to FFmpeg's
+        classification system (audio filter, video filter, source, sink, etc.).
+
+        Returns:
+            The appropriate FFMpegFilterType for this filter
+
+        Raises:
+            ValueError: If the filter's input/output configuration doesn't match
+                       any known filter type
+            AssertionError: If a sink filter has multiple input types or
+                           if a filter has no input types
+        """
         if self.is_filter_sink:
             assert len(self.input_typings) == 1
             if {StreamType.video} == self.input_typings:
@@ -284,35 +495,96 @@ class FFMpegOptionFlag(int, Enum):
 
 
 class FFMpegOptionType(str, Enum):
+    """
+    Enumeration of FFmpeg option data types.
+
+    This enum defines the various data types that can be used for FFmpeg
+    command-line options. These types correspond to the internal option
+    types defined in FFmpeg's libavutil/opt.h header.
+    """
+
     OPT_TYPE_FUNC = "OPT_TYPE_FUNC"
+    """Function option type, typically used for callback functions"""
+
     OPT_TYPE_BOOL = "OPT_TYPE_BOOL"
+    """Boolean option type (true/false)"""
+
     OPT_TYPE_STRING = "OPT_TYPE_STRING"
+    """String option type"""
+
     OPT_TYPE_INT = "OPT_TYPE_INT"
+    """Integer option type"""
+
     OPT_TYPE_INT64 = "OPT_TYPE_INT64"
+    """64-bit integer option type"""
+
     OPT_TYPE_FLOAT = "OPT_TYPE_FLOAT"
+    """Floating-point option type"""
+
     OPT_TYPE_DOUBLE = "OPT_TYPE_DOUBLE"
+    """Double-precision floating-point option type"""
+
     OPT_TYPE_TIME = "OPT_TYPE_TIME"
+    """Time value option type (e.g., duration in seconds)"""
 
 
 @dataclass(frozen=True, kw_only=True)
 class FFMpegOption:
+    """
+    Represents a command-line option for FFmpeg.
+
+    This class defines the metadata for a single option that can be passed
+    to the FFmpeg command line, including its type, help text, and flags
+    that determine its behavior.
+    """
+
     name: str
+    """The name of the option as used in FFmpeg commands"""
+
     type: FFMpegOptionType
+    """The data type of the option (boolean, int, string, etc.)"""
+
     flags: int
+    """Bitmap of FFMpegOptionFlag values that define the option's behavior"""
+
     help: str
+    """Human-readable description of what the option does"""
+
     argname: str | None = None
+    """Optional name for the option's argument in help text"""
+
     canon: str | None = None
+    """For alternative option forms, the name of the canonical option"""
 
     @property
     def is_input_option(self) -> bool:
+        """
+        Check if this option applies to input files.
+
+        Returns:
+            True if this option is meant to be used with input files
+        """
         return bool(self.flags & FFMpegOptionFlag.OPT_INPUT)
 
     @property
     def is_output_option(self) -> bool:
+        """
+        Check if this option applies to output files.
+
+        Returns:
+            True if this option is meant to be used with output files
+        """
         return bool(self.flags & FFMpegOptionFlag.OPT_OUTPUT)
 
     @property
     def is_global_option(self) -> bool:
+        """
+        Check if this option applies globally rather than to specific files.
+
+        Returns:
+            True if this option is a global option that doesn't apply to
+            specific input or output files
+        """
         return (
             not self.is_input_option
             and not self.is_output_option
@@ -321,4 +593,13 @@ class FFMpegOption:
 
     @property
     def is_support_stream_specifier(self) -> bool:
+        """
+        Check if this option supports stream specifiers.
+
+        Stream specifiers allow options to be applied to specific streams
+        within a file, using syntax like "-c:v" for video codec.
+
+        Returns:
+            True if this option can be used with stream specifiers
+        """
         return bool(self.flags & FFMpegOptionFlag.OPT_SPEC)