API Reference — Sync

The following reference is generated directly from the package's Google-style docstrings via mkdocstrings.

Builder

ffmpeg_wrap.input

input(filename: str | PathLike[str], ffmpeg_path: str = 'ffmpeg', **kwargs: Any) -> FFmpeg

Start a new FFmpeg chain with an input file.

This is the recommended entry point for building a fluent chain. It creates a fresh :class:FFmpeg instance and calls :meth:~FFmpeg.input on it.

Parameters:

Name	Type	Description	Default
filename	str | PathLike[str]	Input filesystem path or special ffmpeg input string.	required
ffmpeg_path	str	Path to the ffmpeg executable. Defaults to "ffmpeg" (resolved from PATH).	'ffmpeg'
**kwargs	Any	FFmpeg input options passed through to the input slot (e.g. ss=30, t=60).	{}

Returns:

Type	Description
FFmpeg	A new :class:FFmpeg instance with the input added, ready for further
FFmpeg	chaining.

Example

from ffmpeg_wrap import input

input("in.mkv", ss=30, t=60).output("clip.mp4").codec("v", "copy").run()

Source code in src/ffmpeg_wrap/_builder.py

def input(filename: str | PathLike[str], ffmpeg_path: str = "ffmpeg", **kwargs: Any) -> FFmpeg:
    """Start a new FFmpeg chain with an input file.

    This is the recommended entry point for building a fluent chain. It creates
    a fresh :class:`FFmpeg` instance and calls :meth:`~FFmpeg.input` on it.

    Args:
        filename: Input filesystem path or special ffmpeg input string.
        ffmpeg_path: Path to the ffmpeg executable. Defaults to ``"ffmpeg"``
            (resolved from ``PATH``).
        **kwargs: FFmpeg input options passed through to the input slot
            (e.g. ``ss=30``, ``t=60``).

    Returns:
        A new :class:`FFmpeg` instance with the input added, ready for further
        chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv", ss=30, t=60).output("clip.mp4").codec("v", "copy").run()
        ```
    """
    instance = FFmpeg(ffmpeg_path=ffmpeg_path)
    return instance.input(filename, **kwargs)

ffmpeg_wrap.FFmpeg

FFmpeg(ffmpeg_path: str = 'ffmpeg')

A fluent interface wrapper for ffmpeg.

Build an ffmpeg command incrementally via method chaining and execute it with :meth:run (sync) or :meth:arun (async). Every builder method returns self so calls can be chained in a single expression.

Parameters:

Name	Type	Description	Default
ffmpeg_path	str	Path to the ffmpeg executable. Defaults to "ffmpeg", which relies on the executable being present on PATH. Pass an absolute path to pin a specific build.	'ffmpeg'

Example

from ffmpeg_wrap import input

out, _ = (
    input("in.mkv")
    .output("out.mp4")
    .codec("v", "libx264")
    .codec("a", "aac")
    .overwrite_output()
    .run(capture_stderr=True, text=True)
)

Initialise the FFmpeg command builder.

Parameters:

Name	Type	Description	Default
ffmpeg_path	str	Path to the ffmpeg executable. Defaults to "ffmpeg" (resolved from PATH). Pass an absolute path to target a specific ffmpeg build, e.g. "/usr/local/bin/ffmpeg".	'ffmpeg'

Example

from ffmpeg_wrap import FFmpeg

ff = FFmpeg(ffmpeg_path="/usr/local/bin/ffmpeg")
ff.input("in.mkv").output("out.mp4").run()

Source code in src/ffmpeg_wrap/_builder.py

def __init__(self, ffmpeg_path: str = "ffmpeg") -> None:
    """Initialise the FFmpeg command builder.

    Args:
        ffmpeg_path: Path to the ffmpeg executable. Defaults to
            ``"ffmpeg"`` (resolved from ``PATH``). Pass an absolute path
            to target a specific ffmpeg build, e.g.
            ``"/usr/local/bin/ffmpeg"``.

    Example:
        ```python
        from ffmpeg_wrap import FFmpeg

        ff = FFmpeg(ffmpeg_path="/usr/local/bin/ffmpeg")
        ff.input("in.mkv").output("out.mp4").run()
        ```
    """
    self._inputs: list[dict[str, Any]] = []
    self._outputs: list[dict[str, Any]] = []
    self._global_args: list[str] = []
    self._filter_graph_args: list[str] = []
    self._overwrite: bool = False
    self._ffmpeg_path: str = ffmpeg_path

compile

compile() -> list[str]

Build the FFmpeg command as a list of arguments without executing it.

Returns:

Type	Description
list[str]	The command as a list of strings.

Example

from ffmpeg_wrap import input

cmd = input("in.mkv").output("out.mp4").codec("v", "copy").compile()
# ['ffmpeg', '-i', '/abs/path/in.mkv', '-c:v', 'copy', 'out.mp4']
print(cmd)

Source code in src/ffmpeg_wrap/_builder.py

def compile(self) -> list[str]:
    """Build the FFmpeg command as a list of arguments without executing it.

    Returns:
        The command as a list of strings.

    Example:
        ```python
        from ffmpeg_wrap import input

        cmd = input("in.mkv").output("out.mp4").codec("v", "copy").compile()
        # ['ffmpeg', '-i', '/abs/path/in.mkv', '-c:v', 'copy', 'out.mp4']
        print(cmd)
        ```
    """
    cmd = [self._ffmpeg_path]

    if self._overwrite:
        cmd.append("-y")

    cmd.extend(self._global_args)

    cmd.extend(self._filter_graph_args)

    for inp in self._inputs:
        for k, v in inp["kwargs"].items():
            cmd.extend(_convert_arg(k, v))
        cmd.extend(["-i", str(inp["filename"])])

    for out in self._outputs:
        for k, v in out["kwargs"].items():
            cmd.extend(_convert_arg(k, v))
        cmd.append(str(out["filename"]))

    return cmd

input

input(filename: str | PathLike[str], **kwargs: Any) -> FFmpeg

Add an input file with optional arguments.

Parameters:

Name	Type	Description	Default
filename	str | PathLike[str]	Input filesystem path or special ffmpeg input string.	required
**kwargs	Any	FFmpeg input options (e.g., t=10).	{}

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import FFmpeg

ff = FFmpeg().input("clip.mkv", ss=30, t=60)
# Emits: -ss 30 -t 60 -i clip.mkv

Source code in src/ffmpeg_wrap/_builder.py

def input(self, filename: str | PathLike[str], **kwargs: Any) -> FFmpeg:
    """Add an input file with optional arguments.

    Args:
        filename: Input filesystem path or special ffmpeg input string.
        **kwargs: FFmpeg input options (e.g., t=10).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import FFmpeg

        ff = FFmpeg().input("clip.mkv", ss=30, t=60)
        # Emits: -ss 30 -t 60 -i clip.mkv
        ```
    """
    filename_str = filename if isinstance(filename, str) else str(Path(filename))
    self._inputs.append({"filename": filename_str, "kwargs": kwargs})
    return self

output

output(filename: str | PathLike[str], **kwargs: Any) -> FFmpeg

Add an output file with optional arguments.

Parameters:

Name	Type	Description	Default
filename	str | PathLike[str]	Output filesystem path or special ffmpeg output string.	required
**kwargs	Any	FFmpeg output options (e.g., c="copy", ac=2).	{}

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4", c="copy", ac=2)

Source code in src/ffmpeg_wrap/_builder.py

def output(self, filename: str | PathLike[str], **kwargs: Any) -> FFmpeg:
    """Add an output file with optional arguments.

    Args:
        filename: Output filesystem path or special ffmpeg output string.
        **kwargs: FFmpeg output options (e.g., c="copy", ac=2).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4", c="copy", ac=2)
        ```
    """
    filename_str = filename if isinstance(filename, str) else str(Path(filename))
    self._outputs.append({"filename": filename_str, "kwargs": kwargs})
    return self

map

map(*specs: str | Stream) -> FFmpeg

Add one or more -map specifiers to the current output.

Accepts raw specifier strings ("0:v") and Stream objects. For a Stream, the per-type specifier (e.g. 0:s:0) is used, computed from probe data rather than the raw absolute index.

Parameters:

Name	Type	Description	Default
*specs	str | Stream	Map specifiers as strings or Stream objects.	()

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input, probe

result = probe("in.mkv")
video = next(s for s in result.streams if s.is_video)
input("in.mkv").output("out.mkv").map("0:a", video)

Source code in src/ffmpeg_wrap/_builder.py

def map(self, *specs: str | Stream) -> FFmpeg:
    """Add one or more ``-map`` specifiers to the current output.

    Accepts raw specifier strings (``"0:v"``) and ``Stream`` objects. For a
    ``Stream``, the per-type specifier (e.g. ``0:s:0``) is used, computed
    from probe data rather than the raw absolute index.

    Args:
        *specs: Map specifiers as strings or ``Stream`` objects.

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input, probe

        result = probe("in.mkv")
        video = next(s for s in result.streams if s.is_video)
        input("in.mkv").output("out.mkv").map("0:a", video)
        ```
    """
    tokens = [spec.map_specifier() if isinstance(spec, Stream) else str(spec) for spec in specs]
    self._append_output_list("map", tokens)
    return self

map_stream

map_stream(kind: str, ordinal: int, input: int = 0) -> FFmpeg

Add a per-type -map specifier to the current output.

Parameters:

Name	Type	Description	Default
kind	str	Stream-type letter (e.g. "v", "a", "s").	required
ordinal	int	Zero-based index within that stream type.	required
input	int	Index of the ffmpeg input to map from.	0

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

# Map first video and second audio stream from input 0
input("in.mkv").output("out.mkv").map_stream("v", 0).map_stream("a", 1)

Source code in src/ffmpeg_wrap/_builder.py

def map_stream(self, kind: str, ordinal: int, input: int = 0) -> FFmpeg:
    """Add a per-type ``-map`` specifier to the current output.

    Args:
        kind: Stream-type letter (e.g. ``"v"``, ``"a"``, ``"s"``).
        ordinal: Zero-based index within that stream type.
        input: Index of the ffmpeg input to map from.

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        # Map first video and second audio stream from input 0
        input("in.mkv").output("out.mkv").map_stream("v", 0).map_stream("a", 1)
        ```
    """
    self._append_output_list("map", [f"{input}:{kind}:{ordinal}"])
    return self

hwaccel

hwaccel(name: str) -> FFmpeg

Request a hardware-acceleration backend on the current input.

Discoverable sugar for input(..., hwaccel=name): emits -hwaccel {name} before the current input's -i (e.g. hwaccel("cuda") -> -hwaccel cuda -i in.mkv).

Parameters:

Name	Type	Description	Default
name	str	Hardware-acceleration backend (e.g. "cuda", "vaapi").	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import FFmpeg

ff = FFmpeg().input("in.mkv").hwaccel("cuda").output("out.mp4")
# Emits: -hwaccel cuda -i in.mkv out.mp4

Source code in src/ffmpeg_wrap/_builder.py

def hwaccel(self, name: str) -> FFmpeg:
    """Request a hardware-acceleration backend on the current input.

    Discoverable sugar for ``input(..., hwaccel=name)``: emits
    ``-hwaccel {name}`` before the current input's ``-i`` (e.g.
    ``hwaccel("cuda")`` -> ``-hwaccel cuda -i in.mkv``).

    Args:
        name: Hardware-acceleration backend (e.g. ``"cuda"``, ``"vaapi"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import FFmpeg

        ff = FFmpeg().input("in.mkv").hwaccel("cuda").output("out.mp4")
        # Emits: -hwaccel cuda -i in.mkv out.mp4
        ```
    """
    self._set_input_option("hwaccel", name)
    return self

codec

codec(kind: str, name: str) -> FFmpeg

Set the codec for a stream type on the current output.

Emits -c:{kind} {name} (e.g. codec("v", "libx265") -> -c:v libx265).

Parameters:

Name	Type	Description	Default
kind	str	Stream-type letter (e.g. "v", "a", "s").	required
name	str	Codec name (e.g. "libx265", "copy").	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").codec("v", "libx264").codec("a", "aac")

Source code in src/ffmpeg_wrap/_builder.py

def codec(self, kind: str, name: str) -> FFmpeg:
    """Set the codec for a stream type on the current output.

    Emits ``-c:{kind} {name}`` (e.g. ``codec("v", "libx265")`` ->
    ``-c:v libx265``).

    Args:
        kind: Stream-type letter (e.g. ``"v"``, ``"a"``, ``"s"``).
        name: Codec name (e.g. ``"libx265"``, ``"copy"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").codec("v", "libx264").codec("a", "aac")
        ```
    """
    self._set_output_option(f"c:{kind}", name)
    return self

bitrate

bitrate(kind: str, value: str | int) -> FFmpeg

Set the bitrate for a stream type on the current output.

Emits -b:{kind} {value} (e.g. bitrate("v", "2M") -> -b:v 2M).

Parameters:

Name	Type	Description	Default
kind	str	Stream-type letter (e.g. "v", "a").	required
value	str | int	Bitrate value (e.g. "2M", 128000).	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").codec("v", "libx264").bitrate("v", "2M")

Source code in src/ffmpeg_wrap/_builder.py

def bitrate(self, kind: str, value: str | int) -> FFmpeg:
    """Set the bitrate for a stream type on the current output.

    Emits ``-b:{kind} {value}`` (e.g. ``bitrate("v", "2M")`` ->
    ``-b:v 2M``).

    Args:
        kind: Stream-type letter (e.g. ``"v"``, ``"a"``).
        value: Bitrate value (e.g. ``"2M"``, ``128000``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").codec("v", "libx264").bitrate("v", "2M")
        ```
    """
    self._set_output_option(f"b:{kind}", value)
    return self

quality

quality(kind: str, value: str | int) -> FFmpeg

Set the quality scale for a stream type on the current output.

Emits -q:{kind} {value} (e.g. quality("a", 2) -> -q:a 2).

Parameters:

Name	Type	Description	Default
kind	str	Stream-type letter (e.g. "v", "a").	required
value	str | int	Quality value.	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp3").codec("a", "libmp3lame").quality("a", 2)

Source code in src/ffmpeg_wrap/_builder.py

def quality(self, kind: str, value: str | int) -> FFmpeg:
    """Set the quality scale for a stream type on the current output.

    Emits ``-q:{kind} {value}`` (e.g. ``quality("a", 2)`` -> ``-q:a 2``).

    Args:
        kind: Stream-type letter (e.g. ``"v"``, ``"a"``).
        value: Quality value.

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp3").codec("a", "libmp3lame").quality("a", 2)
        ```
    """
    self._set_output_option(f"q:{kind}", value)
    return self

audio_filter

audio_filter(chain: str) -> FFmpeg

Set the audio filter chain on the current output.

Emits -filter:a {chain}.

Parameters:

Name	Type	Description	Default
chain	str	Filter chain string (e.g. "loudnorm").	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mkv").audio_filter("loudnorm")

Source code in src/ffmpeg_wrap/_builder.py

def audio_filter(self, chain: str) -> FFmpeg:
    """Set the audio filter chain on the current output.

    Emits ``-filter:a {chain}``.

    Args:
        chain: Filter chain string (e.g. ``"loudnorm"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mkv").audio_filter("loudnorm")
        ```
    """
    self._set_output_option("filter:a", chain)
    return self

video_filter

video_filter(chain: str) -> FFmpeg

Set the video filter chain on the current output.

Emits -filter:v {chain}.

Parameters:

Name	Type	Description	Default
chain	str	Filter chain string (e.g. "scale=1280:-2").	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").video_filter("scale=1280:-2")

Source code in src/ffmpeg_wrap/_builder.py

def video_filter(self, chain: str) -> FFmpeg:
    """Set the video filter chain on the current output.

    Emits ``-filter:v {chain}``.

    Args:
        chain: Filter chain string (e.g. ``"scale=1280:-2"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").video_filter("scale=1280:-2")
        ```
    """
    self._set_output_option("filter:v", chain)
    return self

flag

flag(*names: str) -> FFmpeg

Add one or more valueless switches to the current output.

Emits a bare -{name} token per name (e.g. flag("vn", "sn") -> -vn -sn). This is the intentional way to request a switch; note the contrast with output(..., vn=None), which omits the flag entirely.

Parameters:

Name	Type	Description	Default
*names	str	Switch names without the leading dash (e.g. "vn").	()

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

# Extract audio only: suppress video and subtitle streams
input("in.mkv").output("out.aac").flag("vn", "sn")

Source code in src/ffmpeg_wrap/_builder.py

def flag(self, *names: str) -> FFmpeg:
    """Add one or more valueless switches to the current output.

    Emits a bare ``-{name}`` token per name (e.g. ``flag("vn", "sn")`` ->
    ``-vn -sn``). This is the intentional way to request a switch; note the
    contrast with ``output(..., vn=None)``, which *omits* the flag entirely.

    Args:
        *names: Switch names without the leading dash (e.g. ``"vn"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        # Extract audio only: suppress video and subtitle streams
        input("in.mkv").output("out.aac").flag("vn", "sn")
        ```
    """
    for name in names:
        self._set_output_option(name, True)
    return self

overwrite_output

overwrite_output() -> FFmpeg

Add the -y flag to overwrite output files without prompting.

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").overwrite_output().run()

Source code in src/ffmpeg_wrap/_builder.py

def overwrite_output(self) -> FFmpeg:
    """Add the ``-y`` flag to overwrite output files without prompting.

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").overwrite_output().run()
        ```
    """
    self._overwrite = True
    return self

global_args

global_args(*args: str) -> FFmpeg

Add raw global arguments emitted before input options.

Parameters:

Name	Type	Description	Default
*args	str	Global arguments (e.g. "-nostdin", "-benchmark").	()

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").global_args("-nostdin", "-benchmark")

Source code in src/ffmpeg_wrap/_builder.py

def global_args(self, *args: str) -> FFmpeg:
    """Add raw global arguments emitted before input options.

    Args:
        *args: Global arguments (e.g. ``"-nostdin"``, ``"-benchmark"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").global_args("-nostdin", "-benchmark")
        ```
    """
    self._global_args.extend(args)
    return self

hide_banner

hide_banner() -> FFmpeg

Add the -hide_banner global flag.

Thin sugar over :meth:global_args; emitted in the global slot.

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").hide_banner().run()

Source code in src/ffmpeg_wrap/_builder.py

def hide_banner(self) -> FFmpeg:
    """Add the ``-hide_banner`` global flag.

    Thin sugar over :meth:`global_args`; emitted in the global slot.

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").hide_banner().run()
        ```
    """
    self._global_args.append("-hide_banner")
    return self

loglevel

loglevel(level: str) -> FFmpeg

Set the ffmpeg log level via -loglevel {level}.

Thin sugar over :meth:global_args; emitted in the global slot.

Parameters:

Name	Type	Description	Default
level	str	Log level (e.g. "error", "warning", "verbose").	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").output("out.mp4").loglevel("error").run()

Source code in src/ffmpeg_wrap/_builder.py

def loglevel(self, level: str) -> FFmpeg:
    """Set the ffmpeg log level via ``-loglevel {level}``.

    Thin sugar over :meth:`global_args`; emitted in the global slot.

    Args:
        level: Log level (e.g. ``"error"``, ``"warning"``, ``"verbose"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").output("out.mp4").loglevel("error").run()
        ```
    """
    self._global_args.extend(["-loglevel", level])
    return self

filter_complex

filter_complex(graph_str: str) -> FFmpeg

Set a graph-level -filter_complex filtergraph.

Emits -filter_complex <graph_str> in a dedicated slot after global args and before inputs, so placement no longer depends on parking the option on an output. Mutually exclusive with :meth:filter_complex_script at runtime (not enforced here).

Parameters:

Name	Type	Description	Default
graph_str	str	The filtergraph string (e.g. "[0:v]split=2[a][b]").	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

(
    input("in.mkv")
    .filter_complex("[0:v]split=2[a][b];[a]scale=640:-2[out]")
    .output("out.mp4", map="[out]")
)

Source code in src/ffmpeg_wrap/_builder.py

def filter_complex(self, graph_str: str) -> FFmpeg:
    """Set a graph-level ``-filter_complex`` filtergraph.

    Emits ``-filter_complex <graph_str>`` in a dedicated slot after global
    args and before inputs, so placement no longer depends on parking the
    option on an output. Mutually exclusive with
    :meth:`filter_complex_script` at runtime (not enforced here).

    Args:
        graph_str: The filtergraph string (e.g.
            ``"[0:v]split=2[a][b]"``).

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        (
            input("in.mkv")
            .filter_complex("[0:v]split=2[a][b];[a]scale=640:-2[out]")
            .output("out.mp4", map="[out]")
        )
        ```
    """
    self._filter_graph_args = ["-filter_complex", graph_str]
    return self

filter_complex_script

filter_complex_script(path: str | PathLike[str]) -> FFmpeg

Read a graph-level filtergraph from a UTF-8 file.

Reads the file when this method is called and emits its contents via -filter_complex in the same dedicated slot as :meth:filter_complex (after global args, before inputs). Mutually exclusive with :meth:filter_complex at runtime (not enforced here).

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Path to a file containing the filtergraph.	required

Returns:

Type	Description
FFmpeg	Self for chaining.

Example

from ffmpeg_wrap import input

input("in.mkv").filter_complex_script("graph.txt").output("out.mp4").run()

Source code in src/ffmpeg_wrap/_builder.py

def filter_complex_script(self, path: str | PathLike[str]) -> FFmpeg:
    """Read a graph-level filtergraph from a UTF-8 file.

    Reads the file when this method is called and emits its contents via
    ``-filter_complex`` in the same dedicated slot as :meth:`filter_complex`
    (after global args, before inputs). Mutually exclusive with
    :meth:`filter_complex` at runtime (not enforced here).

    Args:
        path: Path to a file containing the filtergraph.

    Returns:
        Self for chaining.

    Example:
        ```python
        from ffmpeg_wrap import input

        input("in.mkv").filter_complex_script("graph.txt").output("out.mp4").run()
        ```
    """
    graph_str = Path(path).read_text(encoding="utf-8")
    self._filter_graph_args = ["-filter_complex", graph_str]
    return self

run

run(capture_stdout: bool = ..., capture_stderr: bool = ..., *, text: Literal[False] = ..., timeout: float | None = ...) -> tuple[bytes | None, bytes | None]

run(capture_stdout: bool = ..., capture_stderr: bool = ..., *, text: Literal[True], timeout: float | None = ...) -> tuple[str | None, str | None]

run(capture_stdout: bool = False, capture_stderr: bool = False, *, text: bool = False, timeout: float | None = None) -> tuple[bytes | None, bytes | None] | tuple[str | None, str | None]

Build and execute the FFmpeg command.

Parameters:

Name	Type	Description	Default
capture_stdout	bool	Whether to capture stdout.	False
capture_stderr	bool	Whether to capture stderr.	False
text	bool	When True, decode stdout/stderr (and FFmpegError.stderr) as text using the platform default encoding; otherwise return raw bytes.	False
timeout	float | None	Wall-clock limit in seconds, or None (the default) for no limit. When it expires the child is killed and reaped, then :class:~ffmpeg_wrap.FFmpegTimeoutError is raised.	None

Returns:

Type	Description
tuple[bytes | None, bytes | None] | tuple[str | None, str | None]	Tuple of (stdout, stderr). Values are str when text=True
tuple[bytes | None, bytes | None] | tuple[str | None, str | None]	else bytes when the corresponding capture flag is True, or
tuple[bytes | None, bytes | None] | tuple[str | None, str | None]	None otherwise.

Raises:

Type	Description
FFmpegError	If ffmpeg fails.
FFmpegTimeoutError	If timeout expires before ffmpeg exits.
ValueError	If timeout is not a positive finite number of at most 2147483.647 seconds.

Example

import ffmpeg_wrap as ffmpeg

try:
    _, stderr = (
        ffmpeg.input("in.mkv")
        .output("out.mp4")
        .overwrite_output()
        .run(capture_stderr=True, text=True)
    )
except ffmpeg.FFmpegError as e:
    print(e.returncode, e.stderr)

Source code in src/ffmpeg_wrap/_builder.py

def run(
    self,
    capture_stdout: bool = False,
    capture_stderr: bool = False,
    *,
    text: bool = False,
    timeout: float | None = None,
) -> tuple[bytes | None, bytes | None] | tuple[str | None, str | None]:
    """Build and execute the FFmpeg command.

    Args:
        capture_stdout: Whether to capture stdout.
        capture_stderr: Whether to capture stderr.
        text: When True, decode stdout/stderr (and ``FFmpegError.stderr``)
            as text using the platform default encoding; otherwise return
            raw bytes.
        timeout: Wall-clock limit in seconds, or ``None`` (the default) for
            no limit. When it expires the child is killed and reaped, then
            :class:`~ffmpeg_wrap.FFmpegTimeoutError` is raised.

    Returns:
        Tuple of (stdout, stderr). Values are ``str`` when ``text=True``
        else ``bytes`` when the corresponding capture flag is True, or
        None otherwise.

    Raises:
        FFmpegError: If ffmpeg fails.
        FFmpegTimeoutError: If ``timeout`` expires before ffmpeg exits.
        ValueError: If ``timeout`` is not a positive finite number of at most 2147483.647 seconds.

    Example:
        ```python
        import ffmpeg_wrap as ffmpeg

        try:
            _, stderr = (
                ffmpeg.input("in.mkv")
                .output("out.mp4")
                .overwrite_output()
                .run(capture_stderr=True, text=True)
            )
        except ffmpeg.FFmpegError as e:
            print(e.returncode, e.stderr)
        ```
    """
    _validate_timeout(timeout)

    cmd = self.compile()

    stdout_dest = subprocess.PIPE if capture_stdout else None

    logger.debug(f"Running ffmpeg command: {' '.join(cmd)}")

    try:
        if capture_stderr:
            # Caller wants stderr returned: capture it directly.
            if text:
                process_text = subprocess.run(
                    cmd,
                    stdout=stdout_dest,
                    stderr=subprocess.PIPE,
                    check=True,
                    text=True,
                    timeout=timeout,
                )
                return process_text.stdout, process_text.stderr
            process_bytes = subprocess.run(
                cmd,
                stdout=stdout_dest,
                stderr=subprocess.PIPE,
                check=True,
                text=False,
                timeout=timeout,
            )
            return process_bytes.stdout, process_bytes.stderr
        # Caller does not capture stderr: tee ffmpeg's stderr to the
        # inherited stderr stream in real time (preserving the live
        # progress output of a bare ``run()``) while collecting it, so the
        # failure path can still populate ``FFmpegError.stderr`` without
        # silently buffering an entire successful run in memory.
        stdout_data = self._run_tee(cmd, stdout_dest, text, timeout)
        if isinstance(stdout_data, str):
            return stdout_data, None
        return stdout_data, None
    except subprocess.TimeoutExpired as e:
        timeout_stderr = decode_error_stderr(e.stderr, text=text, encoding=locale.getpreferredencoding(False))
        logger.error(f"FFmpeg command timed out after {e.timeout}s: {timeout_stderr or str(e)}")
        raise _build_ffmpeg_timeout_error(
            f"ffmpeg timed out after {e.timeout}s",
            timeout=e.timeout,
            stderr=timeout_stderr,
            cmd=cmd,
        ) from e
    except subprocess.CalledProcessError as e:
        if e.stderr is None:
            stderr_text: str | None = None
        elif isinstance(e.stderr, str):
            stderr_text = e.stderr
        else:
            stderr_text = e.stderr.decode("utf-8", errors="replace")
        err_msg = stderr_text or str(e)
        logger.error(f"FFmpeg command failed: {err_msg}")
        raise _build_ffmpeg_error(
            f"ffmpeg error: {err_msg}",
            stderr=stderr_text,
            returncode=e.returncode,
            cmd=cmd,
        ) from e
    except OSError as e:
        logger.error(f"ffmpeg could not be executed: {e}")
        raise _build_ffmpeg_error(f"ffmpeg could not be executed: {e}", cmd=cmd) from e

arun async

arun(capture_stdout: bool = ..., capture_stderr: bool = ..., *, text: Literal[False] = ..., timeout: float | None = ...) -> tuple[bytes | None, bytes | None]

arun(capture_stdout: bool = ..., capture_stderr: bool = ..., *, text: Literal[True], timeout: float | None = ...) -> tuple[str | None, str | None]

arun(capture_stdout: bool = False, capture_stderr: bool = False, *, text: bool = False, timeout: float | None = None) -> tuple[bytes | None, bytes | None] | tuple[str | None, str | None]

Build and execute the FFmpeg command asynchronously.

Async mirror of :meth:run, powered by AnyIO via the optional [async] extra. The return contract is identical to :meth:run. Importing this module never imports anyio — the dependency is pulled in lazily here, so ffmpeg_wrap.aio (and thus anyio) is only loaded when arun is actually awaited.

Parameters:

Name	Type	Description	Default
capture_stdout	bool	Whether to capture stdout.	False
capture_stderr	bool	Whether to capture stderr.	False
text	bool	When True, decode stdout/stderr (and FFmpegError.stderr) leniently as text using the platform default encoding.	False
timeout	float | None	Wall-clock limit in seconds, or None (the default) for no limit; see :func:ffmpeg_wrap.aio.run.	None

Returns:

Type	Description
tuple[bytes | None, bytes | None] | tuple[str | None, str | None]	Tuple of (stdout, stderr); see :meth:run.

Raises:

Type	Description
FFmpegError	If ffmpeg fails or cannot be executed.
FFmpegTimeoutError	If timeout expires before ffmpeg exits.
ValueError	If timeout is not a positive finite number of at most 2147483.647 seconds.
ImportError	If the optional [async] extra is not installed.

Example

import anyio
from ffmpeg_wrap import input

async def main():
    _, stderr = await (
        input("in.mkv")
        .output("out.mp4")
        .overwrite_output()
        .arun(capture_stderr=True, text=True)
    )

anyio.run(main)

Source code in src/ffmpeg_wrap/_builder.py

async def arun(
    self,
    capture_stdout: bool = False,
    capture_stderr: bool = False,
    *,
    text: bool = False,
    timeout: float | None = None,
) -> tuple[bytes | None, bytes | None] | tuple[str | None, str | None]:
    """Build and execute the FFmpeg command asynchronously.

    Async mirror of :meth:`run`, powered by AnyIO via the optional
    ``[async]`` extra. The return contract is identical to :meth:`run`.
    Importing this module never imports anyio — the dependency is pulled in
    lazily here, so ``ffmpeg_wrap.aio`` (and thus anyio) is only loaded when
    ``arun`` is actually awaited.

    Args:
        capture_stdout: Whether to capture stdout.
        capture_stderr: Whether to capture stderr.
        text: When True, decode stdout/stderr (and ``FFmpegError.stderr``)
            leniently as text using the platform default encoding.
        timeout: Wall-clock limit in seconds, or ``None`` (the default) for
            no limit; see :func:`ffmpeg_wrap.aio.run`.

    Returns:
        Tuple of (stdout, stderr); see :meth:`run`.

    Raises:
        FFmpegError: If ffmpeg fails or cannot be executed.
        FFmpegTimeoutError: If ``timeout`` expires before ffmpeg exits.
        ValueError: If ``timeout`` is not a positive finite number of at most 2147483.647 seconds.
        ImportError: If the optional ``[async]`` extra is not installed.

    Example:
        ```python
        import anyio
        from ffmpeg_wrap import input

        async def main():
            _, stderr = await (
                input("in.mkv")
                .output("out.mp4")
                .overwrite_output()
                .arun(capture_stderr=True, text=True)
            )

        anyio.run(main)
        ```
    """
    from ffmpeg_wrap import aio

    return await aio.run(self, capture_stdout, capture_stderr, text=text, timeout=timeout)

Probing

ffmpeg_wrap.probe

probe(filename: str | PathLike[str], ffprobe_path: str = 'ffprobe', *, timeout: float | None = None) -> ProbeResult

Run ffprobe on the specified file and return typed output.

Parameters:

Name	Type	Description	Default
filename	str | PathLike[str]	Path to the file to probe.	required
ffprobe_path	str	Path to the ffprobe executable.	'ffprobe'
timeout	float | None	Wall-clock limit in seconds, or None (the default) for no limit. When it expires the child is killed and reaped, then :class:~ffmpeg_wrap.FFmpegTimeoutError is raised.	None

Returns:

Type	Description
ProbeResult	Parsed and typed :class:ProbeResult containing all streams and
ProbeResult	container format information.

Raises:

Type	Description
FFmpegError	If ffprobe fails or the output cannot be parsed.
FFmpegTimeoutError	If timeout expires before ffprobe exits.
ValueError	If timeout is not a positive finite number of at most 2147483.647 seconds.

Example

import ffmpeg_wrap as ffmpeg

result = ffmpeg.probe("video.mkv")
print(result.format.format_name if result.format else None)
for stream in result.streams:
    print(stream.index, stream.codec_type, stream.codec_name)

Source code in src/ffmpeg_wrap/_probe.py

def probe(
    filename: str | PathLike[str],
    ffprobe_path: str = "ffprobe",
    *,
    timeout: float | None = None,
) -> ProbeResult:
    """Run ffprobe on the specified file and return typed output.

    Args:
        filename: Path to the file to probe.
        ffprobe_path: Path to the ffprobe executable.
        timeout: Wall-clock limit in seconds, or ``None`` (the default) for
            no limit. When it expires the child is killed and reaped, then
            :class:`~ffmpeg_wrap.FFmpegTimeoutError` is raised.

    Returns:
        Parsed and typed :class:`ProbeResult` containing all streams and
        container format information.

    Raises:
        FFmpegError: If ffprobe fails or the output cannot be parsed.
        FFmpegTimeoutError: If ``timeout`` expires before ffprobe exits.
        ValueError: If ``timeout`` is not a positive finite number of at most 2147483.647 seconds.

    Example:
        ```python
        import ffmpeg_wrap as ffmpeg

        result = ffmpeg.probe("video.mkv")
        print(result.format.format_name if result.format else None)
        for stream in result.streams:
            print(stream.index, stream.codec_type, stream.codec_name)
        ```
    """
    _validate_timeout(timeout)
    cmd = _build_probe_cmd(filename, ffprobe_path)
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            check=True,
            text=False,
            timeout=timeout,
        )
    except subprocess.TimeoutExpired as e:
        raise _probe_timeout_error(cmd, e) from e
    except subprocess.CalledProcessError as e:
        stderr_text = e.stderr.decode("utf-8", errors="replace") if e.stderr else None
        err_msg = stderr_text or str(e)
        logger.error(f"ffprobe failed: {err_msg}")
        raise _build_ffmpeg_error(
            f"ffprobe error: {err_msg}",
            stderr=stderr_text,
            returncode=e.returncode,
            cmd=cmd,
        ) from e
    except OSError as e:
        logger.error(f"ffprobe could not be executed: {e}")
        raise _build_ffmpeg_error(f"ffprobe could not be executed: {e}", cmd=cmd) from e
    return _parse_probe_output(result.stdout, cmd)

ffmpeg_wrap.validate

validate(filename: str | PathLike[str], ffprobe_path: str = 'ffprobe', loglevel: str = 'warning', extra_args: tuple[str, ...] = (), *, timeout: float | None = None) -> tuple[bool, str]

Run ffprobe in validation mode and report diagnostics.

Does not raise on bad media — a non-zero exit or non-empty stderr is a normal outcome (returned as ok=False). This makes it safe to use as a boolean health-check without wrapping in try/except.

Parameters:

Name	Type	Description	Default
filename	str | PathLike[str]	Path to the media file or special ffmpeg input string.	required
ffprobe_path	str	Path to the ffprobe executable.	'ffprobe'
loglevel	str	Value passed to ffprobe's -v flag. Defaults to "warning" so DTS/codec warnings surface in stderr. Use "error" for a stricter check that ignores warnings, "fatal"/"panic" for only unrecoverable failures, or any other ffprobe loglevel keyword. See ffprobe -loglevel help.	'warning'
extra_args	tuple[str, ...]	Additional raw arguments forwarded to ffprobe before the filename, e.g. ("-show_format",). Use with care; no validation is performed on these args.	()
timeout	float | None	Wall-clock limit in seconds, or None (the default) for no limit. When it expires the child is killed and reaped, then :class:~ffmpeg_wrap.FFmpegTimeoutError is raised.	None

Returns:

Type	Description
bool	(ok, stderr_text) where ok is True iff the ffprobe exit
str	code is 0 and stderr.strip() is empty. stderr_text is the
tuple[bool, str]	raw decoded stderr (never None, possibly an empty string).

Raises:

Type	Description
FFmpegError	When the ffprobe executable itself cannot be run (e.g. not found on PATH). A corrupt or unreadable media file does not raise — it returns (False, stderr_text).
FFmpegTimeoutError	If timeout expires before ffprobe exits.
ValueError	If loglevel is not a recognised ffprobe loglevel keyword, or if timeout is not a positive finite number of at most 2147483.647 seconds.

Example

import ffmpeg_wrap as ffmpeg

ok, diag = ffmpeg.validate("recording.mkv")
if not ok:
    print("Validation failed:", diag)

Source code in src/ffmpeg_wrap/_probe.py

def validate(
    filename: str | PathLike[str],
    ffprobe_path: str = "ffprobe",
    loglevel: str = "warning",
    extra_args: tuple[str, ...] = (),
    *,
    timeout: float | None = None,
) -> tuple[bool, str]:
    """Run ffprobe in validation mode and report diagnostics.

    Does **not** raise on bad media — a non-zero exit or non-empty stderr is a
    normal outcome (returned as ``ok=False``). This makes it safe to use as a
    boolean health-check without wrapping in ``try/except``.

    Args:
        filename: Path to the media file or special ffmpeg input string.
        ffprobe_path: Path to the ffprobe executable.
        loglevel: Value passed to ffprobe's ``-v`` flag. Defaults to
            ``"warning"`` so DTS/codec warnings surface in stderr.
            Use ``"error"`` for a stricter check that ignores warnings,
            ``"fatal"``/``"panic"`` for only unrecoverable failures,
            or any other ffprobe loglevel keyword. See ``ffprobe -loglevel help``.
        extra_args: Additional raw arguments forwarded to ffprobe before the
            filename, e.g. ``("-show_format",)``. Use with care; no validation
            is performed on these args.
        timeout: Wall-clock limit in seconds, or ``None`` (the default) for
            no limit. When it expires the child is killed and reaped, then
            :class:`~ffmpeg_wrap.FFmpegTimeoutError` is raised.

    Returns:
        ``(ok, stderr_text)`` where ``ok`` is ``True`` iff the ffprobe exit
        code is 0 *and* ``stderr.strip()`` is empty. ``stderr_text`` is the
        raw decoded stderr (never ``None``, possibly an empty string).

    Raises:
        FFmpegError: When the ffprobe executable itself cannot be run
            (e.g. not found on ``PATH``). A corrupt or unreadable media file
            does *not* raise — it returns ``(False, stderr_text)``.
        FFmpegTimeoutError: If ``timeout`` expires before ffprobe exits.
        ValueError: If ``loglevel`` is not a recognised ffprobe loglevel
            keyword, or if ``timeout`` is not a positive finite number of at most 2147483.647 seconds.

    Example:
        ```python
        import ffmpeg_wrap as ffmpeg

        ok, diag = ffmpeg.validate("recording.mkv")
        if not ok:
            print("Validation failed:", diag)
        ```
    """
    _validate_timeout(timeout)
    cmd = _build_validate_cmd(filename, ffprobe_path, loglevel, extra_args)
    try:
        result = subprocess.run(cmd, capture_output=True, check=False, text=False, timeout=timeout)
    except subprocess.TimeoutExpired as e:
        raise _probe_timeout_error(cmd, e) from e
    except OSError as e:
        logger.error(f"ffprobe could not be executed: {e}")
        raise _build_ffmpeg_error(f"ffprobe could not be executed: {e}", cmd=cmd) from e
    return _interpret_validate(result.returncode, result.stderr)

ffmpeg_wrap.ProbeResult

Bases: Struct

Typed result of running :func:probe on a media file.

Top-level container decoded from ffprobe's -print_format json output. Provides convenient access to all streams and the container format information in a single structured object.

Attributes:

Name	Type	Description
streams	list[Stream]	All streams found in the file, in index order. Each entry is a :class:Stream with type_index populated by :func:probe.
format	Format | None	Container-level format information, or None when ffprobe did not emit a "format" section (rare for well-formed files).

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
print(result.format.format_name if result.format else None)
print([s.codec_name for s in result.streams if s.is_video])

duration_seconds

duration_seconds() -> float | None

Return the container duration as float seconds.

Delegates to self.format; returns None when format is absent or its duration is missing/non-numeric.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
secs = result.duration_seconds()
print(f"Duration: {secs:.1f}s" if secs else "Duration unknown")

Source code in src/ffmpeg_wrap/_probe.py

def duration_seconds(self) -> float | None:
    """Return the container ``duration`` as ``float`` seconds.

    Delegates to ``self.format``; returns ``None`` when ``format`` is
    absent or its ``duration`` is missing/non-numeric.

    Example:
        ```python
        from ffmpeg_wrap import probe

        result = probe("video.mkv")
        secs = result.duration_seconds()
        print(f"Duration: {secs:.1f}s" if secs else "Duration unknown")
        ```
    """
    if self.format is None:
        return None
    return self.format.duration_seconds()

ffmpeg_wrap.Stream

Bases: Struct

A single stream entry from ffprobe JSON output.

Decoded by msgspec from the ffprobe streams array. All fields except :attr:index are optional because ffprobe omits irrelevant fields per stream type (e.g. width/height are absent on audio streams).

Attributes:

Name	Type	Description
index	int	Absolute stream index within the file (0-based).
codec_name	str | None	Short codec name as reported by ffprobe (e.g. "h264", "aac", "subrip"). None if not reported.
codec_type	str | None	Stream type string (e.g. "video", "audio", "subtitle"). None if not reported. Compare against :class:CodecType members rather than raw strings.
width	int | None	Video frame width in pixels. None for non-video streams.
height	int | None	Video frame height in pixels. None for non-video streams.
channels	int | None	Number of audio channels. None for non-audio streams.
sample_rate	str | None	Audio sample rate as a string (e.g. "48000"). None for non-audio streams.
duration	str | None	Stream duration as a decimal-seconds string (e.g. "3600.123000"). None or "N/A" when unavailable.
bit_rate	str | None	Stream bit rate as a string (e.g. "128000"). None when not reported.
tags	dict[str, str] | None	Key/value metadata tags from the stream header (e.g. {"language": "eng", "title": "Commentary"}). None when no tags are present.
disposition	dict[str, int] | None	ffprobe disposition flags as a dict[str, int] (e.g. {"default": 1, "forced": 0}). None when absent.
type_index	int	Zero-based ordinal of this stream within its :attr:codec_type group (the N in the ffmpeg specifier 0:<type>:N). Set by :func:probe; defaults to 0 when a Stream is constructed outside of :func:probe.
sample_fmt	str | None	Raw ffprobe sample format name (e.g. "s16", "s32", "flt", "fltp"). None for non-audio streams or when not reported. It names the decoded sample layout, not the stored width: 24-bit PCM and 24-bit FLAC both report "s32".
bits_per_sample	int | None	Coded sample width as ffprobe's integer field (e.g. 16 for pcm_s16le, 4 for adpcm_ima_wav, 8 for pcm_mulaw). 0 when the codec has no fixed width (FLAC, MP3, Opus); None when not reported.
bits_per_raw_sample	str | None	Significant bits per decoded sample, as the string ffprobe emits (e.g. "24" for 24-bit PCM or FLAC, "16" for 16-bit FLAC). Also set on video streams as the pixel bit depth ("8" for 8-bit H.264, "10" for 10-bit). Absent (None) on most other audio codecs. Prefer :meth:bit_depth over reading the raw fields.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
for stream in result.streams:
    print(stream.index, stream.codec_type, stream.codec_name)

is_video property

is_video: bool

True iff codec_type is "video".

Returns:

Type	Description
bool	True for video streams, False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
videos = [s for s in result.streams if s.is_video]
audios = [s for s in result.streams if s.is_audio]
subs = [s for s in result.streams if s.is_subtitle]

is_audio property

is_audio: bool

True iff codec_type is "audio".

Returns:

Type	Description
bool	True for audio streams, False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
audio_streams = [s for s in result.streams if s.is_audio]

is_subtitle property

is_subtitle: bool

True iff codec_type is "subtitle".

Returns:

Type	Description
bool	True for subtitle streams, False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
subtitle_streams = [s for s in result.streams if s.is_subtitle]

is_data property

is_data: bool

True iff codec_type is "data".

Returns:

Type	Description
bool	True for data streams, False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
data_streams = [s for s in result.streams if s.is_data]

is_attachment property

is_attachment: bool

True iff codec_type is "attachment".

Returns:

Type	Description
bool	True for attachment streams, False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
attachments = [s for s in result.streams if s.is_attachment]

is_text_subtitle property

is_text_subtitle: bool

True iff this is a subtitle stream with a known text-based codec.

Best-effort: driven by a documented codec-name set (subrip, ass, ssa, ...). Unknown subtitle codecs return False.

Returns:

Type	Description
bool	True for text-based subtitle streams (SRT, ASS, WebVTT, etc.),
bool	False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
text_subs = [s for s in result.streams if s.is_text_subtitle]

is_image_subtitle property

is_image_subtitle: bool

True iff this is a subtitle stream with a known image-based codec.

Best-effort: driven by a documented codec-name set (hdmv_pgs_subtitle, dvd_subtitle, dvb_subtitle, ...). Unknown subtitle codecs return False.

Returns:

Type	Description
bool	True for bitmap/image subtitle streams (PGS, DVD, DVB, etc.),
bool	False otherwise.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
image_subs = [s for s in result.streams if s.is_image_subtitle]

bit_depth

bit_depth() -> int | None

Return the sample width in bits that ffprobe reports.

int(bits_per_raw_sample) when numeric and positive, else a positive bits_per_sample, else None. Says nothing about lossiness: adpcm_ima_wav answers 4, pcm_mulaw 8, MP3 and Opus None; video streams answer their pixel bit depth.

Returns:

Type	Description
int | None	The bit depth, or None when ffprobe reports no fixed width.

Example

from ffmpeg_wrap import probe

result = probe("audio.flac")
audio = next(s for s in result.streams if s.is_audio)
print(audio.bit_depth())  # e.g. 24

Source code in src/ffmpeg_wrap/_probe.py

def bit_depth(self) -> int | None:
    """Return the sample width in bits that ffprobe reports.

    ``int(bits_per_raw_sample)`` when numeric and positive, else a positive
    ``bits_per_sample``, else ``None``. Says nothing about lossiness:
    ``adpcm_ima_wav`` answers ``4``, ``pcm_mulaw`` ``8``, MP3 and Opus ``None``;
    video streams answer their pixel bit depth.

    Returns:
        The bit depth, or ``None`` when ffprobe reports no fixed width.

    Example:
        ```python
        from ffmpeg_wrap import probe

        result = probe("audio.flac")
        audio = next(s for s in result.streams if s.is_audio)
        print(audio.bit_depth())  # e.g. 24
        ```
    """
    raw = self.bits_per_raw_sample
    if raw is not None:
        with contextlib.suppress(ValueError):
            if (depth := int(raw)) > 0:
                return depth
    coded = self.bits_per_sample
    if coded is not None and coded > 0:
        return coded
    return None

map_specifier

map_specifier(input_index: int = 0) -> str

Return the ffmpeg -map specifier for this stream.

Emits the per-type form {input}:{letter}:{ordinal} (e.g. 0:s:0) derived from codec_type and type_index. When codec_type is unknown or None, falls back to the unambiguous absolute-index form {input}:{index}.

Parameters:

Name	Type	Description	Default
input_index	int	Index of the ffmpeg input the stream belongs to.	0

Returns:

Type	Description
str	The map specifier string.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
sub = next(s for s in result.streams if s.is_subtitle)
print(sub.map_specifier())   # e.g. "0:s:0"
print(sub.map_specifier(1))  # e.g. "1:s:0"

Source code in src/ffmpeg_wrap/_probe.py

def map_specifier(self, input_index: int = 0) -> str:
    """Return the ffmpeg ``-map`` specifier for this stream.

    Emits the per-type form ``{input}:{letter}:{ordinal}`` (e.g. ``0:s:0``)
    derived from ``codec_type`` and ``type_index``. When ``codec_type`` is
    unknown or ``None``, falls back to the unambiguous absolute-index form
    ``{input}:{index}``.

    Args:
        input_index: Index of the ffmpeg input the stream belongs to.

    Returns:
        The map specifier string.

    Example:
        ```python
        from ffmpeg_wrap import probe

        result = probe("video.mkv")
        sub = next(s for s in result.streams if s.is_subtitle)
        print(sub.map_specifier())   # e.g. "0:s:0"
        print(sub.map_specifier(1))  # e.g. "1:s:0"
        ```
    """
    letter = _STREAM_TYPE_LETTERS.get(self.codec_type or "")
    if letter is None:
        return f"{input_index}:{self.index}"
    return f"{input_index}:{letter}:{self.type_index}"

duration_seconds

duration_seconds() -> float | None

Return this stream's duration as float seconds.

Returns None when duration is missing or non-numeric (e.g. "N/A"); the raw duration string is preserved.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
for stream in result.streams:
    secs = stream.duration_seconds()
    if secs is not None:
        print(f"stream {stream.index}: {secs:.1f}s")

Source code in src/ffmpeg_wrap/_probe.py

def duration_seconds(self) -> float | None:
    """Return this stream's ``duration`` as ``float`` seconds.

    Returns ``None`` when ``duration`` is missing or non-numeric
    (e.g. ``"N/A"``); the raw ``duration`` string is preserved.

    Example:
        ```python
        from ffmpeg_wrap import probe

        result = probe("video.mkv")
        for stream in result.streams:
            secs = stream.duration_seconds()
            if secs is not None:
                print(f"stream {stream.index}: {secs:.1f}s")
        ```
    """
    return _parse_duration(self.duration)

ffmpeg_wrap.Format

Bases: Struct

The format/container section from ffprobe JSON output.

Decoded from the top-level "format" key of ffprobe's JSON output. All fields are optional because ffprobe may omit them for certain inputs.

Attributes:

Name	Type	Description
filename	str | None	Resolved path of the probed file as reported by ffprobe.
nb_streams	int | None	Total number of streams in the container.
nb_programs	int | None	Number of programs (relevant for MPEG-TS and similar).
format_name	str | None	Short format/muxer name (e.g. "matroska,webm").
format_long_name	str | None	Human-readable format name (e.g. "Matroska / WebM").
start_time	str | None	Container start time in decimal seconds (e.g. "0.000000"). None when not reported.
duration	str | None	Container duration in decimal seconds (e.g. "3600.123000"). None or "N/A" when unavailable.
size	str | None	File size in bytes as a string (e.g. "1234567890").
bit_rate	str | None	Overall container bit rate in bits/s as a string.
probe_score	int | None	ffprobe format-detection confidence score (0-100).
tags	dict[str, str] | None	Container-level metadata tags (e.g. {"title": "My Movie", "encoder": "Lavf58.76.100"}).

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
fmt = result.format
if fmt:
    print(fmt.format_name, fmt.duration_seconds())

duration_seconds

duration_seconds() -> float | None

Return the container duration as float seconds.

Returns None when duration is missing or non-numeric (e.g. "N/A"); the raw duration string is preserved.

Example

from ffmpeg_wrap import probe

result = probe("video.mkv")
if result.format:
    secs = result.format.duration_seconds()
    print(f"Duration: {secs:.1f}s" if secs else "Unknown duration")

Source code in src/ffmpeg_wrap/_probe.py

def duration_seconds(self) -> float | None:
    """Return the container ``duration`` as ``float`` seconds.

    Returns ``None`` when ``duration`` is missing or non-numeric
    (e.g. ``"N/A"``); the raw ``duration`` string is preserved.

    Example:
        ```python
        from ffmpeg_wrap import probe

        result = probe("video.mkv")
        if result.format:
            secs = result.format.duration_seconds()
            print(f"Duration: {secs:.1f}s" if secs else "Unknown duration")
        ```
    """
    return _parse_duration(self.duration)

ffmpeg_wrap.CodecType

Bases: StrEnum

The known ffprobe codec_type values.

Used for the typed predicates on :class:Stream (is_video etc.). Note that :attr:Stream.codec_type stays typed str | None rather than this enum: ffmpeg can report codec_type values outside this set, and decoding into a strict enum would raise msgspec.ValidationError on such files. Compare against these members instead of retyping the field.

Attributes:

Name	Type	Description
VIDEO		Represents a video stream ("video").
AUDIO		Represents an audio stream ("audio").
SUBTITLE		Represents a subtitle stream ("subtitle").
DATA		Represents a data stream ("data").
ATTACHMENT		Represents an attachment stream ("attachment").

Example

from ffmpeg_wrap import CodecType, probe

result = probe("video.mkv")
videos = [s for s in result.streams if s.codec_type == CodecType.VIDEO]

Encoder discovery

ffmpeg_wrap.encoders

encoders(ffmpeg_path: str = 'ffmpeg') -> frozenset[str]

Return the set of encoder names reported by ffmpeg -encoders.

The result is cached per ffmpeg_path for the lifetime of the process. Use :func:has_encoder for a single-name membership check.

Parameters:

Name	Type	Description	Default
ffmpeg_path	str	Path to the ffmpeg executable.	'ffmpeg'

Returns:

Type	Description
frozenset[str]	A frozenset of encoder names (e.g. "libx264", "h264_nvenc").

Raises:

Type	Description
FFmpegError	If ffmpeg cannot be run or exits non-zero.

Example

import ffmpeg_wrap as ffmpeg

available = ffmpeg.encoders()
print("libx264" in available)   # True if ffmpeg was compiled with it
print(sorted(available)[:5])    # first five encoder names alphabetically

Source code in src/ffmpeg_wrap/_encoders.py

def encoders(ffmpeg_path: str = "ffmpeg") -> frozenset[str]:
    """Return the set of encoder names reported by ``ffmpeg -encoders``.

    The result is cached per ``ffmpeg_path`` for the lifetime of the process.
    Use :func:`has_encoder` for a single-name membership check.

    Args:
        ffmpeg_path: Path to the ffmpeg executable.

    Returns:
        A frozenset of encoder names (e.g. ``"libx264"``, ``"h264_nvenc"``).

    Raises:
        FFmpegError: If ffmpeg cannot be run or exits non-zero.

    Example:
        ```python
        import ffmpeg_wrap as ffmpeg

        available = ffmpeg.encoders()
        print("libx264" in available)   # True if ffmpeg was compiled with it
        print(sorted(available)[:5])    # first five encoder names alphabetically
        ```
    """
    cached = _ENCODERS_CACHE.get(ffmpeg_path)
    if cached is not None:
        return cached

    cmd = _build_encoders_cmd(ffmpeg_path)
    try:
        result = subprocess.run(cmd, capture_output=True, check=True, text=True)
    except subprocess.CalledProcessError as e:
        stderr_text = e.stderr if isinstance(e.stderr, str) else None
        err_msg = stderr_text or str(e)
        logger.error(f"ffmpeg -encoders failed: {err_msg}")
        raise _build_ffmpeg_error(
            f"ffmpeg -encoders error: {err_msg}",
            stderr=stderr_text,
            returncode=e.returncode,
            cmd=cmd,
        ) from e
    except OSError as e:
        logger.error(f"ffmpeg could not be executed: {e}")
        raise _build_ffmpeg_error(f"ffmpeg could not be executed: {e}", cmd=cmd) from e

    parsed = _parse_encoders(result.stdout)
    _ENCODERS_CACHE[ffmpeg_path] = parsed
    return parsed

ffmpeg_wrap.has_encoder

has_encoder(name: str, ffmpeg_path: str = 'ffmpeg') -> bool

Return whether name is an available ffmpeg encoder.

Parameters:

Name	Type	Description	Default
name	str	Encoder name to check (e.g. "h264_nvenc").	required
ffmpeg_path	str	Path to the ffmpeg executable.	'ffmpeg'

Returns:

Type	Description
bool	True iff name appears in :func:encoders.

Raises:

Type	Description
FFmpegError	If ffmpeg cannot be run or exits non-zero.

Example

import ffmpeg_wrap as ffmpeg

if ffmpeg.has_encoder("h264_nvenc"):
    codec = "h264_nvenc"
else:
    codec = "libx264"
ffmpeg.input("in.mkv").output("out.mp4").codec("v", codec).run()

Source code in src/ffmpeg_wrap/_encoders.py

def has_encoder(name: str, ffmpeg_path: str = "ffmpeg") -> bool:
    """Return whether ``name`` is an available ffmpeg encoder.

    Args:
        name: Encoder name to check (e.g. ``"h264_nvenc"``).
        ffmpeg_path: Path to the ffmpeg executable.

    Returns:
        ``True`` iff ``name`` appears in :func:`encoders`.

    Raises:
        FFmpegError: If ffmpeg cannot be run or exits non-zero.

    Example:
        ```python
        import ffmpeg_wrap as ffmpeg

        if ffmpeg.has_encoder("h264_nvenc"):
            codec = "h264_nvenc"
        else:
            codec = "libx264"
        ffmpeg.input("in.mkv").output("out.mp4").codec("v", codec).run()
        ```
    """
    return name in encoders(ffmpeg_path)

Filters

ffmpeg_wrap.filter_arg_escape

filter_arg_escape(value: str) -> str

Escape a value for safe embedding in a filtergraph option.

ffmpeg parses a filtergraph at two levels, and a value pasted into a filter option (such as a subtitles= path) must survive both:

• The filter-option parser, where : separates options and \/' are escaping/quoting characters. A raw colon (every Windows drive path, and POSIX paths containing one) is otherwise read as an option separator, so ffmpeg mis-parses the tail (e.g. original_size). This level is handled by backslash-escaping \, ' and :.
• The filtergraph parser, where ' quotes and [],; are special. This level is handled by wrapping the whole value in single quotes; a literal ' is emitted via the close/escape/reopen idiom ('\'').

Single-quote wrapping alone is not sufficient: the colon still reaches the filter-option parser and splits the value, so the backslash escaping is required as well. The result parses back to the original value.

Typical use is building a subtitles= (or any path-bearing) filter.

Example

from ffmpeg_wrap import filter_arg_escape, input

path = "/media/My Film: Director's Cut/subs.srt"
graph = f"subtitles={filter_arg_escape(path)}"
input("in.mkv").filter_complex(graph).output("out.mp4").run()

Parameters:

Name	Type	Description	Default
value	str	The raw string to escape (e.g. a filesystem path).	required

Returns:

Type	Description
str	The escaped, single-quote-wrapped token.

Source code in src/ffmpeg_wrap/_filters.py

def filter_arg_escape(value: str) -> str:
    r"""Escape a value for safe embedding in a filtergraph option.

    ffmpeg parses a filtergraph at two levels, and a value pasted into a filter
    option (such as a ``subtitles=`` path) must survive both:

    * The *filter-option* parser, where ``:`` separates options and ``\``/``'``
      are escaping/quoting characters. A raw colon (every Windows drive path,
      and POSIX paths containing one) is otherwise read as an option separator,
      so ffmpeg mis-parses the tail (e.g. ``original_size``). This level is
      handled by backslash-escaping ``\``, ``'`` and ``:``.
    * The *filtergraph* parser, where ``'`` quotes and ``[],;`` are special.
      This level is handled by wrapping the whole value in single quotes; a
      literal ``'`` is emitted via the close/escape/reopen idiom (``'\''``).

    Single-quote wrapping alone is **not** sufficient: the colon still reaches
    the filter-option parser and splits the value, so the backslash escaping is
    required as well. The result parses back to the original ``value``.

    Typical use is building a ``subtitles=`` (or any path-bearing) filter.

    Example:
        ```python
        from ffmpeg_wrap import filter_arg_escape, input

        path = "/media/My Film: Director's Cut/subs.srt"
        graph = f"subtitles={filter_arg_escape(path)}"
        input("in.mkv").filter_complex(graph).output("out.mp4").run()
        ```

    Args:
        value: The raw string to escape (e.g. a filesystem path).

    Returns:
        The escaped, single-quote-wrapped token.
    """
    # Filter-option level: escape backslash first, then quote and colon.
    escaped = value.replace("\\", "\\\\").replace("'", "\\'").replace(":", "\\:")
    # Filtergraph level: single-quote wrap, emitting any embedded ' literally.
    return "'" + escaped.replace("'", "'\\''") + "'"

Errors

ffmpeg_wrap.FFmpegError

FFmpegError(message: str, *, stderr: str | None = None, returncode: int | None = None, cmd: list[str] | None = None)

Bases: Exception

Custom exception for FFmpeg errors.

Carries structured introspection from the underlying process failure so callers can branch on the exit code or inspect stderr without re-parsing str(e). The message remains args[0] so str(e) is unchanged.

Attributes:

Name	Type	Description
stderr		Decoded stderr from the failed process, or None if not captured. Present on both :meth:~ffmpeg_wrap.FFmpeg.run failures and :func:~ffmpeg_wrap.probe / :func:~ffmpeg_wrap.validate failures.
returncode		Process exit code, or None when the process could not be launched at all (e.g. executable not found) or when a timeout expired (see :class:FFmpegTimeoutError).
cmd		The exact command list that was executed, or None.

Example

import ffmpeg_wrap as ffmpeg

try:
    ffmpeg.input("missing.mkv").output("out.mp4").run()
except ffmpeg.FFmpegError as e:
    print("exit code:", e.returncode)
    print("command:", e.cmd)
    print("stderr:", e.stderr)

Source code in src/ffmpeg_wrap/_errors.py

def __init__(
    self,
    message: str,
    *,
    stderr: str | None = None,
    returncode: int | None = None,
    cmd: list[str] | None = None,
) -> None:
    super().__init__(message)
    self.stderr = stderr
    self.returncode = returncode
    self.cmd = cmd

ffmpeg_wrap.FFmpegTimeoutError

FFmpegTimeoutError(message: str, *, timeout: float, stderr: str | None = None, returncode: int | None = None, cmd: list[str] | None = None)

Bases: FFmpegError

Raised when timeout expires before the process exits.

The child is killed and reaped before this is raised; descendants it spawned are not. Subclasses :class:FFmpegError, so except FFmpegError still catches it. returncode is always None.

Attributes:

Name	Type	Description
timeout		The limit, in seconds, that was exceeded.
stderr		The stderr tail collected before the kill, or None.
cmd		The exact command list that was executed, or None.

Example

import ffmpeg_wrap as ffmpeg

try:
    ffmpeg.input("in.mkv").output("out.mp4").run(timeout=60)
except ffmpeg.FFmpegTimeoutError as e:
    print("gave up after", e.timeout, "seconds")

Source code in src/ffmpeg_wrap/_errors.py

def __init__(
    self,
    message: str,
    *,
    timeout: float,
    stderr: str | None = None,
    returncode: int | None = None,
    cmd: list[str] | None = None,
) -> None:
    super().__init__(message, stderr=stderr, returncode=returncode, cmd=cmd)
    self.timeout = timeout