Subtitle/Captioning and Audio tracks

Mobile		Tablet		Web	TV platforms

The DIVA 5.0 SDK provides the Subtitles, Captioning, and Audio track selection via the player Settings panel (available for live and VOD videos if available in the stream-manifest).

Supported formats: 608, in-stream WebVTT

The DIVA SDK supports Subtitles, Captioning, and Audio track selection for HLS and Dash video formats. External integrators must define the best approach to add the tracks into the manifest file.

DIVA requirements

The DIVA video player provides some parameters to enable functionality; read on for more information:

DIVA setting and videoMetaData

DIVA must receive the following Setting parameters:

• closedCaptionSelectionMethod
• audioSelectionMethog
• preferredAudioTrackName
• preferredClosedCaptionName
• audioTrack array with AudioTracks
• cc

note

• The integrated application is responsible for ensuring the user selection persists across different DIVA sessions. DIVA provides a callback to manage the selection:

Web

const divaParams = {
    
    onPreferredCCTrack: function(value) {
        console.log('-- Preferred Text track: '+value+' --');
    },
    
    onPreferredAudioTrack: function(value) {
        console.log('-- Preferred Audio track: '+value+' --');
    },

};
const { element: divaElement, api: divaAPI } = newDiva('.diva-player-container', divaParams);

Android

val divaListener: DivaListener = object : DivaListener {

    override fun onAudioTrackSelected(track: String) {
        Log.d("DivaListener", "onAudioTrackSelected - Track selected: $track")
    }

    override fun onClosedCaptionTrackSelected(track: String) {
        Log.d("DivaListener", "onClosedCaptionTrackSelected - Track selected: $track")
    }

}

iOS

typealias AudioTrackCallback = (String) -> Void
typealias ClosedCaptionCallback = (String) -> Void
var onPreferredAudioTrack: Diva.AudioTrackCallback?
var onPreferredCCTrack: Diva.ClosedCaptionCallback?

config.onPreferredCCTrack = { track in
    print("[onPreferredCCTrack] track: \(track)")
}
config.onPreferredAudioTrack = { track in
    print("[onPreferredAudioTrack] track: \(track)")
}

tvOS

typealias AudioTrackCallback = (String) -> Void
typealias ClosedCaptionCallback = (String) -> Void
var onPreferredAudioTrack: Diva.AudioTrackCallback?
var onPreferredCCTrack: Diva.ClosedCaptionCallback?

config.onPreferredCCTrack = { track in
    print("[onPreferredCCTrack] track: \(track)")
}
config.onPreferredAudioTrack = { track in
    print("[onPreferredAudioTrack] track: \(track)")
}

WebTV

const onAudioTrackChange = (audioTrack: string) => {
    console.log(`preferredAudioTrack ${audioTrack}`)
};

const preferredCCTrackName = "English";
const preferredAudioTrackName = "English";

const Player = () =>{
    // ...
    return (
        <DivaWebTV
            // ...
            init={{
                // ...
                preferredCCTrackName,
                preferredAudioTrackName
                // ...
            }}
            // ...
            onPreferredAudioTrack={onAudioTrackChange}
            // ...
        />
    )
}

Roku

sub launchDivaPlayer()
	...

	observeDivaPlayerSelectedAudioTrack("onSelectedAudioTrackHandler")
	observeDivaPlayerSelectedCC("onSelectedCCTrackHandler")
    ...
	runDivaPlayer()
end sub

sub onSelectedCCTrackHandler(evt as dynamic)
	' data = evt.getData()
end sub

sub onSelectedAudioTrackHandler(evt as dynamic)
	' data = evt.getData()
end sub

DIVA translations

• Subtitles and Captioning label: diva_cc_identifier (where the identifier value is the result of the track found based on the selection method defined)
• Subtitles and Captioning "disabled" label: diva_cc_disabled
• Audio tracks label: label value in AudioTrack
• Closed Caption selection panel button tooltip: diva_cc_button_tooltip
• CC feature Title within settings panel: diva_cc_settings_title
• Audio Language selection panel button tooltip: diva_at_button_tooltip
• Audio Language selection panel Title: diva_at_settings_title
• Audio and close caption languages translations are provided by tvOS based on host application localizations and device language selection.

Analytics

For Subtitles, Closed Captions, and Audio Tracks, DIVA raises external Analytic events

Known issues and limitations

Please check the Known issues page for feature specific information.

Product documentation

For visuals and behaviors, visit the DIVA help centre Audio tracks and DIVA help centre Subtitles and Captioning articles.

tvOS

tvOS has some special behaviour for this feature.

• Audio Tracks: The player displays the audio languages that are available in the video manifest, therefore it is recommended to have a video stream manifest that contains only the language(s) to be offered to end users. Translation is provided by tvOS as described above.
• Closed captions and subtitles: Localisation is provide by tvOS as described above.
• The Diva player communicates with tvOS to notify when a user has initiated an audio or subtitle change. This allows tvOS to use default behaviour when the integrator hasn't set preferredAudioTrack or/and preferredClosedCaption.

Roku

Roku has some special behaviour for this feature.

• Closed captions Tracks: Video node native component has restricted track api for tracks filtering, only "Language" property is available and used for translation keys generating.
• Closed captions and Audio Tracks: Both types of tracks changing is available on system level by special system menu. Diva Player synchronizes both selections with internal panels and flow.