> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Switch subtitle tracks

> Learn how to discover, switch, and disable subtitle tracks in the FastPix Android Player.

Learn how to discover, switch, and disable subtitle tracks in the FastPix Android Player.

## SubtitleTrack properties

Each `SubtitleTrack` includes:

* `id`: pass to `setSubtitleTrack(id)` to switch tracks.
* `languageCode` / `languageName` / `label`: display in your subtitle menu.
* `isSelected`, `isPlayable`, `isDefault`, `isForced`: for UI state.
* Optional: `role`, `codec`, `groupId`.

## Listen for subtitle track updates

```kotlin
import io.fastpix.media3.tracks.SubtitleTrackListener

player.addSubtitleTrackListener(object : SubtitleTrackListener {
    override fun onSubtitlesLoaded(tracks: List<SubtitleTrack>) {
        // Populate subtitle selection UI
    }
    override fun onSubtitleChange(track: SubtitleTrack?) {
        // track == null means subtitles are disabled
    }
    override fun onSubtitlesLoadedFailed(error: SubtitleTrackError) {
        // Track not found, not playable, player not ready, etc.
    }
    override fun onSubtitleCueChange(info: SubtitleRenderInfo) {
        // Optional: observe cues (text + timing) if building a custom subtitle renderer
    }
})
```

## Switch subtitle track by ID

```kotlin
val subs = player.getSubtitleTracks()
val current = player.getCurrentSubtitleTrack()   // currently selected track, null if none or disabled
val target = subs.firstOrNull()
if (target != null) {
    player.setSubtitleTrack(target.id)
}
```

## Disable subtitles

```kotlin
player.disableSubtitles()
```

## Set a default subtitle language

Set a preferred subtitle language that applies automatically when tracks become available. This never overrides a manual selection:

```kotlin
player.setDefaultSubtitleTrack(languageName = "Spanish")
```

Use BCP-47 / ISO language names like `"English"`, `"Spanish"`, `"Hindi"`. If the preferred language doesn't exist in the stream, the player keeps its normal selection.

## Remove the subtitle track listener

Keep a reference to your `SubtitleTrackListener` and remove it when it is no longer needed:

```kotlin
player.removeSubtitleTrackListener(listener)
```

\


#### Frequently asked questions

Read the available tracks with `player.getSubtitleTracks()`, then enable one by id with `player.setSubtitleTrack(track.id)`. Playback position and state are preserved when you switch, so the video does not restart.

Call `player.disableSubtitles()` to turn subtitles off. Playback position and state are preserved, though forced subtitles may still render depending on the stream. In `onSubtitleChange`, a `null` track means subtitles are disabled.

Call `player.setDefaultSubtitleTrack(languageName = "Spanish")` with a BCP-47 / ISO language name. It applies automatically when tracks become available and never overrides a manual selection or a "subtitles disabled" state. If the language is not present, the player keeps its normal selection.

Implement `onSubtitleCueChange(info: SubtitleRenderInfo)` in a `SubtitleTrackListener`. Each `SubtitleCueInfo` in `info.cues` has `text`, `startTimeMs`, and `endTimeMs`, which you can use to drive a custom overlay such as a `TextView`.

\


## What's next

* [Switch audio tracks](/docs/android-player/switch-audio-tracks) to let viewers choose an alternate audio language.
* [Switch video quality](/docs/android-player/switch-video-quality) so users can lock a fixed resolution or return to adaptive auto mode.
* [Listen to playback events](/docs/android-player/listen-to-playback-events) to keep your caption menus and player UI in sync.