SubtitleParser

Artifact: androidx.media3:media3-extractor

View Source

---

Kotlin |Java

@UnstableApi
interface SubtitleParser

Known direct subclasses

DvbParser, Mp4WebvttParser, PgsParser, SsaParser, SubripParser, TtmlParser, Tx3gParser, WebvttParser

DvbParser	A SubtitleParser for DVB subtitles.
Mp4WebvttParser	A SubtitleParser for Webvtt embedded in a Mp4 container file.
PgsParser	A SubtitleParser for PGS subtitles.
SsaParser	A SubtitleParser for SSA/ASS.
SubripParser	A SubtitleParser for SubRip.
TtmlParser	A SimpleSubtitleDecoder for TTML supporting the DFXP presentation profile.
Tx3gParser	A SubtitleParser for tx3g.
WebvttParser	A SubtitleParser for WebVTT.

---

Parses subtitle data into timed CuesWithTiming instances.

Instances are stateful, so samples can be fed in repeated calls to parse, and one or more complete CuesWithTiming instances will be returned when enough data has been received. Due to this stateful-ness, reset must be called after a seek or similar discontinuity in the source data.

Summary

Nested types
interface SubtitleParser.Factory Factory for SubtitleParser instances.
class SubtitleParser.OutputOptions Options to control the output behavior of SubtitleParser methods that emit their output incrementally using a Consumer provided by the caller.

Public functions
Int	@Format.CueReplacementBehavior getCueReplacementBehavior() Returns the CueReplacementBehavior for consecutive CuesWithTiming emitted by this implementation.
Unit	parse(     data: ByteArray!,     outputOptions: SubtitleParser.OutputOptions!,     output: Consumer<CuesWithTiming!>! ) Parses data (and any data stored from previous invocations) and emits resulting instances.
Unit	parse(     data: ByteArray!,     offset: Int,     length: Int,     outputOptions: SubtitleParser.OutputOptions!,     output: Consumer<CuesWithTiming!>! ) Parses data (and any data stored from previous invocations) and emits any resulting complete CuesWithTiming instances via output.
Subtitle!	parseToLegacySubtitle(data: ByteArray!, offset: Int, length: Int) Parses data to a legacy Subtitle instance.
Unit	reset() Clears any data stored inside this parser from previous parse calls.

Public functions

getCueReplacementBehavior

@Format.CueReplacementBehavior
fun getCueReplacementBehavior(): Int

Returns the CueReplacementBehavior for consecutive CuesWithTiming emitted by this implementation.

A given instance must always return the same value from this method.

parse

fun parse(
    data: ByteArray!,
    outputOptions: SubtitleParser.OutputOptions!,
    output: Consumer<CuesWithTiming!>!
): Unit

Parses data (and any data stored from previous invocations) and emits resulting instances.

Equivalent to parse(data, 0, data.length, outputOptions, output).

parse

fun parse(
    data: ByteArray!,
    offset: Int,
    length: Int,
    outputOptions: SubtitleParser.OutputOptions!,
    output: Consumer<CuesWithTiming!>!
): Unit

Parses data (and any data stored from previous invocations) and emits any resulting complete CuesWithTiming instances via output.

Any samples not used from data will be persisted and used during subsequent calls to this method.

startTimeUs in an emitted instance is derived only from the provided sample data, so has to be considered together with any relevant subsampleOffsetUs. If the provided sample doesn't contain any timing information then at most one CuesWithTiming instance will be emitted, with startTimeUs set to TIME_UNSET, in which case subsampleOffsetUsmust be OFFSET_SAMPLE_RELATIVE.

Parameters
data: ByteArray!	The subtitle data to parse. This must contain only complete samples. For subtitles muxed inside a media container, a sample is usually defined by the container. For subtitles read from a text file, a sample is usually the entire contents of the text file.
offset: Int	The index in data to start reading from (inclusive).
length: Int	The number of bytes to read from data.
outputOptions: SubtitleParser.OutputOptions!	Options to control how instances are emitted to output.
output: Consumer<CuesWithTiming!>!	A consumer for CuesWithTiming instances emitted by this method. All calls will be made on the thread that called this method, and will be completed before this method returns.

parseToLegacySubtitle

fun parseToLegacySubtitle(data: ByteArray!, offset: Int, length: Int): Subtitle!

Parses data to a legacy Subtitle instance.

This method only exists temporarily to support the transition away from and Subtitle. It will be removed in a future release.

The default implementation delegates to parse. Implementations can override this to provide a more efficient implementation if desired.

Parameters
data: ByteArray!	The subtitle data to parse. This must contain only complete samples. For subtitles muxed inside a media container, a sample is usually defined by the container. For subtitles read from a text file, a sample is usually the entire contents of the text file.
offset: Int	The index in data to start reading from (inclusive).
length: Int	The number of bytes to read from data.

reset

fun reset(): Unit

Clears any data stored inside this parser from previous parse calls.

This must be called after a seek or other similar discontinuity in the source data.

The default implementation is a no-op.