base_streams

Base stream classes to avoid circular import dependencies.

This module contains the base FilterableStream class that is used by both the DAG layer and the streams layer. By keeping it separate, we avoid circular imports between dag/nodes.py and streams/*.py.

FilterableStreamBase dataclass

FilterableStreamBase(
    *,
    node: Node,
    index: int | None = None,
    optional: bool = False
)

Bases: Stream, OutputArgs

A stream that can be used as input to an FFmpeg filter.

FilterableStream represents a media stream (audio or video) that can be processed by FFmpeg filters. It provides methods for applying various filters to the stream and for outputting the stream to a file.

This class serves as a base for specific stream types like VideoStream and AudioStream, providing common functionality for filter operations.

Note: This class is defined separately from nodes.py to avoid circular import dependencies between dag/nodes.py and streams/*.py.

Methods:

Name	Description
afilter	Apply a custom audio filter to this stream.
filter_multi_output	Apply a custom filter with multiple outputs to this stream.
output	Output file URL
vfilter	Apply a custom video filter to this stream.
view	Visualize the stream.

Attributes:

Name	Type	Description
hex	str	Get the hexadecimal hash of the object.
index	int | None	Represents the index of the stream in the node's output streams.
node	FilterNode | InputNode | LoopbackDecoderNode	Represents the node that the stream is connected to in the upstream direction.
optional	bool	Represents whether the stream is optional.

hex cached property

hex: str

Get the hexadecimal hash of the object.

index class-attribute instance-attribute

index: int | None = None

Represents the index of the stream in the node's output streams.

Note

See Also: Stream specifiers stream_index

node instance-attribute

node: FilterNode | InputNode | LoopbackDecoderNode

Represents the node that the stream is connected to in the upstream direction.

Note

In the context of a data stream, the 'upstream' refers to the source of the data, or where the data is coming from. Therefore, the 'upstream node' is the node that is providing the data to the current stream.

optional class-attribute instance-attribute

optional: bool = False

Represents whether the stream is optional.

Note

See Also: Advanced options

afilter

afilter(
    *streams: FilterableStream,
    name: str,
    input_typings: tuple[StreamType, ...] = (audio,),
    **kwargs: Any
) -> AudioStream

Apply a custom audio filter to this stream.

This method applies a custom FFmpeg audio filter to this stream and returns the resulting audio stream. It's a convenience wrapper around filter_multi_output that handles the case of filters with a single audio output.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	Additional input streams for the filter	()
name	str	The name of the FFmpeg filter to apply	required
input_typings	tuple[StreamType, ...]	The expected types of the input streams (defaults to all audio)	(audio,)
**kwargs	Any	Filter-specific parameters as keyword arguments	{}

Returns:

Type	Description
AudioStream	An AudioStream representing the filter's output

Example

# Apply a volume filter to an audio stream
louder = stream.afilter(name="volume", volume=2.0)

filter_multi_output

filter_multi_output(
    *streams: FilterableStream,
    name: str,
    input_typings: tuple[StreamType, ...] = (),
    output_typings: tuple[StreamType, ...] = (),
    **kwargs: Any
) -> FilterNode

Apply a custom filter with multiple outputs to this stream.

This method creates a FilterNode that applies a custom FFmpeg filter to this stream (and optionally additional streams). Unlike vfilter and afilter which return a single stream, this method returns the FilterNode itself, allowing access to multiple output streams.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	Additional input streams for the filter	()
name	str	The name of the FFmpeg filter to apply	required
input_typings	tuple[StreamType, ...]	The expected types of the input streams	()
output_typings	tuple[StreamType, ...]	The types of output streams this filter produces	()
**kwargs	Any	Filter-specific parameters as keyword arguments	{}

Returns:

Type	Description
FilterNode	A FilterNode representing the filter operation

Example

# Apply a split filter that produces two output streams
filter_node = stream.filter_multi_output(
    name="split", output_typings=(StreamType.video, StreamType.video)
)
output1 = filter_node.video(0)
output2 = filter_node.video(1)

output

output(
    *streams: "FilterableStream",
    filename: str | Path,
    f: Func = None,
    c: Func = None,
    codec: Func = None,
    pre: Func = None,
    map: Func = None,
    map_channel: Func = None,
    map_metadata: Func = None,
    map_chapters: Func = None,
    t: Func = None,
    to: Func = None,
    fs: Func = None,
    ss: Func = None,
    timestamp: Func = None,
    metadata: Func = None,
    program: Func = None,
    dframes: Func = None,
    target: Func = None,
    shortest: Func = None,
    bitexact: Func = None,
    apad: Func = None,
    copyinkf: Func = None,
    copypriorss: Func = None,
    frames: Func = None,
    tag: Func = None,
    q: Func = None,
    qscale: Func = None,
    profile: Func = None,
    filter: Func = None,
    filter_script: Func = None,
    attach: Func = None,
    disposition: Func = None,
    bits_per_raw_sample: Func = None,
    vframes: Func = None,
    r: Func = None,
    fpsmax: Func = None,
    s: Func = None,
    aspect: Func = None,
    pix_fmt: Func = None,
    vn: Func = None,
    rc_override: Func = None,
    vcodec: Func = None,
    timecode: Func = None,
    _pass: Func = None,
    passlogfile: Func = None,
    vf: Func = None,
    intra_matrix: Func = None,
    inter_matrix: Func = None,
    chroma_intra_matrix: Func = None,
    top: Func = None,
    vtag: Func = None,
    fps_mode: Func = None,
    force_fps: Func = None,
    streamid: Func = None,
    force_key_frames: Func = None,
    ab: Func = None,
    b: Func = None,
    autoscale: Func = None,
    aframes: Func = None,
    aq: Func = None,
    ar: Func = None,
    ac: Func = None,
    an: Func = None,
    acodec: Func = None,
    atag: Func = None,
    sample_fmt: Func = None,
    channel_layout: Func = None,
    ch_layout: Func = None,
    af: Func = None,
    sn: Func = None,
    scodec: Func = None,
    stag: Func = None,
    muxdelay: Func = None,
    muxpreload: Func = None,
    sdp_file: Func = None,
    time_base: Func = None,
    enc_time_base: Func = None,
    bsf: Func = None,
    absf: Func = None,
    vbsf: Func = None,
    apre: Func = None,
    vpre: Func = None,
    spre: Func = None,
    fpre: Func = None,
    max_muxing_queue_size: Func = None,
    muxing_queue_data_threshold: Func = None,
    dcodec: Func = None,
    dn: Func = None,
    encoder_options: FFMpegEncoderOption | None = None,
    muxer_options: FFMpegMuxerOption | None = None,
    format_options: (
        FFMpegAVFormatContextEncoderOption | None
    ) = None,
    codec_options: (
        FFMpegAVCodecContextEncoderOption | None
    ) = None,
    extra_options: dict[str, Any] | None = None
) -> OutputStream

Output file URL

Parameters:

Name	Type	Description	Default
*streams	'FilterableStream'	the streams to output	()
filename	str | Path	the filename to output to	required
f	Func	force format	None
c	Func	codec name	None
codec	Func	codec name	None
pre	Func	preset name	None
map	Func	set input stream mapping	None
map_channel	Func	map an audio channel from one stream to another	None
map_metadata	Func	set metadata information of outfile from infile	None
map_chapters	Func	set chapters mapping	None
t	Func	record or transcode "duration" seconds of audio/video	None
to	Func	record or transcode stop time	None
fs	Func	set the limit file size in bytes	None
ss	Func	set the start time offset	None
timestamp	Func	set the recording timestamp ('now' to set the current time)	None
metadata	Func	add metadata	None
program	Func	add program with specified streams	None
dframes	Func	set the number of data frames to output	None
target	Func	specify target file type ("vcd", "svcd", "dvd", "dv" or "dv50 with optional prefixes "pal-", "ntsc-" or "film-")	None
shortest	Func	finish encoding within shortest input	None
bitexact	Func	bitexact mode	None
apad	Func	audio pad	None
copyinkf	Func	copy initial non-keyframes	None
copypriorss	Func	copy or discard frames before start time	None
frames	Func	set the number of frames to output	None
tag	Func	force codec tag/fourcc	None
q	Func	use fixed quality scale (VBR)	None
qscale	Func	use fixed quality scale (VBR)	None
profile	Func	set profile	None
filter	Func	set stream filtergraph	None
filter_script	Func	read stream filtergraph description from a file	None
attach	Func	add an attachment to the output file	None
disposition	Func	disposition	None
bits_per_raw_sample	Func	set the number of bits per raw sample	None
vframes	Func	set the number of video frames to output	None
r	Func	set frame rate (Hz value, fraction or abbreviation)	None
fpsmax	Func	set max frame rate (Hz value, fraction or abbreviation)	None
s	Func	set frame size (WxH or abbreviation)	None
aspect	Func	set aspect ratio (4:3, 16:9 or 1.3333, 1.7777)	None
pix_fmt	Func	set pixel format	None
vn	Func	disable video	None
rc_override	Func	rate control override for specific intervals	None
vcodec	Func	force video codec ('copy' to copy stream)	None
timecode	Func	set initial TimeCode value.	None
_pass	Func	select the pass number (1 to 3)	None
passlogfile	Func	select two pass log file name prefix	None
vf	Func	set video filters	None
intra_matrix	Func	specify intra matrix coeffs	None
inter_matrix	Func	specify inter matrix coeffs	None
chroma_intra_matrix	Func	specify intra matrix coeffs	None
top	Func	top=1/bottom=0/auto=-1 field first	None
vtag	Func	force video tag/fourcc	None
fps_mode	Func	set framerate mode for matching video streams; overrides vsync	None
force_fps	Func	force the selected framerate, disable the best supported framerate selection	None
streamid	Func	set the value of an outfile streamid	None
force_key_frames	Func	force key frames at specified timestamps	None
ab	Func	audio bitrate (please use -b:a)	None
b	Func	video bitrate (please use -b:v)	None
autoscale	Func	automatically insert a scale filter at the end of the filter graph	None
aframes	Func	set the number of audio frames to output	None
aq	Func	set audio quality (codec-specific)	None
ar	Func	set audio sampling rate (in Hz)	None
ac	Func	set number of audio channels	None
an	Func	disable audio	None
acodec	Func	force audio codec ('copy' to copy stream)	None
atag	Func	force audio tag/fourcc	None
sample_fmt	Func	set sample format	None
channel_layout	Func	set channel layout	None
ch_layout	Func	set channel layout	None
af	Func	set audio filters	None
sn	Func	disable subtitle	None
scodec	Func	force subtitle codec ('copy' to copy stream)	None
stag	Func	force subtitle tag/fourcc	None
muxdelay	Func	set the maximum demux-decode delay	None
muxpreload	Func	set the initial demux-decode delay	None
sdp_file	Func	specify a file in which to print sdp information	None
time_base	Func	set the desired time base hint for output stream (1:24, 1:48000 or 0.04166, 2.0833e-5)	None
enc_time_base	Func	set the desired time base for the encoder (1:24, 1:48000 or 0.04166, 2.0833e-5). two special values are defined - 0 = use frame rate (video) or sample rate (audio),-1 = match source time base	None
bsf	Func	A comma-separated list of bitstream filters	None
absf	Func	deprecated	None
vbsf	Func	deprecated	None
apre	Func	set the audio options to the indicated preset	None
vpre	Func	set the video options to the indicated preset	None
spre	Func	set the subtitle options to the indicated preset	None
fpre	Func	set options from indicated preset file	None
max_muxing_queue_size	Func	maximum number of packets that can be buffered while waiting for all streams to initialize	None
muxing_queue_data_threshold	Func	set the threshold after which max_muxing_queue_size is taken into account	None
dcodec	Func	force data codec ('copy' to copy stream)	None
dn	Func	disable data	None
encoder_options	FFMpegEncoderOption | None	ffmpeg's encoder options	None
muxer_options	FFMpegMuxerOption | None	FFMpegMuxerOption	None
format_options	FFMpegAVFormatContextEncoderOption | None	FFMpegAVFormatContextEncoderOption	None
codec_options	FFMpegAVCodecContextEncoderOption | None	FFMpegAVCodecContextEncoderOption	None
extra_options	dict[str, Any] | None	the arguments for the output	None

Returns:

Type	Description
OutputStream	the output stream

vfilter

vfilter(
    *streams: FilterableStream,
    name: str,
    input_typings: tuple[StreamType, ...] = (video,),
    **kwargs: Any
) -> VideoStream

Apply a custom video filter to this stream.

This method applies a custom FFmpeg video filter to this stream and returns the resulting video stream. It's a convenience wrapper around filter_multi_output that handles the case of filters with a single video output.

Parameters:

Name	Type	Description	Default
*streams	FilterableStream	Additional input streams for the filter	()
name	str	The name of the FFmpeg filter to apply	required
input_typings	tuple[StreamType, ...]	The expected types of the input streams (defaults to all video)	(video,)
**kwargs	Any	Filter-specific parameters as keyword arguments	{}

Returns:

Type	Description
VideoStream	A VideoStream representing the filter's output

Example

# Apply a blur filter to a video stream
blurred = stream.vfilter(name="boxblur", luma_radius=2)

view

view(format: Literal['png', 'svg', 'dot'] = 'png') -> str

Visualize the stream.

Parameters:

Name	Type	Description	Default
format	Literal['png', 'svg', 'dot']	The format of the view.	'png'

Returns:

Type	Description
str	The file path of the visualization.