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

"with optional prefixes \"pal-\", \"ntsc-\" or \"film-\") shortest: finish encoding within shortest input shortest_buf_duration: maximum buffering duration (in seconds) for the -shortest option bitexact: bitexact mode apad: audio pad copyinkf: copy initial non-keyframes copypriorss: copy or discard frames before start time frames: set the number of frames to output tag: force codec tag/fourcc q: use fixed quality scale (VBR) qscale: use fixed quality scale (VBR) profile: set profile filter: apply specified filters to audio/video filter_script: deprecated, use -/filter attach: add an attachment to the output file disposition: disposition thread_queue_size: set the maximum number of queued packets from the demuxer bits_per_raw_sample: set the number of bits per raw sample stats_enc_pre: write encoding stats before encoding stats_enc_post: write encoding stats after encoding stats_mux_pre: write packets stats before muxing stats_enc_pre_fmt: format of the stats written with -stats_enc_pre stats_enc_post_fmt: format of the stats written with -stats_enc_post stats_mux_pre_fmt: format of the stats written with -stats_mux_pre vframes: set the number of video frames to output r: override input framerate/convert to given output framerate (Hz value, fraction or abbreviation) fpsmax: set max frame rate (Hz value, fraction or abbreviation) s: set frame size (WxH or abbreviation) aspect: set aspect ratio (4:3, 16:9 or 1.3333, 1.7777) pix_fmt: set pixel format vn: disable video rc_override: rate control override for specific intervals vcodec: alias for -c:v (select encoder/decoder for video streams) timecode: set initial TimeCode value. _pass: select the pass number (1 to 3) passlogfile: select two pass log file name prefix vf: alias for -filter:v (apply filters to video streams) intra_matrix: specify intra matrix coeffs inter_matrix: specify inter matrix coeffs chroma_intra_matrix: specify intra matrix coeffs vtag: force video tag/fourcc fps_mode: set framerate mode for matching video streams; overrides vsync force_fps: force the selected framerate, disable the best supported framerate selection streamid: set the value of an outfile streamid force_key_frames: force key frames at specified timestamps b: video bitrate (please use -b:v) autoscale: automatically insert a scale filter at the end of the filter graph fix_sub_duration_heartbeat: 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 aframes: set the number of audio frames to output aq: set audio quality (codec-specific) ar: set audio sampling rate (in Hz) ac: set number of audio channels an: disable audio acodec: alias for -c:a (select encoder/decoder for audio streams) ab: alias for -b:a (select bitrate for audio streams) atag: force audio tag/fourcc sample_fmt: set sample format channel_layout: set channel layout ch_layout: set channel layout af: alias for -filter:a (apply filters to audio streams) sn: disable subtitle scodec: alias for -c:s (select encoder/decoder for subtitle streams) stag: force subtitle tag/fourcc muxdelay: set the maximum demux-decode delay muxpreload: set the initial demux-decode delay sdp_file: specify a file in which to print sdp information time_base: set the desired time base hint for output stream (1:24, 1:48000 or 0.04166, 2.0833e-5) enc_time_base: 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 bsf: A comma-separated list of bitstream filters apre: set the audio options to the indicated preset vpre: set the video options to the indicated preset spre: set the subtitle options to the indicated preset fpre: set options from indicated preset file max_muxing_queue_size: maximum number of packets that can be buffered while waiting for all streams to initialize muxing_queue_data_threshold: set the threshold after which max_muxing_queue_size is taken into account dcodec: alias for -c:d (select encoder/decoder for data streams) dn: disable data top: deprecated, use the setfield video filter encoder_options: ffmpeg's encoder options muxer_options: FFMpegMuxerOption format_options: FFMpegAVFormatContextEncoderOption codec_options: FFMpegAVCodecContextEncoderOption extra_options: the arguments for the output

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.