typed-ffmpeg-compatible 3.0.1__py3-none-any.whl → 3.2.1__py3-none-any.whl

typed_ffmpeg/__init__.py

@@ -26,8 +26,8 @@ from . import compile, dag, filters, sources
 from .base import afilter, filter_multi_output, input, merge_outputs, output, vfilter
 from .dag import Stream
 from .exceptions import FFMpegExecuteError, FFMpegTypeError, FFMpegValueError
+from .ffprobe.probe import probe, probe_obj
 from .info import get_codecs, get_decoders, get_encoders
-from .probe import probe
 from .streams import AudioStream, AVStream, VideoStream
 
 __all__ = [
@@ -41,6 +41,7 @@ __all__ = [
     "FFMpegValueError",
     "Stream",
     "probe",
+    "probe_obj",
     "compile",
     "AudioStream",
     "VideoStream",

typed_ffmpeg/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '3.2.1'
+__version_tuple__ = version_tuple = (3, 2, 1)

typed_ffmpeg/compile/compile_cli.py

@@ -16,10 +16,29 @@ filter graph syntax, and escaping of special characters in FFmpeg commands.
 
 from __future__ import annotations
 
-from ..dag.nodes import FilterableStream, FilterNode, GlobalNode, InputNode, OutputNode
+import re
+import shlex
+from collections import defaultdict
+from collections.abc import Mapping
+
+from ..base import input, merge_outputs, output
+from ..common.cache import load
+from ..common.schema import FFMpegFilter, FFMpegFilterDef, FFMpegOption, StreamType
+from ..dag.factory import filter_node_factory
+from ..dag.nodes import (
+    FilterableStream,
+    FilterNode,
+    GlobalNode,
+    InputNode,
+    OutputNode,
+    OutputStream,
+)
 from ..dag.schema import Node, Stream
 from ..exceptions import FFMpegValueError
 from ..schema import Default
+from ..streams.audio import AudioStream
+from ..streams.av import AVStream
+from ..streams.video import VideoStream
 from ..utils.escaping import escape
 from ..utils.lazy_eval.schema import LazyValue
 from ..utils.run import command_line
@@ -27,6 +46,350 @@ from .context import DAGContext
 from .validate import validate
 
 
+def get_options_dict() -> dict[str, FFMpegOption]:
+    options = load(list[FFMpegOption], "options")
+    return {option.name: option for option in options}
+
+
+def get_filter_dict() -> dict[str, FFMpegFilter]:
+    filters = load(list[FFMpegFilter], "filters")
+    return {filter.name: filter for filter in filters}
+
+
+def parse_options(tokens: list[str]) -> dict[str, list[str | None | bool]]:
+    """
+    Parse FFmpeg command-line options into a structured dictionary.
+
+    This function processes a list of command-line tokens and converts them into
+    a dictionary where keys are option names (without the leading '-') and values
+    are lists of their corresponding values. Boolean options are handled specially:
+    - '-option' becomes {'option': [None]}
+    - '-nooption' becomes {'option': [False]}
+
+    Args:
+        tokens: List of command-line tokens to parse
+
+    Returns:
+        Dictionary mapping option names to lists of their values
+    """
+    parsed_options: dict[str, list[str | None | bool]] = defaultdict(list)
+
+    while tokens:
+        assert tokens[0][0] == "-", f"Expected option, got {tokens[0]}"
+        if len(tokens) == 1 or tokens[1][0] == "-":
+            if tokens[0].startswith("-no"):
+                # Handle boolean options with -no prefix
+                option_name = tokens[0][3:]
+                parsed_options[option_name] = [False]
+            else:
+                # Handle boolean options without value
+                option_name = tokens[0][1:]
+                parsed_options[option_name] = [None]
+            tokens = tokens[1:]
+        else:
+            # Handle options with values
+            option_name = tokens[0][1:]
+            option_value = tokens[1]
+            parsed_options[option_name].append(option_value)
+            tokens = tokens[2:]
+
+    return parsed_options
+
+
+def parse_stream_selector(
+    selector: str, mapping: Mapping[str, FilterableStream]
+) -> FilterableStream:
+    selector = selector.strip("[]")
+
+    if ":" in selector:
+        stream_label, _ = selector.split(":", 1)
+    else:
+        stream_label = selector
+
+    assert stream_label in mapping, f"Unknown stream label: {stream_label}"
+    stream = mapping[stream_label]
+
+    if isinstance(stream, AVStream):
+        if selector.count(":") == 1:
+            stream_label, stream_type = selector.split(":", 1)
+            return stream.video if stream_type == "v" else stream.audio
+        elif selector.count(":") == 2:
+            stream_label, stream_type, stream_index = selector.split(":", 2)
+            return (
+                stream.video_stream(int(stream_index))
+                if stream_type == "v"
+                else stream.audio_stream(int(stream_index))
+            )
+        else:
+            return stream
+    else:
+        return stream
+
+
+def parse_output(
+    source: list[str],
+    in_streams: Mapping[str, FilterableStream],
+    ffmpeg_options: dict[str, FFMpegOption],
+) -> list[OutputStream]:
+    tokens = source.copy()
+
+    export: list[OutputStream] = []
+
+    buffer: list[str] = []
+    while tokens:
+        token = tokens.pop(0)
+        if token.startswith("-") or len(buffer) % 2 == 1:
+            buffer.append(token)
+            continue
+
+        filename = token
+        options = parse_options(buffer)
+
+        map_options = options.pop("map", [])
+        inputs: list[FilterableStream] = []
+        for map_option in map_options:
+            assert isinstance(map_option, str), f"Expected map option, got {map_option}"
+            stream = parse_stream_selector(map_option, in_streams)
+            inputs.append(stream)
+
+        if not inputs:
+            # NOTE: if there is no inputs, and there is only one input node
+            if len([k for k in in_streams if isinstance(in_streams[k], AVStream)]) == 1:
+                inputs = [
+                    in_streams[k]
+                    for k in in_streams
+                    if isinstance(in_streams[k], AVStream)
+                ]
+
+        assert inputs, f"No inputs found for output {filename}"
+        export.append(output(*inputs, filename=filename, extra_options=options))
+        buffer = []
+
+    return export
+
+
+def parse_input(
+    tokens: list[str], ffmpeg_options: dict[str, FFMpegOption]
+) -> dict[str, FilterableStream]:
+    output: list[AVStream] = []
+
+    while "-i" in tokens:
+        index = tokens.index("-i")
+        filename = tokens[index + 1]
+        assert filename[0] != "-", f"Expected filename, got {filename}"
+
+        input_options_args = tokens[:index]
+
+        options = parse_options(input_options_args)
+        parameters: dict[str, str | bool] = {}
+
+        for key, value in options.items():
+            assert key in ffmpeg_options, f"Unknown option: {key}"
+            option = ffmpeg_options[key]
+
+            if option.is_input_option:
+                # just ignore not input options
+                if value[-1] is None:
+                    parameters[key] = True
+                else:
+                    parameters[key] = value[-1]
+
+        output.append(input(filename=filename, extra_options=parameters))
+
+        tokens = tokens[index + 2 :]
+
+    return {str(idx): stream for idx, stream in enumerate(output)}
+
+
+def parse_filter_complex(
+    filter_complex: str,
+    stream_mapping: dict[str, FilterableStream],
+    ffmpeg_filters: dict[str, FFMpegFilter],
+) -> dict[str, FilterableStream]:
+    """
+    Parse an FFmpeg filter_complex string into a stream mapping.
+
+    This function processes a filter_complex string (e.g. "[0:v]scale=1280:720[v0]")
+    and converts it into a mapping of stream labels to their corresponding
+    FilterableStream objects. It handles:
+    - Input stream references (e.g. [0:v])
+    - Filter definitions with parameters
+    - Output stream labels (e.g. [v0])
+
+    Args:
+        filter_complex: The filter_complex string to parse
+        stream_mapping: Existing mapping of stream labels to streams
+        ffmpeg_filters: Dictionary of available FFmpeg filters
+
+    Returns:
+        Updated stream mapping with new filter outputs added
+    """
+    filter_units = filter_complex.split(";")
+
+    for filter_unit in filter_units:
+        pattern = re.compile(
+            r"""
+            (?P<inputs>(\[[^\[\]]+\])*)          # inputs: zero or more [label]
+            (?P<filter>[a-zA-Z0-9_]+)            # filter name
+            (=?(?P<params>[^[]+?))?              # optional =params (until next [ or end)
+            (?P<outputs>(\[[^\[\]]+\])*)$        # outputs: zero or more [label] at end
+            """,
+            re.VERBOSE,
+        )
+
+        match = pattern.match(filter_unit)
+        assert match, f"Invalid filter unit: {filter_unit}"
+
+        def extract_labels(label_str: str) -> list[str]:
+            return re.findall(r"\[([^\[\]]+)\]", label_str)
+
+        input_labels = extract_labels(match.group("inputs") or "")
+        output_labels = extract_labels(match.group("outputs") or "")
+        filter_name = match.group("filter")
+        param_str = match.group("params")
+
+        # Parse filter parameters into key-value pairs
+        filter_params = {}
+        if param_str:
+            param_parts = param_str.strip().split(":")
+            for part in param_parts:
+                if "=" in part:
+                    key, value = part.split("=", 1)
+                    filter_params[key.strip()] = value.strip()
+
+        assert isinstance(filter_name, str), f"Expected filter name, got {filter_name}"
+        ffmpeg_filter = ffmpeg_filters[filter_name]
+        filter_def = FFMpegFilterDef(
+            name=ffmpeg_filter.name,
+            typings_input=ffmpeg_filter.formula_typings_input
+            or tuple(k.type.value for k in ffmpeg_filter.stream_typings_input),
+            typings_output=ffmpeg_filter.formula_typings_output
+            or tuple(k.type.value for k in ffmpeg_filter.stream_typings_output),
+        )
+        input_streams = [
+            parse_stream_selector(label, stream_mapping) for label in input_labels
+        ]
+
+        # Create the filter node with default options and parsed parameters
+        filter_node = filter_node_factory(
+            filter_def,
+            *input_streams,
+            **(
+                {k.name: Default(k.default) for k in ffmpeg_filter.options}
+                | filter_params
+            ),
+        )
+
+        # Map output streams to their labels
+        for idx, (output_label, output_typing) in enumerate(
+            zip(output_labels, filter_node.output_typings)
+        ):
+            if output_typing == StreamType.video:
+                stream_mapping[output_label] = VideoStream(node=filter_node, index=idx)
+            elif output_typing == StreamType.audio:
+                stream_mapping[output_label] = AudioStream(node=filter_node, index=idx)
+            else:
+                raise FFMpegValueError(f"Unknown stream type: {output_typing}")
+
+    return stream_mapping
+
+
+def parse_global(
+    tokens: list[str], ffmpeg_options: dict[str, FFMpegOption]
+) -> tuple[dict[str, str | bool], list[str]]:
+    """
+    Parse global FFmpeg options from command-line tokens.
+
+    This function processes the global options that appear before any input files
+    in the FFmpeg command line. These options affect the entire FFmpeg process,
+    such as log level, overwrite flags, etc.
+
+    Args:
+        tokens: List of command-line tokens to parse
+        ffmpeg_options: Dictionary of valid FFmpeg options
+
+    Returns:
+        A tuple containing:
+        - Dictionary of parsed global options and their values
+        - Remaining tokens after global options are consumed
+
+    Example:
+        For tokens like ['-y', '-loglevel', 'quiet', '-i', 'input.mp4']:
+        Returns ({'y': True, 'loglevel': 'quiet'}, ['-i', 'input.mp4'])
+    """
+    global_params: dict[str, str | bool] = {}
+    remaining_tokens = tokens.copy()
+
+    # Process tokens until we hit an input file marker (-i)
+    while remaining_tokens and remaining_tokens[0] != "-i":
+        if remaining_tokens[0].startswith("-"):
+            option_name = remaining_tokens[0][1:]
+            assert option_name in ffmpeg_options, (
+                f"Unknown global option: {option_name}"
+            )
+            option = ffmpeg_options[option_name]
+
+            if not option.is_global_option:
+                continue
+
+            if len(remaining_tokens) > 1 and not remaining_tokens[1].startswith("-"):
+                # Option with value
+                global_params[option_name] = remaining_tokens[1]
+                remaining_tokens = remaining_tokens[2:]
+            else:
+                # Boolean option
+                if option_name.startswith("no"):
+                    global_params[option_name[2:]] = False
+                else:
+                    global_params[option_name] = True
+                remaining_tokens = remaining_tokens[1:]
+        else:
+            # Skip non-option tokens
+            remaining_tokens = remaining_tokens[1:]
+
+    return global_params, remaining_tokens
+
+
+def parse(cli: str) -> Stream:
+    # ffmpeg [global_options] {[input_file_options] -i input_url} ... {[output_file_options] output_url} ...
+    ffmpeg_options = get_options_dict()
+    ffmpeg_filters = get_filter_dict()
+
+    tokens = shlex.split(cli)
+    assert tokens[0] == "ffmpeg"
+    tokens = tokens[1:]
+
+    # Parse global options first
+    global_params, remaining_tokens = parse_global(tokens, ffmpeg_options)
+
+    # find the index of the last -i option
+    index = len(remaining_tokens) - 1 - list(reversed(remaining_tokens)).index("-i")
+    input_streams = parse_input(remaining_tokens[: index + 2], ffmpeg_options)
+    remaining_tokens = remaining_tokens[index + 2 :]
+
+    if "-filter_complex" in remaining_tokens:
+        index = remaining_tokens.index("-filter_complex")
+        filter_complex = remaining_tokens[index + 1]
+        filterable_streams = parse_filter_complex(
+            filter_complex, input_streams, ffmpeg_filters
+        )
+        remaining_tokens = remaining_tokens[index + 2 :]
+    else:
+        filterable_streams = {}
+
+    output_streams = parse_output(
+        remaining_tokens,
+        input_streams | filterable_streams,
+        ffmpeg_options,
+    )
+
+    # Create a stream with global options
+    result = merge_outputs(*output_streams)
+    if global_params:
+        result = result.global_args(extra_options=global_params)
+    return result
+
+
 def compile(stream: Stream, auto_fix: bool = True) -> str:
     """
     Compile a stream into a command-line string.
@@ -41,7 +404,7 @@ def compile(stream: Stream, auto_fix: bool = True) -> str:
     Returns:
         A command-line string that can be passed to FFmpeg
     """
-    return command_line(compile_as_list(stream, auto_fix))
+    return "ffmpeg " + command_line(compile_as_list(stream, auto_fix))
 
 
 def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
@@ -50,15 +413,36 @@ def compile_as_list(stream: Stream, auto_fix: bool = True) -> list[str]:
 
     This function takes a Stream object representing an FFmpeg filter graph
     and converts it into a list of command-line arguments that can be passed
-    to FFmpeg. It processes the graph in the correct order:
-    1. Global nodes (general FFmpeg options)
-    2. Input nodes (input files and their options)
-    3. Filter nodes (combined into a -filter_complex argument)
-    4. Output nodes (output files and their options)
+    to FFmpeg. The compilation process follows these steps:
+
+    1. Validation: The graph is validated to ensure it's properly formed
+       - Checks for cycles in the graph
+       - Verifies stream types match filter requirements
+       - Ensures all streams are properly connected
+
+    2. Global Options: Processes global FFmpeg settings
+       - Log level, overwrite flags, etc.
+       - These affect the entire FFmpeg process
+
+    3. Input Files: Handles source media files
+       - File paths and input-specific options
+       - Stream selection and format options
+       - Timestamp and duration settings
+
+    4. Filter Graph: Combines all filters into a -filter_complex argument
+       - Properly labels all streams
+       - Maintains correct filter chain order
+       - Handles stream splitting and merging
+
+    5. Output Files: Processes destination files
+       - File paths and output options
+       - Codec and format settings
+       - Stream mapping and selection
 
-    The function validates the graph before compilation to ensure it's properly
-    formed. If auto_fix is enabled, it will attempt to fix common issues like
-    disconnected nodes or invalid stream mappings.
+    If auto_fix is enabled, the function will attempt to fix common issues:
+    - Reconnecting disconnected nodes
+    - Adding missing split filters
+    - Fixing stream type mismatches
 
     Args:
         stream: The Stream object to compile into arguments
@@ -214,10 +598,10 @@ def get_args_filter_node(node: FilterNode, context: DAGContext) -> list[str]:
     outputs = context.get_outgoing_streams(node)
 
     outgoing_labels = ""
-    for output in sorted(outputs, key=lambda stream: stream.index or 0):
+    for _output in sorted(outputs, key=lambda stream: stream.index or 0):
         # NOTE: all outgoing streams must be filterable
-        assert isinstance(output, FilterableStream)
-        outgoing_labels += f"[{get_stream_label(output, context)}]"
+        assert isinstance(_output, FilterableStream)
+        outgoing_labels += f"[{get_stream_label(_output, context)}]"
 
     commands = []
     for key, value in node.kwargs.items():
@@ -301,6 +685,22 @@ def get_args_output_node(node: OutputNode, context: DAGContext) -> list[str]:
     if context:
         for input in node.inputs:
             if isinstance(input.node, InputNode):
+                # NOTE: specially rules,
+                # if there is only one input node,
+                # only one output node,
+                # the output node has only one input,
+                # and the stream selector is not specified,
+                # then the map can be ignore.
+                if (
+                    input.index is None
+                    and isinstance(input, AVStream)
+                    and len([k for k in context.all_nodes if isinstance(k, InputNode)])
+                    == 1
+                    and len([k for k in context.all_nodes if isinstance(k, OutputNode)])
+                    == 1
+                    and len(node.inputs) == 1
+                ):
+                    continue
                 commands += ["-map", get_stream_label(input, context)]
             else:
                 commands += ["-map", f"[{get_stream_label(input, context)}]"]

typed_ffmpeg/compile/compile_python.py

@@ -3,10 +3,6 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Any
 
-from ffmpeg.streams.audio import AudioStream
-from ffmpeg.streams.av import AVStream
-from ffmpeg.streams.video import VideoStream
-
 from ..common.cache import load
 from ..common.schema import FFMpegFilter
 from ..dag.nodes import (
@@ -19,6 +15,9 @@ from ..dag.nodes import (
     OutputStream,
 )
 from ..dag.schema import Node, Stream
+from ..streams.audio import AudioStream
+from ..streams.av import AVStream
+from ..streams.video import VideoStream
 from .context import DAGContext
 from .validate import validate
 

typed_ffmpeg/ffprobe/parse.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+
+import json
+import types
+from dataclasses import is_dataclass
+from typing import (
+    Any,
+    TypeGuard,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .schema import ffprobeType, registered_types
+from .xml2json import xml_string_to_json
+
+T = TypeVar("T")
+
+
+def _get_actual_type(type_hint: Any) -> type[Any]:
+    """
+    Get the actual type from a type hint, handling Optional and Union (including | syntax).
+
+    Args:
+        type_hint: The type hint to get the actual type from
+
+    Returns:
+        The actual type
+    """
+    # If type_hint is a string, evaluate it in the schema's module context
+    if isinstance(type_hint, str):
+        type_hint = registered_types[type_hint]
+
+    origin = get_origin(type_hint)
+    # Handle typing.Union and types.UnionType (for int | None in Python 3.10+)
+    if origin is Union or (hasattr(types, "UnionType") and origin is types.UnionType):
+        non_none_types = [t for t in get_args(type_hint) if t is not type(None)]
+        if non_none_types:
+            return _get_actual_type(non_none_types[0])
+    # Handle direct types.UnionType (for int | None in Python 3.10+)
+    if hasattr(types, "UnionType") and isinstance(type_hint, types.UnionType):
+        non_none_types = [t for t in type_hint.__args__ if t is not type(None)]
+        if non_none_types:
+            return _get_actual_type(non_none_types[0])
+    return type_hint
+
+
+def is_dataclass_type(obj: type[Any]) -> TypeGuard[type[T]]:
+    """
+    Check if an object is a dataclass type.
+
+    Args:
+        obj: The object to check
+
+    Returns:
+        True if the object is a dataclass type, False otherwise
+    """
+    return is_dataclass(obj)
+
+
+def _parse_obj_from_dict(data: Any, cls: type[T]) -> T | None:
+    """
+    Parse a dictionary into a dataclass instance.
+
+    Args:
+        data: The dictionary to parse
+        cls: The dataclass to parse into
+
+    Returns:
+        The parsed dataclass instance
+    """
+
+    if data is None:
+        return None
+
+    if isinstance(cls, type):
+        if cls is str:
+            return cast(T, str(data))
+        elif cls is int:
+            return cast(T, int(data))
+        elif cls is float:
+            return cast(T, float(data))
+        elif cls is bool:
+            return cast(T, bool(data))
+
+    if not isinstance(data, dict):
+        return cls()
+
+    if isinstance(cls, str):  # NOTE: python 3.10
+        cls = registered_types[cls]
+
+    type_hints = get_type_hints(cls)
+    kwargs: dict[str, Any] = {}
+
+    for field_name, field_type in type_hints.items():
+        actual_type = _get_actual_type(field_type)
+
+        if get_origin(actual_type) is tuple:
+            tuple_args = get_args(actual_type)
+            if not tuple_args:
+                continue
+            item_type = tuple_args[0]
+            value = data.get(field_name, [])
+            if not isinstance(value, list):
+                value = [value]
+            kwargs[field_name] = tuple(
+                _parse_obj_from_dict(item, item_type) for item in value
+            )
+            continue
+
+        kwargs[field_name] = _parse_obj_from_dict(data.get(field_name), actual_type)
+
+    return cls(**kwargs)
+
+
+def parse_ffprobe(xml_string: str) -> ffprobeType:
+    """
+    Parse ffprobe XML output into ffprobeType dataclass using JSON dict.
+
+    Args:
+        xml_string: The XML string to parse
+
+    Returns:
+        The parsed ffprobeType instance
+    """
+    json_str = xml_string_to_json(xml_string)
+    json_dict = json.loads(json_str)
+    # The root key is 'ffprobe'
+    root_data = json_dict.get("ffprobe", json_dict)
+    return _parse_obj_from_dict(root_data, ffprobeType) or ffprobeType()