schema

Schema definitions for FFmpeg filters and options.

This module defines the core data structures and enumerations used to represent FFmpeg filters, their options, and stream types. These schemas are used throughout the typed-ffmpeg library to provide type-safe interfaces to FFmpeg functionality.

Classes:

Name	Description
FFMpegFilter	Comprehensive representation of an FFmpeg filter with all its metadata.
FFMpegFilterDef	Defines the basic structure of an FFmpeg filter.
FFMpegFilterOption	Represents a configurable option for an FFmpeg filter.
FFMpegFilterOptionChoice	Represents a single choice for an FFmpeg filter option with enumerated values.
FFMpegFilterOptionType	Enumeration of possible data types for FFmpeg filter options.
FFMpegFilterType	Enumeration of FFmpeg filter types based on input/output stream types.
FFMpegIOType	Defines the type information for a filter's input or output stream.
FFMpegOption	Represents a command-line option for FFmpeg.
FFMpegOptionFlag	FFmpeg option flags that define option behavior and characteristics.
FFMpegOptionType	Enumeration of FFmpeg option data types.
StreamType	Enumeration of possible stream types in FFmpeg.

FFMpegFilter dataclass

FFMpegFilter(
    *,
    id: str | None = None,
    name: str,
    description: str,
    ref: str | None = None,
    is_support_slice_threading: bool | None = None,
    is_support_timeline: bool | None = None,
    is_support_framesync: bool | None = None,
    is_support_command: bool | None = None,
    is_filter_sink: bool | None = None,
    is_filter_source: bool | None = None,
    is_dynamic_input: bool = False,
    is_dynamic_output: bool = False,
    stream_typings_input: tuple[FFMpegIOType, ...] = (),
    stream_typings_output: tuple[FFMpegIOType, ...] = (),
    formula_typings_input: str | None = None,
    formula_typings_output: str | None = None,
    pre: tuple[tuple[str, str], ...] = (),
    options: tuple[FFMpegFilterOption, ...] = ()
)

Bases: Serializable

Comprehensive representation of an FFmpeg filter with all its metadata.

This class contains the complete definition of an FFmpeg filter, including its name, description, capabilities, input/output specifications, and options. It serves as the central schema for representing filters in typed-ffmpeg.

Attributes:

Name	Type	Description
description	str	Human-readable description of what the filter does
filter_type	FFMpegFilterType	Determine the FFmpeg filter type based on input and output stream types.
formula_typings_input	str | None	Optional formula to dynamically determine input types
formula_typings_output	str | None	Optional formula to dynamically determine output types
id	str | None	Optional unique identifier for the filter
input_typings	set[StreamType]	Determine the set of input stream types this filter accepts.
is_dynamic_input	bool	Whether the filter can accept a variable number of inputs
is_dynamic_output	bool	Whether the filter can produce a variable number of outputs
is_filter_sink	bool | None	Whether the filter is a sink (consumes input without producing output)
is_filter_source	bool | None	Whether the filter is a source (produces output without requiring input)
is_support_command	bool | None	Whether the filter supports runtime commands
is_support_framesync	bool | None	Whether the filter supports frame synchronization
is_support_slice_threading	bool | None	Whether the filter supports slice-based multithreading
is_support_timeline	bool | None	Whether the filter supports timeline editing features
name	str	The name of the filter as used in FFmpeg commands
options	tuple[FFMpegFilterOption, ...]	The configurable options this filter accepts
output_typings	set[StreamType]	Determine the set of output stream types this filter produces.
pre	tuple[tuple[str, str], ...]	Pre-defined parameter pairs for the filter
pre_dict	dict[str, str]	Convert the pre-defined parameter pairs to a dictionary.
ref	str | None	Optional reference to documentation or source code
stream_typings_input	tuple[FFMpegIOType, ...]	The types of input streams this filter accepts
stream_typings_output	tuple[FFMpegIOType, ...]	The types of output streams this filter produces
to_def	FFMpegFilterDef	Convert this comprehensive filter definition to a simplified FFMpegFilterDef.

description instance-attribute

description: str

Human-readable description of what the filter does

filter_type property

filter_type: FFMpegFilterType

Determine the FFmpeg filter type based on input and output stream types.

This property analyzes the filter's input and output specifications to determine which category of filter it belongs to according to FFmpeg's classification system (audio filter, video filter, source, sink, etc.).

Returns:

Type	Description
FFMpegFilterType	The appropriate FFMpegFilterType for this filter

Raises:

Type	Description
ValueError	If the filter's input/output configuration doesn't match any known filter type
AssertionError	If a sink filter has multiple input types or if a filter has no input types

formula_typings_input class-attribute instance-attribute

formula_typings_input: str | None = None

Optional formula to dynamically determine input types

formula_typings_output class-attribute instance-attribute

formula_typings_output: str | None = None

Optional formula to dynamically determine output types

id class-attribute instance-attribute

id: str | None = None

Optional unique identifier for the filter

input_typings property

input_typings: set[StreamType]

Determine the set of input stream types this filter accepts.

This property analyzes the filter's input specifications to determine what types of streams (audio, video, or both) it can accept as input.

Returns:

Type	Description
set[StreamType]	A set of StreamType values representing accepted input types

Raises:

Type	Description
AssertionError	If a dynamic input filter has no input formula

is_dynamic_input class-attribute instance-attribute

is_dynamic_input: bool = False

Whether the filter can accept a variable number of inputs

is_dynamic_output class-attribute instance-attribute

is_dynamic_output: bool = False

Whether the filter can produce a variable number of outputs

is_filter_sink class-attribute instance-attribute

is_filter_sink: bool | None = None

Whether the filter is a sink (consumes input without producing output)

is_filter_source class-attribute instance-attribute

is_filter_source: bool | None = None

Whether the filter is a source (produces output without requiring input)

is_support_command class-attribute instance-attribute

is_support_command: bool | None = None

Whether the filter supports runtime commands

is_support_framesync class-attribute instance-attribute

is_support_framesync: bool | None = None

Whether the filter supports frame synchronization

is_support_slice_threading class-attribute instance-attribute

is_support_slice_threading: bool | None = None

Whether the filter supports slice-based multithreading

is_support_timeline class-attribute instance-attribute

is_support_timeline: bool | None = None

Whether the filter supports timeline editing features

name instance-attribute

name: str

The name of the filter as used in FFmpeg commands

options class-attribute instance-attribute

options: tuple[FFMpegFilterOption, ...] = ()

The configurable options this filter accepts

output_typings property

output_typings: set[StreamType]

Determine the set of output stream types this filter produces.

This property analyzes the filter's output specifications to determine what types of streams (audio, video, or both) it can produce as output.

Returns:

Type	Description
set[StreamType]	A set of StreamType values representing produced output types

Raises:

Type	Description
AssertionError	If a dynamic output filter has no output formula

pre class-attribute instance-attribute

pre: tuple[tuple[str, str], ...] = ()

Pre-defined parameter pairs for the filter

pre_dict property

pre_dict: dict[str, str]

Convert the pre-defined parameter pairs to a dictionary.

Returns:

Type	Description
dict[str, str]	A dictionary mapping parameter names to their values

ref class-attribute instance-attribute

ref: str | None = None

Optional reference to documentation or source code

stream_typings_input class-attribute instance-attribute

stream_typings_input: tuple[FFMpegIOType, ...] = ()

The types of input streams this filter accepts

stream_typings_output class-attribute instance-attribute

stream_typings_output: tuple[FFMpegIOType, ...] = ()

The types of output streams this filter produces

to_def property

to_def: FFMpegFilterDef

Convert this comprehensive filter definition to a simplified FFMpegFilterDef.

This creates a simplified representation of the filter focusing only on its name and input/output types, which is useful for filter node creation.

Returns:

Type	Description
FFMpegFilterDef	A simplified FFMpegFilterDef representation of this filter

FFMpegFilterDef dataclass

FFMpegFilterDef(
    *,
    name: str,
    typings_input: (
        str | tuple[Literal["video", "audio"], ...]
    ) = (),
    typings_output: (
        str | tuple[Literal["video", "audio"], ...]
    ) = ()
)

Bases: Serializable

Defines the basic structure of an FFmpeg filter.

This class provides a simplified representation of an FFmpeg filter, focusing on its name and the types of its inputs and outputs.

Attributes:

Name	Type	Description
name	str	The name of the filter as used in FFmpeg
typings_input	str | tuple[Literal['video', 'audio'], ...]	The types of input streams this filter accepts.
typings_output	str | tuple[Literal['video', 'audio'], ...]	The types of output streams this filter produces.

name instance-attribute

name: str

The name of the filter as used in FFmpeg

typings_input class-attribute instance-attribute

typings_input: (
    str | tuple[Literal["video", "audio"], ...]
) = ()

The types of input streams this filter accepts. Can be a tuple of stream types or a string expression that evaluates to a tuple.

typings_output class-attribute instance-attribute

typings_output: (
    str | tuple[Literal["video", "audio"], ...]
) = ()

The types of output streams this filter produces. Can be a tuple of stream types or a string expression that evaluates to a tuple.

FFMpegFilterOption dataclass

FFMpegFilterOption(
    *,
    name: str,
    alias: tuple[str, ...] = (),
    description: str,
    type: FFMpegFilterOptionType,
    min: str | None = None,
    max: str | None = None,
    default: bool | int | float | str | None = None,
    required: bool = False,
    choices: tuple[FFMpegFilterOptionChoice, ...] = (),
    flags: str | None = None
)

Bases: Serializable

Represents a configurable option for an FFmpeg filter.

This class defines the metadata for a single option that can be passed to an FFmpeg filter, including its type, constraints, and default value.

Attributes:

Name	Type	Description
alias	tuple[str, ...]	Alternative names that can be used for this option
choices	tuple[FFMpegFilterOptionChoice, ...]	Enumerated values that this option accepts, if applicable
default	bool | int | float | str | None	Default value used by FFmpeg if the option is not specified
description	str	Human-readable description of what the option does
flags	str | None	Optional flags that modify the behavior of this option
max	str | None	Maximum allowed value for numeric options
min	str | None	Minimum allowed value for numeric options
name	str	The primary name of the option as used in FFmpeg
required	bool	Whether the option must be provided or can be omitted
type	FFMpegFilterOptionType	The data type of the option (boolean, int, string, etc.)

alias class-attribute instance-attribute

alias: tuple[str, ...] = ()

Alternative names that can be used for this option

choices class-attribute instance-attribute

choices: tuple[FFMpegFilterOptionChoice, ...] = ()

Enumerated values that this option accepts, if applicable

default class-attribute instance-attribute

default: bool | int | float | str | None = None

Default value used by FFmpeg if the option is not specified

description instance-attribute

description: str

Human-readable description of what the option does

flags class-attribute instance-attribute

flags: str | None = None

Optional flags that modify the behavior of this option

max class-attribute instance-attribute

max: str | None = None

Maximum allowed value for numeric options

min class-attribute instance-attribute

min: str | None = None

Minimum allowed value for numeric options

name instance-attribute

name: str

The primary name of the option as used in FFmpeg

required class-attribute instance-attribute

required: bool = False

Whether the option must be provided or can be omitted

type instance-attribute

type: FFMpegFilterOptionType

The data type of the option (boolean, int, string, etc.)

FFMpegFilterOptionChoice dataclass

FFMpegFilterOptionChoice(
    *,
    name: str,
    help: str,
    value: str | int,
    flags: str | None = None
)

Bases: Serializable

Represents a single choice for an FFmpeg filter option with enumerated values.

Some FFmpeg filter options accept only specific enumerated values. This class represents one such value along with its description and internal representation.

Attributes:

Name	Type	Description
flags	str | None	Optional flags associated with this choice
help	str	Description of what this choice does
name	str	The name of the choice as it appears in FFmpeg documentation
value	str | int	The actual value to pass to FFmpeg when this choice is selected

flags class-attribute instance-attribute

flags: str | None = None

Optional flags associated with this choice

help instance-attribute

help: str

Description of what this choice does

name instance-attribute

name: str

The name of the choice as it appears in FFmpeg documentation

value instance-attribute

value: str | int

The actual value to pass to FFmpeg when this choice is selected

FFMpegFilterOptionType

Bases: str, Enum

Enumeration of possible data types for FFmpeg filter options.

This enum defines the various data types that can be used for options in FFmpeg filters. Each type corresponds to a specific kind of value that can be passed to a filter parameter.

FFMpegFilterType

Bases: str, Enum

Enumeration of FFmpeg filter types based on input/output stream types.

This enum categorizes filters according to what types of streams they process and produce. The naming convention follows FFmpeg's internal categorization of filters.

Attributes:

Name	Type	Description
af		Audio filter: processes audio and outputs audio
asink		Audio sink: consumes audio without producing output
asrc		Audio source: generates audio without input
avf		Audio-video filter: processes and outputs both audio and video
avsrc		Audio-video source: generates both audio and video without input
vaf		Video-to-audio filter: processes video and outputs audio
vf		Video filter: processes video and outputs video
vsink		Video sink: consumes video without producing output
vsrc		Video source: generates video without input

af class-attribute instance-attribute

af = 'af'

Audio filter: processes audio and outputs audio

asink class-attribute instance-attribute

asink = 'asink'

Audio sink: consumes audio without producing output

asrc class-attribute instance-attribute

asrc = 'asrc'

Audio source: generates audio without input

avf class-attribute instance-attribute

avf = 'avf'

Audio-video filter: processes and outputs both audio and video

avsrc class-attribute instance-attribute

avsrc = 'avsrc'

Audio-video source: generates both audio and video without input

vaf class-attribute instance-attribute

vaf = 'vaf'

Video-to-audio filter: processes video and outputs audio

vf class-attribute instance-attribute

vf = 'vf'

Video filter: processes video and outputs video

vsink class-attribute instance-attribute

vsink = 'vsink'

Video sink: consumes video without producing output

vsrc class-attribute instance-attribute

vsrc = 'vsrc'

Video source: generates video without input

FFMpegIOType dataclass

FFMpegIOType(*, name: str | None = None, type: StreamType)

Bases: Serializable

Defines the type information for a filter's input or output stream.

This class associates a name with a stream type (audio or video) for a specific input or output of an FFmpeg filter.

Attributes:

Name	Type	Description
name	str | None	Optional name for this input/output stream
type	StreamType	The type of the stream (audio or video)

name class-attribute instance-attribute

name: str | None = None

Optional name for this input/output stream

type instance-attribute

type: StreamType

The type of the stream (audio or video)

FFMpegOption dataclass

FFMpegOption(
    *,
    name: str,
    type: FFMpegOptionType,
    flags: int,
    help: str,
    argname: str | None = None,
    canon: str | None = None
)

Bases: Serializable

Represents a command-line option for FFmpeg.

This class defines the metadata for a single option that can be passed to the FFmpeg command line, including its type, help text, and flags that determine its behavior.

Attributes:

Name	Type	Description
argname	str | None	Optional name for the option's argument in help text
canon	str | None	For alternative option forms, the name of the canonical option
flags	int	Bitmap of FFMpegOptionFlag values that define the option's behavior
help	str	Human-readable description of what the option does
is_global_option	bool	Check if this option applies globally rather than to specific files.
is_input_option	bool	Check if this option applies to input files.
is_output_option	bool	Check if this option applies to output files.
is_support_stream_specifier	bool	Check if this option supports stream specifiers.
name	str	The name of the option as used in FFmpeg commands
type	FFMpegOptionType	The data type of the option (boolean, int, string, etc.)

argname class-attribute instance-attribute

argname: str | None = None

Optional name for the option's argument in help text

canon class-attribute instance-attribute

canon: str | None = None

For alternative option forms, the name of the canonical option

flags instance-attribute

flags: int

Bitmap of FFMpegOptionFlag values that define the option's behavior

help instance-attribute

help: str

Human-readable description of what the option does

is_global_option property

is_global_option: bool

Check if this option applies globally rather than to specific files.

Returns:

Type	Description
bool	True if this option is a global option that doesn't apply to
bool	specific input or output files

is_input_option property

is_input_option: bool

Check if this option applies to input files.

Returns:

Type	Description
bool	True if this option is meant to be used with input files

is_output_option property

is_output_option: bool

Check if this option applies to output files.

Returns:

Type	Description
bool	True if this option is meant to be used with output files

is_support_stream_specifier property

is_support_stream_specifier: bool

Check if this option supports stream specifiers.

Stream specifiers allow options to be applied to specific streams within a file, using syntax like "-c:v" for video codec.

Returns:

Type	Description
bool	True if this option can be used with stream specifiers

name instance-attribute

name: str

The name of the option as used in FFmpeg commands

type instance-attribute

type: FFMpegOptionType

The data type of the option (boolean, int, string, etc.)

FFMpegOptionFlag

Bases: int, Enum

FFmpeg option flags that define option behavior and characteristics.

Attributes:

Name	Type	Description
OPT_EXIT		Program will immediately exit after processing this option
OPT_EXPERT		Option is intended for advanced users. Only affects help output.
OPT_FLAG_OFFSET		Option is specified as an offset in a passed optctx.
OPT_FLAG_PERSTREAM		Option applies per-stream (implies OPT_SPEC).
OPT_FLAG_SPEC		Option is to be stored in a SpecifierOptList.
OPT_FUNC_ARG		The OPT_TYPE_FUNC option takes an argument.
OPT_HAS_ALT		This option is a "canonical" form, to which one or more alternatives exist. These alternatives are listed in u1.names_alt.
OPT_HAS_CANON		This option is an alternative form of some other option, whose name is stored in u1.name_canon
OPT_INPUT		ffmpeg-only - specifies whether an OPT_PERFILE option applies to input, output, or both.
OPT_OFFSET		Option is to be stored in a SpecifierOptList.
OPT_OUTPUT		ffmpeg-only - specifies whether an OPT_PERFILE option applies to input, output, or both.
OPT_PERFILE		The option is per-file (currently ffmpeg-only). At least one of OPT_INPUT or OPT_OUTPUT must be set when this flag is in use.
OPT_SPEC		Option applies per-stream (implies OPT_SPEC).

OPT_EXIT class-attribute instance-attribute

OPT_EXIT = 1 << 1

Program will immediately exit after processing this option

OPT_EXPERT class-attribute instance-attribute

OPT_EXPERT = 1 << 2

Option is intended for advanced users. Only affects help output.

OPT_FLAG_OFFSET class-attribute instance-attribute

OPT_FLAG_OFFSET = 1 << 8

Option is specified as an offset in a passed optctx. Always use as OPT_OFFSET in option definitions.

OPT_FLAG_PERSTREAM class-attribute instance-attribute

OPT_FLAG_PERSTREAM = 1 << 10

Option applies per-stream (implies OPT_SPEC).

OPT_FLAG_SPEC class-attribute instance-attribute

OPT_FLAG_SPEC = 1 << 9

Option is to be stored in a SpecifierOptList. Always use as OPT_SPEC in option definitions.

OPT_FUNC_ARG class-attribute instance-attribute

OPT_FUNC_ARG = 1 << 0

The OPT_TYPE_FUNC option takes an argument. Must not be used with other option types, as for those it holds: - OPT_TYPE_BOOL do not take an argument - all other types do

OPT_HAS_ALT class-attribute instance-attribute

OPT_HAS_ALT = 1 << 13

This option is a "canonical" form, to which one or more alternatives exist. These alternatives are listed in u1.names_alt.

OPT_HAS_CANON class-attribute instance-attribute

OPT_HAS_CANON = 1 << 14

This option is an alternative form of some other option, whose name is stored in u1.name_canon

OPT_INPUT class-attribute instance-attribute

OPT_INPUT = 1 << 11

ffmpeg-only - specifies whether an OPT_PERFILE option applies to input, output, or both.

OPT_OFFSET class-attribute instance-attribute

OPT_OFFSET = OPT_FLAG_OFFSET | OPT_PERFILE

Option is to be stored in a SpecifierOptList. Always use as OPT_SPEC in option definitions.

OPT_OUTPUT class-attribute instance-attribute

OPT_OUTPUT = 1 << 12

ffmpeg-only - specifies whether an OPT_PERFILE option applies to input, output, or both.

OPT_PERFILE class-attribute instance-attribute

OPT_PERFILE = 1 << 7

The option is per-file (currently ffmpeg-only). At least one of OPT_INPUT or OPT_OUTPUT must be set when this flag is in use.

OPT_SPEC class-attribute instance-attribute

OPT_SPEC = OPT_FLAG_SPEC | OPT_OFFSET

Option applies per-stream (implies OPT_SPEC).

FFMpegOptionType

Bases: str, Enum

Enumeration of FFmpeg option data types.

This enum defines the various data types that can be used for FFmpeg command-line options. These types correspond to the internal option types defined in FFmpeg's libavutil/opt.h header.

Attributes:

Name	Type	Description
OPT_TYPE_BOOL		Boolean option type (true/false)
OPT_TYPE_DOUBLE		Double-precision floating-point option type
OPT_TYPE_FLOAT		Floating-point option type
OPT_TYPE_FUNC		Function option type, typically used for callback functions
OPT_TYPE_INT		Integer option type
OPT_TYPE_INT64		64-bit integer option type
OPT_TYPE_STRING		String option type
OPT_TYPE_TIME		Time value option type (e.g., duration in seconds)

OPT_TYPE_BOOL class-attribute instance-attribute

OPT_TYPE_BOOL = 'OPT_TYPE_BOOL'

Boolean option type (true/false)

OPT_TYPE_DOUBLE class-attribute instance-attribute

OPT_TYPE_DOUBLE = 'OPT_TYPE_DOUBLE'

Double-precision floating-point option type

OPT_TYPE_FLOAT class-attribute instance-attribute

OPT_TYPE_FLOAT = 'OPT_TYPE_FLOAT'

Floating-point option type

OPT_TYPE_FUNC class-attribute instance-attribute

OPT_TYPE_FUNC = 'OPT_TYPE_FUNC'

Function option type, typically used for callback functions

OPT_TYPE_INT class-attribute instance-attribute

OPT_TYPE_INT = 'OPT_TYPE_INT'

Integer option type

OPT_TYPE_INT64 class-attribute instance-attribute

OPT_TYPE_INT64 = 'OPT_TYPE_INT64'

64-bit integer option type

OPT_TYPE_STRING class-attribute instance-attribute

OPT_TYPE_STRING = 'OPT_TYPE_STRING'

String option type

OPT_TYPE_TIME class-attribute instance-attribute

OPT_TYPE_TIME = 'OPT_TYPE_TIME'

Time value option type (e.g., duration in seconds)

StreamType

Bases: str, Enum

Enumeration of possible stream types in FFmpeg.

This enum defines the fundamental types of media streams that can be processed by FFmpeg filters. Each stream in FFmpeg is either an audio stream or a video stream, and filters are designed to work with specific stream types.

Attributes:

Name	Type	Description
audio		Represents an audio stream containing sound data
video		Represents a video stream containing visual frame data

audio class-attribute instance-attribute

audio = 'audio'

Represents an audio stream containing sound data

video class-attribute instance-attribute

video = 'video'

Represents a video stream containing visual frame data