# TtmlParser

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/ttml/TtmlParser.java+class:androidx.media3.extractor.text.ttml.TtmlParser)

*** ** * ** ***


```
@UnstableApi
public final class TtmlParser implements SubtitleParser
```

<br />

*** ** * ** ***

A `https://developer.android.com/reference/androidx/media3/extractor/text/SimpleSubtitleDecoder` for TTML supporting the DFXP presentation profile. Features supported by this decoder are:

- content
- core
- presentation
- profile
- structure
- time-offset
- timing
- tickRate
- time-clock-with-frames
- time-clock
- time-offset-with-frames
- time-offset-with-ticks
- cell-resolution

See the [TTML specification](http://www.w3.org/TR/ttaf1-dfxp/)

## Summary

| ### Constants |
|---|---|
| `static final int` | `@https://developer.android.com/reference/androidx/media3/common/Format.CueReplacementBehavior https://developer.android.com/reference/androidx/media3/extractor/text/ttml/TtmlParser#CUE_REPLACEMENT_BEHAVIOR() = 1` The `https://developer.android.com/reference/androidx/media3/common/Format.CueReplacementBehavior` for consecutive `https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming` emitted by this implementation. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/extractor/text/ttml/TtmlParser#TtmlParser()()` |

| ### Public methods |
|---|---|
| `int` | `@https://developer.android.com/reference/androidx/media3/common/Format.CueReplacementBehavior https://developer.android.com/reference/androidx/media3/extractor/text/ttml/TtmlParser#getCueReplacementBehavior()()` Returns the `https://developer.android.com/reference/androidx/media3/common/Format.CueReplacementBehavior` for consecutive `https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming` emitted by this implementation. |
| `void` | `https://developer.android.com/reference/androidx/media3/extractor/text/ttml/TtmlParser#parse(byte[],int,int,androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)( byte[] data, int offset, int length, https://developer.android.com/reference/androidx/media3/extractor/text/SubtitleParser.OutputOptions outputOptions, https://developer.android.com/reference/java/util/function/Consumer.html<https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming> output )` Parses `data` (and any data stored from previous invocations) and emits any resulting complete `https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming` instances via `output`. |
| `https://developer.android.com/reference/androidx/media3/extractor/text/Subtitle` | `https://developer.android.com/reference/androidx/media3/extractor/text/ttml/TtmlParser#parseToLegacySubtitle(byte[],int,int)(byte[] data, int offset, int length)` Parses `data` to a legacy `https://developer.android.com/reference/androidx/media3/extractor/text/Subtitle` instance. |

### Inherited methods

From [androidx.media3.extractor.text.SubtitleParser](https://developer.android.com/reference/androidx/media3/extractor/text/SubtitleParser) `void` `https://developer.android.com/reference/androidx/media3/extractor/text/SubtitleParser#parse(byte[],androidx.media3.extractor.text.SubtitleParser.OutputOptions,java.util.function.Consumer<androidx.media3.extractor.text.CuesWithTiming>)(
byte[] data,
https://developer.android.com/reference/androidx/media3/extractor/text/SubtitleParser.OutputOptions outputOptions,
https://developer.android.com/reference/java/util/function/Consumer.html<https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming> output
)`

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

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

## Constants

### CUE_REPLACEMENT_BEHAVIOR

```
@Format.CueReplacementBehavior
public static final int CUE_REPLACEMENT_BEHAVIOR = 1
```

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

## Public constructors

### TtmlParser

```
public TtmlParser()
```

## Public methods

### getCueReplacementBehavior

```
@Format.CueReplacementBehavior
public int getCueReplacementBehavior()
```

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

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

### parse

```
public void parse(
    byte[] data,
    int offset,
    int length,
    SubtitleParser.OutputOptions outputOptions,
    Consumer<CuesWithTiming> output
)
```

Parses `data` (and any data stored from previous invocations) and emits any resulting complete `https://developer.android.com/reference/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/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/androidx/media3/common/Format#subsampleOffsetUs()`. If the provided sample doesn't contain any timing information then at most one `https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming` instance will be emitted, with `https://developer.android.com/reference/androidx/media3/extractor/text/CuesWithTiming#startTimeUs()` set to `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()`, in which case `https://developer.android.com/reference/androidx/media3/common/Format#subsampleOffsetUs()`**must** be `https://developer.android.com/reference/androidx/media3/common/Format#OFFSET_SAMPLE_RELATIVE()`.

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

```
public Subtitle parseToLegacySubtitle(byte[] data, int offset, int length)
```

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

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

The default implementation delegates to `https://developer.android.com/reference/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 |
|---|---|
| `byte[] data` | 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. |
| `int offset` | The index in `data` to start reading from (inclusive). |
| `int length` | The number of bytes to read from `data`. |