subtitle

Subtitle stream utilities.

Classes:

Name	Description
SubtitleStream	A stream that contains subtitle data.

SubtitleStream dataclass

SubtitleStream(
    *,
    node: FilterNode | InputNode,
    index: int | None = None,
    optional: bool = False
)

Bases: FilterableStream

A stream that contains subtitle data.

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	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

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 that can be used to access the filter's outputs

Example

# Split a video into two identical streams
split_node = stream.filter_multi_output(
    name="split", output_typings=(StreamType.video, StreamType.video)
)
stream1 = split_node.video(0)
stream2 = split_node.video(1)

output

output(
    *streams: FilterableStream,
    filename: str | Path,
    f: String = None,
    c: String = None,
    codec: String = None,
    pre: String = None,
    map: Func = None,
    map_metadata: String = None,
    map_chapters: Int = None,
    t: Time = None,
    to: Time = None,
    fs: Int64 = None,
    ss: Time = None,
    timestamp: Func = None,
    metadata: String = None,
    program: String = None,
    stream_group: String = None,
    dframes: Int64 = None,
    target: Func = None,
    shortest: Boolean = None,
    shortest_buf_duration: Float = None,
    bitexact: Boolean = None,
    apad: String = None,
    copyinkf: Boolean = None,
    copypriorss: Int = None,
    frames: Int64 = None,
    tag: String = None,
    q: Func = None,
    qscale: Func = None,
    profile: Func = None,
    filter: String = None,
    filter_script: String = None,
    attach: Func = None,
    disposition: String = None,
    thread_queue_size: Int = None,
    bits_per_raw_sample: Int = None,
    stats_enc_pre: String = None,
    stats_enc_post: String = None,
    stats_mux_pre: String = None,
    stats_enc_pre_fmt: String = None,
    stats_enc_post_fmt: String = None,
    stats_mux_pre_fmt: String = None,
    vframes: Int64 = None,
    r: String = None,
    fpsmax: String = None,
    s: String = None,
    aspect: String = None,
    pix_fmt: String = None,
    vn: Boolean = None,
    rc_override: String = None,
    vcodec: String = None,
    timecode: Func = None,
    _pass: Int = None,
    passlogfile: String = None,
    vf: String = None,
    intra_matrix: String = None,
    inter_matrix: String = None,
    chroma_intra_matrix: String = None,
    vtag: String = None,
    fps_mode: String = None,
    force_fps: Boolean = None,
    streamid: Func = None,
    force_key_frames: String = None,
    b: Func = None,
    autoscale: Boolean = None,
    fix_sub_duration_heartbeat: Boolean = None,
    aframes: Int64 = None,
    aq: Func = None,
    ar: Int = None,
    ac: Int = None,
    an: Boolean = None,
    acodec: String = None,
    ab: Func = None,
    atag: String = None,
    sample_fmt: String = None,
    channel_layout: String = None,
    ch_layout: String = None,
    af: String = None,
    sn: Boolean = None,
    scodec: String = None,
    stag: String = None,
    muxdelay: Float = None,
    muxpreload: Float = None,
    sdp_file: Func = None,
    time_base: String = None,
    enc_time_base: String = None,
    bsf: String = None,
    apre: String = None,
    vpre: String = None,
    spre: String = None,
    fpre: String = None,
    max_muxing_queue_size: Int = None,
    muxing_queue_data_threshold: Int = None,
    dcodec: String = None,
    dn: Boolean = None,
    top: Int = 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	String	force container format (auto-detected otherwise)	None
c	String	select encoder/decoder ('copy' to copy stream without reencoding)	None
codec	String	alias for -c (select encoder/decoder)	None
pre	String	preset name	None
map	Func	set input stream mapping	None
map_metadata	String	set metadata information of outfile from infile	None
map_chapters	Int	set chapters mapping	None
t	Time	stop transcoding after specified duration	None
to	Time	stop transcoding after specified time is reached	None
fs	Int64	set the limit file size in bytes	None
ss	Time	start transcoding at specified time	None
timestamp	Func	set the recording timestamp ('now' to set the current time)	None
metadata	String	add metadata	None
program	String	add program with specified streams	None
stream_group	String	add stream group with specified streams and group type-specific arguments	None
dframes	Int64	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	Boolean	finish encoding within shortest input	None
shortest_buf_duration	Float	maximum buffering duration (in seconds) for the -shortest option	None
bitexact	Boolean	bitexact mode	None
apad	String	audio pad	None
copyinkf	Boolean	copy initial non-keyframes	None
copypriorss	Int	copy or discard frames before start time	None
frames	Int64	set the number of frames to output	None
tag	String	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	String	apply specified filters to audio/video	None
filter_script	String	deprecated, use -/filter	None
attach	Func	add an attachment to the output file	None
disposition	String	disposition	None
thread_queue_size	Int	set the maximum number of queued packets from the demuxer	None
bits_per_raw_sample	Int	set the number of bits per raw sample	None
stats_enc_pre	String	write encoding stats before encoding	None
stats_enc_post	String	write encoding stats after encoding	None
stats_mux_pre	String	write packets stats before muxing	None
stats_enc_pre_fmt	String	format of the stats written with -stats_enc_pre	None
stats_enc_post_fmt	String	format of the stats written with -stats_enc_post	None
stats_mux_pre_fmt	String	format of the stats written with -stats_mux_pre	None
vframes	Int64	set the number of video frames to output	None
r	String	override input framerate/convert to given output framerate (Hz value, fraction or abbreviation)	None
fpsmax	String	set max frame rate (Hz value, fraction or abbreviation)	None
s	String	set frame size (WxH or abbreviation)	None
aspect	String	set aspect ratio (4:3, 16:9 or 1.3333, 1.7777)	None
pix_fmt	String	set pixel format	None
vn	Boolean	disable video	None
rc_override	String	rate control override for specific intervals	None
vcodec	String	alias for -c:v (select encoder/decoder for video streams)	None
timecode	Func	set initial TimeCode value.	None
_pass	Int	select the pass number (1 to 3)	None
passlogfile	String	select two pass log file name prefix	None
vf	String	alias for -filter:v (apply filters to video streams)	None
intra_matrix	String	specify intra matrix coeffs	None
inter_matrix	String	specify inter matrix coeffs	None
chroma_intra_matrix	String	specify intra matrix coeffs	None
vtag	String	force video tag/fourcc	None
fps_mode	String	set framerate mode for matching video streams; overrides vsync	None
force_fps	Boolean	force the selected framerate, disable the best supported framerate selection	None
streamid	Func	set the value of an outfile streamid	None
force_key_frames	String	force key frames at specified timestamps	None
b	Func	video bitrate (please use -b:v)	None
autoscale	Boolean	automatically insert a scale filter at the end of the filter graph	None
fix_sub_duration_heartbeat	Boolean	set this video output stream to be a heartbeat stream for fix_sub_duration, according to which subtitles should be split at random access points	None
aframes	Int64	set the number of audio frames to output	None
aq	Func	set audio quality (codec-specific)	None
ar	Int	set audio sampling rate (in Hz)	None
ac	Int	set number of audio channels	None
an	Boolean	disable audio	None
acodec	String	alias for -c:a (select encoder/decoder for audio streams)	None
ab	Func	alias for -b:a (select bitrate for audio streams)	None
atag	String	force audio tag/fourcc	None
sample_fmt	String	set sample format	None
channel_layout	String	set channel layout	None
ch_layout	String	set channel layout	None
af	String	alias for -filter:a (apply filters to audio streams)	None
sn	Boolean	disable subtitle	None
scodec	String	alias for -c:s (select encoder/decoder for subtitle streams)	None
stag	String	force subtitle tag/fourcc	None
muxdelay	Float	set the maximum demux-decode delay	None
muxpreload	Float	set the initial demux-decode delay	None
sdp_file	Func	specify a file in which to print sdp information	None
time_base	String	set the desired time base hint for output stream (1:24, 1:48000 or 0.04166, 2.0833e-5)	None
enc_time_base	String	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	String	A comma-separated list of bitstream filters	None
apre	String	set the audio options to the indicated preset	None
vpre	String	set the video options to the indicated preset	None
spre	String	set the subtitle options to the indicated preset	None
fpre	String	set options from indicated preset file	None
max_muxing_queue_size	Int	maximum number of packets that can be buffered while waiting for all streams to initialize	None
muxing_queue_data_threshold	Int	set the threshold after which max_muxing_queue_size is taken into account	None
dcodec	String	alias for -c:d (select encoder/decoder for data streams)	None
dn	Boolean	disable data	None
top	Int	deprecated, use the setfield video filter	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.