Skip to main content

​
TextTrack

Represents a text track (subtitle or caption track) available in the video. 
interface TextTrack {
  id: string;
  label: string;
  language?: string;
  selected: boolean;
}

​
Properties

​
id
string
required
Unique identifier for the text track.
id: 'track-en-001'
​
label
string
required
Display label for the text track. This is typically shown to users when selecting subtitles.
label: 'English'
label: 'Spanish (Latin America)'
label: 'French (SDH)'
​
language
string
ISO 639-1 or ISO 639-2 language code identifying the track’s language.
language: 'en'  // English
language: 'es'  // Spanish
language: 'fr'  // French
language: 'zh-CN'  // Simplified Chinese
​
selected
boolean
required
Whether this text track is currently selected/active.
selected: true  // This track is currently displayed
selected: false // This track is available but not active

​
Usage

Text tracks are typically retrieved from the video player and used to display available subtitle/caption options to the user.

​
Getting Available Text Tracks

import { VideoPlayer } from 'react-native-video';

const player = VideoPlayer.create({
  uri: 'https://example.com/video.mp4'
});

// Get all available text tracks
const tracks = await player.getTextTracksAsync();

tracks.forEach((track) => {
  console.log(`${track.label} (${track.language}) - ${track.selected ? 'Active' : 'Inactive'}`);
});

​
Selecting a Text Track

import { VideoPlayer } from 'react-native-video';

const player = VideoPlayer.create({
  uri: 'https://example.com/video.mp4'
});

// Get available tracks
const tracks = await player.getTextTracksAsync();

// Find the Spanish track
const spanishTrack = tracks.find(track => track.language === 'es');

if (spanishTrack) {
  // Select the track by its ID
  await player.setSelectedTextTrackAsync(spanishTrack.id);
}

​
Building a Track Selector UI

import React, { useEffect, useState } from 'react';
import { View, Text, TouchableOpacity, FlatList } from 'react-native';
import { VideoPlayer, TextTrack } from 'react-native-video';

interface TrackSelectorProps {
  player: VideoPlayer;
}

const TrackSelector: React.FC<TrackSelectorProps> = ({ player }) => {
  const [tracks, setTracks] = useState<TextTrack[]>([]);

  useEffect(() => {
    loadTracks();
  }, []);

  const loadTracks = async () => {
    const availableTracks = await player.getTextTracksAsync();
    setTracks(availableTracks);
  };

  const selectTrack = async (trackId: string) => {
    await player.setSelectedTextTrackAsync(trackId);
    await loadTracks(); // Refresh to update selected state
  };

  const renderTrack = ({ item }: { item: TextTrack }) => (
    <TouchableOpacity
      onPress={() => selectTrack(item.id)}
      style={{
        padding: 12,
        backgroundColor: item.selected ? '#007AFF' : '#F0F0F0'
      }}
    >
      <Text style={{ color: item.selected ? 'white' : 'black' }}>
        {item.label}
        {item.language && ` (${item.language})`}
      </Text>
    </TouchableOpacity>
  );

  return (
    <View>
      <Text style={{ fontSize: 18, fontWeight: 'bold', padding: 12 }}>
        Subtitles
      </Text>
      <FlatList
        data={tracks}
        renderItem={renderTrack}
        keyExtractor={(item) => item.id}
      />
    </View>
  );
};

export default TrackSelector;

​
Disabling Text Tracks

import { VideoPlayer } from 'react-native-video';

const player = VideoPlayer.create({
  uri: 'https://example.com/video.mp4'
});

// Disable all text tracks (hide subtitles)
await player.setSelectedTextTrackAsync(null);

​
Examples

​
Example Text Track Objects

const englishTrack: TextTrack = {
  id: 'track-001',
  label: 'English',
  language: 'en',
  selected: true
};

const spanishTrack: TextTrack = {
  id: 'track-002',
  label: 'Español (Latinoamérica)',
  language: 'es',
  selected: false
};

const sdhTrack: TextTrack = {
  id: 'track-003',
  label: 'English (SDH)',
  language: 'en',
  selected: false
};

const noLanguageTrack: TextTrack = {
  id: 'track-004',
  label: 'Subtitles',
  selected: false
  // language is optional
};

​
Filtering Tracks by Language

import { VideoPlayer, TextTrack } from 'react-native-video';

const player = VideoPlayer.create({
  uri: 'https://example.com/video.mp4'
});

const tracks = await player.getTextTracksAsync();

// Get only English tracks
const englishTracks = tracks.filter(
  (track: TextTrack) => track.language === 'en'
);

// Get the currently selected track
const selectedTrack = tracks.find(
  (track: TextTrack) => track.selected
);

console.log('Selected track:', selectedTrack?.label);

​
Platform Behavior

​
iOS/visionOS/tvOS

  • Text tracks are automatically detected from HLS manifests
  • Native subtitle rendering is used
  • Labels may be overridden by the system player

​
Android

  • Supports embedded tracks in videos
  • External subtitle files loaded via externalSubtitles in VideoConfig
  • Custom subtitle rendering

Build docs developers (and LLMs) love

Get started for freeTalk to us