typed-ffmpeg-compatible 3.5.1__py3-none-any.whl → 3.6__py3-none-any.whl

typed_ffmpeg/codecs/schema.py

@@ -1,17 +1,11 @@
-from dataclasses import dataclass
+"""FFmpeg codec schema definitions."""
 
-from ..common.serialize import Serializable
-from ..utils.frozendict import FrozenDict
+from ..schema import FFMpegOptionGroup
 
 
-@dataclass(frozen=True, kw_only=True)
-class FFMpegCodecOption(Serializable):
-    kwargs: FrozenDict[str, str | int | float | bool] = FrozenDict({})
+class FFMpegEncoderOption(FFMpegOptionGroup):
+    """FFmpeg encoder option group."""
 
 
-@dataclass(frozen=True, kw_only=True)
-class FFMpegEncoderOption(FFMpegCodecOption): ...
-
-
-@dataclass(frozen=True, kw_only=True)
-class FFMpegDecoderOption(FFMpegCodecOption): ...
+class FFMpegDecoderOption(FFMpegOptionGroup):
+    """FFmpeg decoder option group."""

typed_ffmpeg/common/__init__.py

@@ -0,0 +1 @@
+"""FFmpeg common utilities package."""

typed_ffmpeg/common/cache.py

@@ -1,3 +1,5 @@
+"""Cache utilities for FFmpeg operations."""
+
 from pathlib import Path
 from typing import TypeVar
 
@@ -11,7 +13,7 @@ cache_path.mkdir(exist_ok=True)
 
 def load(cls: type[T], id: str) -> T:
     """
-    Load an object from the cache
+    Load an object from the cache.
 
     Args:
         cls: The class of the object
@@ -19,6 +21,7 @@ def load(cls: type[T], id: str) -> T:
 
     Returns:
         The loaded object
+
     """
     path = cache_path / f"{cls.__name__}/{id}.json"
 
@@ -29,11 +32,12 @@ def load(cls: type[T], id: str) -> T:
 
 def save(obj: T, id: str) -> None:
     """
-    Save an object to the cache
+    Save an object to the cache.
 
     Args:
         obj: The object to save
         id: The id of the object
+
     """
     schema_path = cache_path / f"{obj.__class__.__name__}"
     schema_path.mkdir(exist_ok=True)
@@ -44,13 +48,14 @@ def save(obj: T, id: str) -> None:
 
 def list_all(cls: type[T]) -> list[T]:
     """
-    List all objects of a class in the cache
+    List all objects of a class in the cache.
 
     Args:
         cls: The class of the objects
 
     Returns:
         A list of all objects of the class in the cache
+
     """
     path = cache_path / f"{cls.__name__}"
 
@@ -58,9 +63,7 @@ def list_all(cls: type[T]) -> list[T]:
 
 
 def clean(cls: type[T]) -> None:
-    """
-    Clean the cache for a class
-    """
+    """Clean the cache for a class."""
     path = cache_path / f"{cls.__name__}"
     for i in path.glob("*.json"):
         i.unlink()

typed_ffmpeg/common/schema.py

@@ -275,6 +275,7 @@ class FFMpegFilter(Serializable):
 
         Returns:
             A dictionary mapping parameter names to their values
+
         """
         return dict(self.pre)
 
@@ -288,6 +289,7 @@ class FFMpegFilter(Serializable):
 
         Returns:
             A simplified FFMpegFilterDef representation of this filter
+
         """
         return FFMpegFilterDef(
             name=self.name,
@@ -310,6 +312,7 @@ class FFMpegFilter(Serializable):
 
         Raises:
             AssertionError: If a dynamic input filter has no input formula
+
         """
         if self.is_filter_source:
             return set()
@@ -346,6 +349,7 @@ class FFMpegFilter(Serializable):
 
         Raises:
             AssertionError: If a dynamic output filter has no output formula
+
         """
         if self.is_filter_sink:
             return set()
@@ -386,6 +390,7 @@ class FFMpegFilter(Serializable):
                        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
@@ -423,6 +428,8 @@ class FFMpegFilter(Serializable):
 
 @serializable
 class FFMpegOptionFlag(int, Enum):
+    """FFmpeg option flags that define option behavior and characteristics."""
+
     OPT_FUNC_ARG = 1 << 0
     """
     The OPT_TYPE_FUNC option takes an argument.
@@ -567,6 +574,7 @@ class FFMpegOption(Serializable):
 
         Returns:
             True if this option is meant to be used with input files
+
         """
         return bool(self.flags & FFMpegOptionFlag.OPT_INPUT)
 
@@ -577,6 +585,7 @@ class FFMpegOption(Serializable):
 
         Returns:
             True if this option is meant to be used with output files
+
         """
         return bool(self.flags & FFMpegOptionFlag.OPT_OUTPUT)
 
@@ -588,6 +597,7 @@ class FFMpegOption(Serializable):
         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
@@ -605,5 +615,6 @@ class FFMpegOption(Serializable):
 
         Returns:
             True if this option can be used with stream specifiers
+
         """
         return bool(self.flags & FFMpegOptionFlag.OPT_SPEC)

typed_ffmpeg/common/serialize.py

@@ -37,6 +37,7 @@ def serializable(
 
     Returns:
         The class itself
+
     """
     assert cls.__name__ not in CLASS_REGISTRY, (
         f"Class {cls.__name__} already registered"
@@ -47,11 +48,10 @@ def serializable(
 
 
 class Serializable:
-    """
-    A base class for all serializable classes.
-    """
+    """A base class for all serializable classes."""
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Register the subclass in the serialization registry."""
         super().__init_subclass__(**kwargs)
         serializable(cls)
 
@@ -79,6 +79,7 @@ def load_class(name: str) -> type[Serializable] | type[Enum]:
         # Create an instance
         node = FilterNode(name='scale', ...)
         ```
+
     """
     assert name in CLASS_REGISTRY, f"Class {name} not registered"
     return CLASS_REGISTRY[name]
@@ -102,11 +103,13 @@ def frozen(v: Any) -> Any:
     Example:
         ```python
         # Convert a nested structure to immutable form
-        frozen_data = frozen(
-            {"options": ["option1", "option2"], "settings": {"key": "value"}}
-        )
+        frozen_data = frozen({
+            "options": ["option1", "option2"],
+            "settings": {"key": "value"},
+        })
         # Result: FrozenDict with tuple instead of list and nested FrozenDict
         ```
+
     """
     if isinstance(v, list):
         return tuple(frozen(i) for i in v)
@@ -141,6 +144,7 @@ def object_hook(obj: Any) -> Any:
         }
         # Will be converted to a FilterNode instance
         ```
+
     """
     if isinstance(obj, dict):
         if obj.get("__class__"):
@@ -176,6 +180,7 @@ def loads(raw: str) -> Any:
         filter_node = loads(json_str)
         # filter_node is now a FilterNode instance
         ```
+
     """
     return json.loads(raw, object_hook=object_hook)
 
@@ -202,8 +207,8 @@ def to_dict_with_class_info(instance: Any) -> Any:
         serializable = to_dict_with_class_info(filter_node)
         # serializable now contains class information and all attributes
         ```
-    """
 
+    """
     if isinstance(instance, dict | FrozenDict):
         return {k: to_dict_with_class_info(v) for k, v in instance.items()}
     elif isinstance(instance, list):
@@ -251,6 +256,7 @@ def dumps(instance: Any) -> str:
         # json_str can be saved to a file and later deserialized
         # with loads() to reconstruct the original object
         ```
+
     """
     obj = to_dict_with_class_info(instance)
     return json.dumps(obj, indent=2)

typed_ffmpeg/compile/__init__.py

@@ -0,0 +1 @@
+"""FFmpeg compilation utilities package."""

typed_ffmpeg/compile/compile_cli.py

@@ -16,8 +16,10 @@ filter graph syntax, and escaping of special characters in FFmpeg commands.
 
 from __future__ import annotations
 
+import logging
 import re
 import shlex
+import tempfile
 from collections import defaultdict
 from collections.abc import Mapping
 from dataclasses import replace
@@ -47,6 +49,8 @@ from ..utils.run import command_line
 from .context import DAGContext
 from .validate import validate
 
+logger = logging.getLogger(__name__)
+
 
 def get_options_dict() -> dict[str, FFMpegOption]:
     """
@@ -54,6 +58,7 @@ def get_options_dict() -> dict[str, FFMpegOption]:
 
     Returns:
         Dictionary mapping option names to their FFMpegOption definitions
+
     """
     options = load(list[FFMpegOption], "options")
     return {option.name: option for option in options}
@@ -65,6 +70,7 @@ def get_filter_dict() -> dict[str, FFMpegFilter]:
 
     Returns:
         Dictionary mapping filter names to their FFMpegFilter definitions
+
     """
     filters = load(list[FFMpegFilter], "filters")
     return {filter.name: filter for filter in filters}
@@ -85,6 +91,7 @@ def parse_options(tokens: list[str]) -> dict[str, list[str | None | bool]]:
 
     Returns:
         Dictionary mapping option names to lists of their values
+
     """
     parsed_options: dict[str, list[str | None | bool]] = defaultdict(list)
 
@@ -130,6 +137,8 @@ def parse_stream_selector(
 
     Raises:
         AssertionError: If the stream label is not found in the mapping
+        FFMpegValueError: If the stream type is unknown
+
     """
     selector = selector.strip("[]")
 
@@ -178,6 +187,7 @@ def _is_filename(token: str) -> bool:
 
     Returns:
         True if the token is a filename, False otherwise
+
     """
     # not start with - and has ext
     return not token.startswith("-") and len(token.split(".")) > 1
@@ -201,6 +211,7 @@ def parse_output(
 
     Returns:
         List of OutputStream objects representing the output specifications
+
     """
     tokens = source.copy()
 
@@ -268,6 +279,7 @@ def parse_input(
 
     Returns:
         Dictionary mapping input indices to their FilterableStream objects
+
     """
     output: list[AVStream] = []
 
@@ -321,6 +333,10 @@ def parse_filter_complex(
 
     Returns:
         Updated stream mapping with new filter outputs added
+
+    Raises:
+        FFMpegValueError: If the stream type is unknown
+
     """
     # Use re.split with negative lookbehind to handle escaped semicolons
     filter_units = re.split(r"(?<!\\);", filter_complex)
@@ -421,6 +437,7 @@ def parse_global(
     Example:
         For tokens like ['-y', '-loglevel', 'quiet', '-i', 'input.mp4']:
         Returns ({'y': True, 'loglevel': 'quiet'}, ['-i', 'input.mp4'])
+
     """
     options = parse_options(tokens[: tokens.index("-i")])
     remaining_tokens = tokens[tokens.index("-i") :]
@@ -462,6 +479,7 @@ def parse(cli: str) -> Stream:
             "ffmpeg -i input.mp4 -filter_complex '[0:v]scale=1280:720[v]' -map '[v]' output.mp4"
         )
         ```
+
     """
     # ffmpeg [global_options] {[input_file_options] -i input_url} ... {[output_file_options] output_url} ...
     ffmpeg_options = get_options_dict()
@@ -502,7 +520,9 @@ def parse(cli: str) -> Stream:
     return result
 
 
-def compile(stream: Stream, auto_fix: bool = True) -> str:
+def compile(
+    stream: Stream, auto_fix: bool = True, use_filter_complex_script: bool = False
+) -> str:
     """
     Compile a stream into a command-line string.
 
@@ -512,14 +532,21 @@ def compile(stream: Stream, auto_fix: bool = True) -> str:
     Args:
         stream: The Stream object to compile into a command-line string
         auto_fix: Whether to automatically fix issues in the stream
+        use_filter_complex_script: If True, use -filter_complex_script with a
+                                  temporary file instead of -filter_complex
 
     Returns:
         A command-line string that can be passed to FFmpeg
+
     """
-    return "ffmpeg " + command_line(compile_as_list(stream, auto_fix))
+    return "ffmpeg " + command_line(
+        compile_as_list(stream, auto_fix, use_filter_complex_script)
+    )
 
 
-def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
+def 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.
 
@@ -545,6 +572,8 @@ def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
        - Properly labels all streams
        - Maintains correct filter chain order
        - Handles stream splitting and merging
+       - If use_filter_complex_script is True, creates a temporary file
+         with the filter complex content and uses -filter_complex_script
 
     5. Output Files: Processes destination files
        - File paths and output options
@@ -560,6 +589,8 @@ def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
         stream: The Stream object to compile into arguments
         auto_fix: Whether to automatically fix issues in the stream
                  (e.g., reconnecting disconnected nodes)
+        use_filter_complex_script: If True, use -filter_complex_script with a
+                                  temporary file instead of -filter_complex
 
     Returns:
         A list of strings representing FFmpeg command-line arguments
@@ -580,8 +611,8 @@ def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
             args
         )  # ['ffmpeg', '-i', 'input.mp4', '-filter_complex', '...', 'output.mp4']
         ```
-    """
 
+    """
     stream = validate(stream, auto_fix=auto_fix)
     node = stream.node
     context = DAGContext.build(node)
@@ -605,7 +636,19 @@ def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
         vf_commands += ["".join(get_args(node, context))]
 
     if vf_commands:
-        commands += ["-filter_complex", ";".join(vf_commands)]
+        filter_complex_content = ";".join(vf_commands)
+
+        if use_filter_complex_script:
+            # Create a temporary file with the filter complex content
+            with tempfile.NamedTemporaryFile(
+                mode="w", suffix=".txt", delete=False
+            ) as f:
+                f.write(filter_complex_content)
+                temp_filename = f.name
+
+            commands += ["-filter_complex_script", temp_filename]
+        else:
+            commands += ["-filter_complex", filter_complex_content]
 
     # compile the output nodes
     output_nodes = [node for node in context.all_nodes if isinstance(node, OutputNode)]
@@ -643,6 +686,7 @@ def get_stream_label(stream: Stream, context: DAGContext | None = None) -> str:
 
     Raises:
         FFMpegValueError: If the stream has an unknown type or node type
+
     """
     from ..streams.audio import AudioStream
     from ..streams.av import AVStream
@@ -713,8 +757,8 @@ def get_args_filter_node(node: FilterNode, context: DAGContext) -> list[str]:
     Example:
         For a scale filter with width=1280 and height=720, this might return:
         ['[0:v]', 'scale=', 'width=1280:height=720', '[s0]']
-    """
 
+    """
     incoming_labels = "".join(f"[{get_stream_label(k, context)}]" for k in node.inputs)
     outputs = context.get_outgoing_streams(node)
 
@@ -766,6 +810,7 @@ def get_args_input_node(node: InputNode, context: DAGContext) -> list[str]:
     Example:
         For an input file "input.mp4" with options like seeking to 10 seconds:
         ['-ss', '10', '-i', 'input.mp4']
+
     """
     commands = []
     for key, value in node.kwargs.items():
@@ -799,6 +844,7 @@ def get_args_output_node(node: OutputNode, context: DAGContext) -> list[str]:
     Example:
         For an output file "output.mp4" with H.264 video codec:
         ['-map', '[v0]', '-c:v', 'libx264', 'output.mp4']
+
     """
     # !handle mapping
     commands = []
@@ -860,6 +906,7 @@ def get_args_global_node(node: GlobalNode, context: DAGContext) -> list[str]:
     Example:
         For global options like overwrite and quiet logging:
         ['-y', '-loglevel', 'quiet']
+
     """
     commands = []
     for key, value in node.kwargs.items():
@@ -891,8 +938,8 @@ def get_args(node: Node, context: DAGContext | None = None) -> list[str]:
 
     Raises:
         FFMpegValueError: If the node type is not recognized
-    """
 
+    """
     context = context or DAGContext.build(node)
 
     match node:
@@ -927,8 +974,8 @@ def get_node_label(node: Node, context: DAGContext) -> str:
 
     Raises:
         AssertionError: If the node is not an InputNode or FilterNode
-    """
 
+    """
     node_id = context.node_ids[node]
     match node:
         case InputNode():

typed_ffmpeg/compile/compile_json.py

@@ -1,3 +1,5 @@
+"""JSON compilation utilities for FFmpeg streams."""
+
 from ..common.serialize import dumps, loads
 from ..dag.schema import Stream
 from .validate import validate
@@ -16,6 +18,7 @@ def compile(stream: Stream, auto_fix: bool = True) -> str:
 
     Returns:
         A JSON string that can be passed to FFmpeg
+
     """
     stream = validate(stream, auto_fix=auto_fix)
 
@@ -34,5 +37,6 @@ def parse(json: str) -> Stream:
 
     Returns:
         A Stream object
+
     """
     return loads(json)

typed_ffmpeg/compile/compile_python.py

@@ -1,3 +1,5 @@
+"""Python code compilation utilities for FFmpeg streams."""
+
 from __future__ import annotations
 
 from collections.abc import Mapping
@@ -39,6 +41,7 @@ def filter_stream_typed_index(
 
     Returns:
         The index of the matched stream in the outgoing streams of the node.
+
     """
     matched_outgoing_streams = [
         k
@@ -69,6 +72,10 @@ def get_input_var_name(
 
     Returns:
         The input variable name for the stream.
+
+    Raises:
+        ValueError: If the stream type is unknown
+
     """
     match stream:
         case AVStream():
@@ -127,6 +134,10 @@ def get_output_var_name(node: Node, context: DAGContext) -> str:
 
     Returns:
         The output variable name for the node.
+
+    Raises:
+        ValueError: If the node type is unknown
+
     """
     match node:
         case InputNode():
@@ -153,6 +164,7 @@ def compile_kwargs(kwargs: Mapping[str, Any]) -> str:
 
     Returns:
         The compiled kwargs.
+
     """
     return ", ".join(f"{k}={repr(v)}" for k, v in kwargs.items())
 
@@ -169,6 +181,7 @@ def compile_fluent(code: list[str]) -> list[str]:
 
     Returns:
         The compiled code.
+
     """
     buffer = [k.split("=", 1)[:2] for k in code]
 
@@ -209,6 +222,7 @@ def compile(stream: Stream, auto_fix: bool = True, fluent: bool = True) -> str:
 
     Returns:
         The compiled python code.
+
     """
     stream = validate(stream, auto_fix=auto_fix)
     node = stream.node
@@ -314,6 +328,7 @@ def parse(code: str) -> Stream:
 
     Returns:
         The parsed stream.
+
     """
     local_vars: dict[str, Any] = {}
     exec(code, {}, local_vars)

typed_ffmpeg/compile/context.py

@@ -35,6 +35,7 @@ def _remove_duplicates(seq: Iterable[T]) -> list[T]:
 
     Returns:
         A new list with duplicates removed, preserving the original order
+
     """
     seen = set()
     output: list[T] = []
@@ -62,6 +63,7 @@ def _collect(node: Node) -> tuple[list[Node], list[Stream]]:
         A tuple containing two lists:
         - A list of all nodes in the upstream path (including the starting node)
         - A list of all streams connecting these nodes
+
     """
     nodes: list[Node] = [node]
     streams: list[Stream] = list(node.inputs)
@@ -124,6 +126,7 @@ class DAGContext:
 
         Returns:
             A fully initialized DAGContext containing all nodes and streams in the graph
+
         """
         nodes, streams = _collect(node)
 
@@ -144,6 +147,7 @@ class DAGContext:
 
         Returns:
             A sorted list of all nodes in the graph
+
         """
         return sorted(self.nodes, key=lambda node: len(node.upstream_nodes))
 
@@ -159,6 +163,7 @@ class DAGContext:
 
         Returns:
             A sorted list of all streams in the graph
+
         """
         return sorted(
             self.streams,
@@ -177,6 +182,7 @@ class DAGContext:
 
         Returns:
             A dictionary mapping streams to their destination nodes and connection indices
+
         """
         outgoing_nodes: dict[Stream, list[tuple[Node, int]]] = defaultdict(list)
 
@@ -197,8 +203,8 @@ class DAGContext:
 
         Returns:
             A dictionary mapping nodes to their output streams
-        """
 
+        """
         outgoing_streams: dict[Node, list[Stream]] = defaultdict(list)
 
         for stream in self.streams:
@@ -210,10 +216,13 @@ class DAGContext:
     def node_ids(self) -> dict[Node, int]:
         """
         Get a mapping of nodes to their unique integer IDs.
+
         This property assigns a unique integer ID to each node in the graph,
         based on the node type and its position in the processing chain.
+
         Returns:
-            A dictionary mapping nodes to their unique integer IDs
+            A dictionary mapping nodes to their unique integer IDs.
+
         """
         node_index: dict[type[Node], int] = defaultdict(int)
         node_ids: dict[Node, int] = {}
@@ -239,8 +248,8 @@ class DAGContext:
 
         Returns:
             A dictionary mapping nodes to their string labels
-        """
 
+        """
         input_node_index = 0
         filter_node_index = 0
         node_labels: dict[Node, str] = {}
@@ -271,6 +280,7 @@ class DAGContext:
 
         Returns:
             A list of (node, input_index) tuples for nodes that receive this stream
+
         """
         return self.outgoing_nodes[stream]
 
@@ -292,8 +302,8 @@ class DAGContext:
 
         Raises:
             AssertionError: If the node is not an InputNode or FilterNode
-        """
 
+        """
         return self.node_labels[node]
 
     @override
@@ -311,5 +321,6 @@ class DAGContext:
 
         Returns:
             A list of streams that originate from this node
+
         """
         return self.outgoing_streams[node]