For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
StatusSupportDiscussionsLog inSign Up
Docs HomeAPI ReferenceVideo on DemandAI FeaturesLive StreamingVideo PlayerVideo DataCloud PlayoutRecipes
Docs HomeAPI ReferenceVideo on DemandAI FeaturesLive StreamingVideo PlayerVideo DataCloud PlayoutRecipes
  • Player SDKs
    • Introduction
  • Web player
    • Install the FastPix web player
    • Play uploaded videos
    • Handle playback errors
  • Android player
    • Install FastPix Android player
    • Set up the player
    • Play uploaded videos
    • Handle playback errors
  • iOS player
    • Install FastPix iOS player
    • Play uploaded videos
    • Handle playback errors
      • Secure video playback
      • Play DRM-protected content
      • Use a custom domain
      • Switch audio tracks
      • Switch subtitle tracks
      • Add seek preview thumbnails
      • Enable Picture-in-Picture
      • Enable full-screen mode
      • Manage playlists
      • Add skip controls
      • Handle network changes
  • Flutter player
    • Install FastPix Flutter player
    • Play uploaded videos
    • Handle playback errors
LogoLogo
StatusSupportDiscussionsLog inSign Up
On this page
  • Set up the subtitle track delegate
  • Set a preferred subtitle track
  • Get available subtitle tracks
  • Get the current subtitle track
  • Switch subtitle tracks
  • Disable subtitles
  • Render subtitle cues
  • Handle subtitle events
  • SubtitleTrack model
  • SubtitleRenderInfo model
iOS playerAdvanced features

Switch subtitle tracks

Was this page helpful?
Previous

Add seek preview thumbnails

Next
Built with

Learn how to detect, switch, and render subtitle tracks in the FastPix iOS Player.

The FastPix iOS Player SDK supports WebVTT-based subtitle tracks. It automatically parses the HLS manifest, fetches subtitle segments, and delivers cues in sync with playback. Your app is responsible for rendering the subtitle text in the UI.

Set up the subtitle track delegate

1playerViewController.subtitleTrackDelegate = self

Set a preferred subtitle track

Set a preferred subtitle track by language name. The SDK automatically selects it when the video loads.

1// Pass the display name of the language (case-insensitive)
2playerViewController.setPreferredSubtitleTrack("Hindi")

The preferred track is automatically applied on every playlist item change.

Get available subtitle tracks

1let subtitleTracks = playerViewController.getSubtitleTracks()

Get the current subtitle track

1// Returns nil if subtitles are disabled
2let currentTrack = playerViewController.getCurrentSubtitleTrack()

Switch subtitle tracks

1// Switch by track ID
2try? playerViewController.setSubtitleTrack(trackId: track.id)

Disable subtitles

1playerViewController.disableSubtitles()

Render subtitle cues

The SDK delivers subtitle text in real time through the onSubtitleCueChange callback. Create a label to display the text:

1private let subtitleLabel: UILabel = {
2 let label = UILabel()
3 label.textColor = .white
4 label.font = UIFont.systemFont(ofSize: 16, weight: .medium)
5 label.textAlignment = .center
6 label.numberOfLines = 0
7 label.backgroundColor = UIColor.black.withAlphaComponent(0.5)
8 label.translatesAutoresizingMaskIntoConstraints = false
9 return label
10}()

Position the label above the seek bar inside playerViewController.view:

1private func setupSubtitleLabel() {
2 playerViewController.view.addSubview(subtitleLabel)
3 playerViewController.view.bringSubviewToFront(subtitleLabel)
4
5 NSLayoutConstraint.activate([
6 subtitleLabel.leadingAnchor.constraint(
7 equalTo: playerViewController.view.leadingAnchor, constant: 20),
8 subtitleLabel.trailingAnchor.constraint(
9 equalTo: playerViewController.view.trailingAnchor, constant: -20),
10 subtitleLabel.bottomAnchor.constraint(
11 equalTo: playerViewController.view.bottomAnchor, constant: -130)
12 ])
13}

Handle subtitle events

Conform to FastPixSubtitleTrackDelegate to receive subtitle updates:

1extension VideoPlayerViewController: FastPixSubtitleTrackDelegate {
2
3 // Called when subtitle tracks finish loading
4 func onSubtitlesLoaded(tracks: [SubtitleTrack]) {
5 print("Subtitle tracks available:", tracks)
6 }
7
8 // Called when the active subtitle track changes
9 func onSubtitleChange(track: SubtitleTrack?) {
10 print("Subtitle switched to:", track?.label ?? "Off")
11 }
12
13 // Called every time a new subtitle cue becomes active
14 func onSubtitleCueChange(information: SubtitleRenderInfo) {
15 DispatchQueue.main.async {
16 if information.text.isEmpty {
17 self.subtitleLabel.isHidden = true
18 } else {
19 self.subtitleLabel.text = information.text
20 self.subtitleLabel.isHidden = false
21 }
22 }
23 }
24
25 // Called when subtitle tracks fail to load
26 func onSubtitlesLoadedFailed(error: SubtitleTrackError) {
27 print("Subtitle load failed:", error)
28 }
29}

SubtitleTrack model

PropertyTypeDescription
idStringUnique identifier for the track
languageCodeStringBCP-47 language tag (for example, "hi", "en")
labelStringHuman-readable label shown in UI
playlistURLString?Resolved URL of the subtitle playlist
isSelectedBoolWhether this track is currently active

SubtitleRenderInfo model

PropertyTypeDescription
textStringSubtitle cue text (empty string means the cue has ended)
timestampDoublePlayback time in seconds when the cue is active
languageCodeStringLanguage code of the active subtitle track

Important:

  • Subtitle rendering is the host app’s responsibility. The SDK delivers cue text only.
  • Call disableSubtitles() when switching playlist items to prevent stale cues from appearing on videos without subtitles.
  • Add the subtitle label to playerViewController.view, not self.view, to ensure correct positioning across orientations and full-screen transitions.