Skip to navigation
Android playerAdvanced features

Switch subtitle tracks

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

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

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

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:

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:

player.removeSubtitleTrackListener(listener)

Frequently asked questions

How do I turn on subtitles in the FastPix Android player?

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.

How do I disable captions?

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.

How do I set a default subtitle language?

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.

How do I render custom subtitle cues?

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