Captions

This page describes how to manage captions and subtitles in the Bambuser player.

Overview

The Bambuser player supports displaying captions and subtitles to enhance accessibility and viewer experience. You can:

• Show or hide captions
• Retrieve a list of available caption tracks
• Select a specific caption track for display

Show or Hide Captions

Use the showCaptions and hideCaptions invoke functions to control the visibility of captions.

func enableClosedCaption() {
    Task { @MainActor in
        try await playerView?.invoke(function: "showCaptions", arguments: "")
    }
}

func disableClosedCaption() {
    Task { @MainActor in
        try await playerView?.invoke(function: "hideCaptions", arguments: "")
    }
}

Retrieve Available Captions

Use the getAvailableCaptions invoke function to fetch a list of available caption tracks. This allows you to present a selection to the user.

func showCaptionSelector() {
    Task { @MainActor in
        do {
            // 1. Invoke the player function
            let result = try await playerView?.invoke(function: "getAvailableCaptions", arguments: "")

            // 2. Parse the nested Dictionary
            guard let baseDict = result as? [String: Any],
                  let eventDict = baseDict["event"] as? [String: Any],
                  let captionList = eventDict["availableCaptions"] as? [String] else {
                print("Failed to parse caption structure or no captions available.")
                return
            }

            // 3. Present the modal with the strings (e.g., "sv-SE")
            presentCaptionModal(tracks: captionList)
        } catch {
            print("Error fetching captions: \(error)")
        }
    }
}

The result is a dictionary with the following structure:

{
  "event": {
    "availableCaptions": ["sv-SE", "en-US", "fr-CA"]
  }
}

Select a Caption Track

Use the selectCaptionTrack invoke function to select a specific caption track by its ID.

func selectTrack(id: String) {
    Task { @MainActor in
        // Passing the string ID inside quotes for JS
        try? await playerView?.invoke(function: "selectCaptionTrack", arguments: "'\(id)'")

        // Also call showCaptions to ensure they are visible
        enableClosedCaption()
    }
}

Configuration

You can control the visibility of the closed captions button using the ui.hideClosedCaptionsButton configuration flag. By default, the captions button is visible.

Config Key	Type	Default	Description
ui.hideClosedCaptionsButton	boolean	false	Hides the closed captions / subtitles button.

let config = BambuserVideoConfiguration(
    type: .live(id: "your-show-id"),
    events: ["*"],
    configuration: [
        "ui": [
            "hideClosedCaptionsButton": true
        ]
    ]
)

For the full configuration reference, see Configuration and Functions.