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.

fun enableClosedCaption() {
    lifecycleScope.launch {
        viewActions.invoke(function = "showCaptions", arguments = "")
    }
}

fun disableClosedCaption() {
    lifecycleScope.launch {
        viewActions.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.

fun showCaptionSelector() {
    lifecycleScope.launch {
        try {
            // 1. Invoke the player function
            val result = viewActions.invoke(function = "getAvailableCaptions", arguments = "") as? Map<*, *>

            // 2. Parse the nested Dictionary
            val eventDict = result?.get("event") as? Map<*, *>
            val captionList = eventDict?.get("availableCaptions") as? List<String>

            if (captionList == null || captionList.isEmpty()) {
                println("Failed to parse caption structure or no captions available.")
                return@launch
            }

            // 3. Present the modal with the strings (e.g., "sv-SE")
            presentCaptionModal(tracks = captionList)
        } catch (e: Exception) {
            println("Error fetching captions: ${e.message}")
        }
    }
}

The result is a map 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.

fun selectTrack(id: String) {
    lifecycleScope.launch {
        // Passing the string ID inside quotes for JS
        viewActions.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.

val videoConfiguration = BambuserVideoConfiguration(
    events = listOf("*"),
    configuration = mapOf(
        "ui" to mapOf(
            "hideClosedCaptionsButton" to true
        )
    ),
    videoType = BambuserVideoAsset.Live(showId)
)

For the full configuration reference, see Configuration and Functions.