# SubtitleParser

Artifact: [androidx.media3:media3-extractor](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/extractor/text/SubtitleParser.java+class:androidx.media3.extractor.text.SubtitleParser)

*** ** * ** ***


```
@UnstableApi
interface SubtitleParser
```

<br />

Known direct subclasses [DvbParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/dvb/DvbParser), [Mp4WebvttParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/webvtt/Mp4WebvttParser), [PgsParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/pgs/PgsParser), [SsaParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/ssa/SsaParser), [SubripParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/subrip/SubripParser), [TtmlParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/ttml/TtmlParser), [Tx3gParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/tx3g/Tx3gParser), [VobsubParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/vobsub/VobsubParser), [WebvttParser](https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/webvtt/WebvttParser)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/dvb/DvbParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for DVB subtitles. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/webvtt/Mp4WebvttParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for Webvtt embedded in a Mp4 container file. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/pgs/PgsParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for PGS subtitles. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/ssa/SsaParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for SSA/ASS. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/subrip/SubripParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for SubRip. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/ttml/TtmlParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SimpleSubtitleDecoder` for TTML supporting the DFXP presentation profile. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/tx3g/Tx3gParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for tx3g. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/vobsub/VobsubParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for Vobsub subtitles. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/webvtt/WebvttParser` | A `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` for WebVTT. |

*** ** * ** ***

Parses subtitle data into timed `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instances.

Instances are stateful, so samples can be fed in repeated calls to `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)`, and one or more complete `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instances will be returned when enough data has been received. Due to this stateful-ness, `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#reset()` must be called after a seek or similar discontinuity in the source data.

## Summary

| ### Nested types |
|---|
| `interface https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser.Factory` Factory for `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` instances. |
| `class https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser.OutputOptions` Options to control the output behavior of `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser` methods that emit their output incrementally using a `https://developer.android.com/reference/java/util/function/Consumer.html` provided by the caller. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/Format.CueReplacementBehavior https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#getCueReplacementBehavior()()` Returns the `https://developer.android.com/reference/kotlin/androidx/media3/common/Format.CueReplacementBehavior` for consecutive `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` emitted by this implementation. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)( data: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte/index.html>!, outputOptions: https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser.OutputOptions!, output: https://developer.android.com/reference/java/util/function/Consumer.html<https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming!>! )` Parses `data` (and any data stored from previous invocations) and emits resulting `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instances. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],int,int,androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)( data: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte/index.html>!, offset: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, length: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, outputOptions: https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser.OutputOptions!, output: https://developer.android.com/reference/java/util/function/Consumer.html<https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming!>! )` Parses `data` (and any data stored from previous invocations) and emits any resulting complete `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instances via `output`. |
| `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/Subtitle!` | `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parseToLegacySubtitle(byte[],int,int)(data: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte/index.html>!, offset: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, length: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Parses `data` to a legacy `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/Subtitle` instance. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#reset()()` Clears any data stored inside this parser from previous `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)` calls. |

## Public functions

### getCueReplacementBehavior

```
@Format.CueReplacementBehavior
fun getCueReplacementBehavior(): Int
```

Returns the `https://developer.android.com/reference/kotlin/androidx/media3/common/Format.CueReplacementBehavior` for consecutive `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` emitted by this implementation.

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

### parse

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

Parses `data` (and any data stored from previous invocations) and emits resulting `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instances.

Equivalent to `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],int,int,androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)`.

### parse

```
fun parse(
    data: ByteArray<Byte>!,
    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 `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instances via `output`.

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

`https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming#startTimeUs()` in an emitted instance is derived only from the provided sample data, so has to be considered together with any relevant `https://developer.android.com/reference/kotlin/androidx/media3/common/Format#subsampleOffsetUs()`. If the provided sample doesn't contain any timing information then at most one `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming` instance will be emitted, with `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming#startTimeUs()` set to `https://developer.android.com/reference/kotlin/androidx/media3/common/C#TIME_UNSET()`, in which case `https://developer.android.com/reference/kotlin/androidx/media3/common/Format#subsampleOffsetUs()`**must** be `https://developer.android.com/reference/kotlin/androidx/media3/common/Format#OFFSET_SAMPLE_RELATIVE()`.

| Parameters |
|---|---|
| `data: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte/index.html>!` | 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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The index in `data` to start reading from (inclusive). |
| `length: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The number of bytes to read from `data`. |
| `outputOptions: https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser.OutputOptions!` | Options to control how instances are emitted to `output`. |
| `output: https://developer.android.com/reference/java/util/function/Consumer.html<https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/CuesWithTiming!>!` | A consumer for `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/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<Byte>!, offset: Int, length: Int): Subtitle!
```

Parses `data` to a legacy `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/Subtitle` instance.

This method only exists temporarily to support the transition away from `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleDecoder` and `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/Subtitle`. It will be removed in a future release.

The default implementation delegates to `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],int,int,androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)`. Implementations can override this to provide a more efficient implementation if desired.

| Parameters |
|---|---|
| `data: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte/index.html>!` | 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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The index in `data` to start reading from (inclusive). |
| `length: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The number of bytes to read from `data`. |

### reset

```
fun reset(): Unit
```

Clears any data stored inside this parser from previous `https://developer.android.com/reference/kotlin/androidx/media3/extractor/text/SubtitleParser#parse(byte[],androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)` calls.

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

The default implementation is a no-op.