Closed Captions & Subtitles

Scope of support

Radiant Media Player supports multi-languages closed captions (or subtitles) in the following formats:

• Side-loaded WebVTT closed captions files for on-demand video. WebVTT files are passed to the player through the ccFiles player settings. This use-case is supported for HLS, DASH & progressive download
• In-manifest/in-band closed captions for live and on-demand video:
  • HLS: WebVTT, IMSC1 & CEA 608/708
  • DASH: WebVTT & TTML

Casting and managing captions is also supported with Google Cast.

Captions styling (FCC compliant)

Radiant Media Player is committed to ensuring better accessibility with our video player for all of your viewers. With Radiant Media Player 5.10 we continue this commitment with an out-of-the-box UI for viewers to style captions directly within the player. Laws in the United States mandate that certain content providers, such as broadcasters, include captions with all of their videos. Thus we now expose all nine FCC compliant attributes and values.

You can also set initial values for styling closed captions. The following player settings are available:

ccFontColor: String

Closed captions initial font color. Default: 'white'. Other possible values are: 'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan'.

ccFontOpacity: Number

Closed captions initial font opacity. Default: 1. Other possible values are: 0.75, 0.5, 0.25.

ccFontSize: Number

Closed captions initial font size (1 means 100%). Default: 1. Other possible values are: 3, 2, 1.75, 1.5, 1.25, 1, 0.75, 0.5.

ccFontFamily: String

Closed captions initial font family. Default: 'arial'. Other possible values are: 'courier', 'georgia', 'impact', 'lucida console', 'tahoma', 'times new roman', 'trebuchet ms', 'verdana'.

ccFontEdge: String

Closed captions initial font edge style. Default: 'none'. Other possible values are: 'raised', 'depressed', 'outline', 'drop shadow'.

ccBackgroundColor: String

Closed captions initial background color. Default: 'black'. Other possible values are: 'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan'.

ccBackgroundOpacity: Number

Closed captions initial background opacity (0.5 means 50%). Default: 0.5. Other possible values are: 1, 0.75, 0.25, 0.

ccWindowColor: String

Closed captions initial window color. Default: 'black'. Other possible values are: 'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan'.

ccWindowOpacity: String

Closed captions initial window opacity (0 means 0%). Default: 0. Other possible values are: 1, 0.75, 0.5, 0.25.

Side-loaded WebVTT closed captions files

Player settings

You can side-load WebVTT closed captions files in Radiant Media Player. This is done through the ccFiles player setting. Our player makes use of vtt.js to render closed captions with the ccFiles setting with the exception of iOS where captions are rendered with Safari native engine. For vtt.js, all WebVTT files are ajax-loaded and as such appropriate CORS settings are expected for retrieval of WebVTT files.

ccFiles: Array

This setting holds WebVTT closed captions files location to be displayed along the video within the player. Default: []. Multi-language WebVTT closed captions can be added to the player. Example:

const ccFiles = [
  ['en', 'English', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc.vtt'],
  ['fr', 'Français', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-fr.vtt']
];

ccFiles[i]: Array

ccFiles[i][0]: String is the ISO 639-1 (two-letter) code for the closed captions language
ccFiles[i][1]: String is the human-readable label for the closed captions language (this information will be displayed within the player captions menu)
ccFiles[i][2]: String is the WebVTT closed captions file location for player.

It is possible to set a default attribute to a specific caption track. This will cause the related caption track to be activated by default when player starts. Example:

const ccFiles = [
  ['en', 'English', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc.vtt'],
  ['fr', 'Français', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-fr.vtt', 'default']
];

On iOS, captions are rendered with Safari native captions engine with ccFiles setting - this means that FCC settings cannot be ported to fullscreen and will only be available in window mode.

Styling WebVTT closed captions through embedded WebVTT data

The player shall honor any standard-compliant styling & positioning information that are held within the WebVTT file (position, line, italic or bold tags ...).

Player code example - see this example here

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/9.15.3/js/rmp-vttjs.min.js"></script>
<!-- Player container element -->
<div id="rmp"></div>
<script>
const src = {
  hls: 'https://your-hls-url.m3u8'
};
// Your WebVTT closed captions
const ccFiles = [
  ['en', 'English', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc.vtt'],
  ['fr', 'Français', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-fr.vtt']
];
// Your player settings
const settings = {
  licenseKey: 'your-license-key',
  src: src,
  width: 640,
  height: 360,
  ccFiles: ccFiles,
  crossorigin: 'anonymous', // On iOS this is required for loading cross-origin VTT files
  contentMetadata: {
    poster: [
      'https://your-poster-url.jpg'
    ]
  }
};
const rmp = new RadiantMP('rmp');
rmp.init(settings);
</script>

HLS & DASH in-manifest/in-band closed captions for live & on-demand video

Supported closed captions type

We support in-stream multi-language closed captions with HLS & DASH for the following caption types. Language information for the captions are directly read from the HLS or DASH manifest and automatically displayed on the player when detected. Note that in this case captions may be rendered with the native HTML5 track tag and as such browser support and styling options may vary.

• HLS (with hls.js)
  • WebVTT (in-manifest)
  • TTML IMSC1
  • CEA 608/708 (in-band)
• DASH (with Shaka Player)
  • WebVTT (in-manifest)
  • TTML IMSC1
  • CEA 608/708 (in-band)
  • SubRip SRT (in-manifest)
  • SubViewer (SBV)
  • SubStation Alpha (SSA)
  • LyRiCs (LRC)

Player code example

Following is a player code example for a DASH stream with embedded multi-language WebVTT captions.

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/9.15.3/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmp"></div>
<script>
// This sample DASH stream has multi-language VTT tracks referenced in its manifest
// The player will automatically pick them up and display the captions UI
const src = {
  dash: '//storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd' 
};
const settings = {
  licenseKey: 'your-license-key',
  src: src,
  width: 640,
  height: 360,
  contentMetadata: {
    poster: [
      'https://your-poster-url.jpg'
    ]
  }
};
const rmp = new RadiantMP('rmp');
rmp.init(settings);
</script>

Captions API

Since Radiant Media Player 4.5.13 we provide a unified captions API allowing to programatically control captions being displayed by the player. This unified captions API works for HLS & DASH in-manifest/in-band closed captions and side-loaded WebVTT closed captions files. Refer to our player API documentation for guidance on using the player API.

Captions API events

texttrackchanged

Fires each time a caption track change happens in the player. Note that this event also fires when all caption tracks become hidden ('off' state).

Captions API methods

showCaptions(lng)

When invoked, this method will display closed captions for the queried language passed as an input parameter. The input language parameter must be a 2 digit ISO 639-1 (two-letter) String for side-loaded WebVTT closed captions files. For HLS & DASH in-manifest/in-band captions you need to adhere to the language format provided in the manifest which may not be 2 digit ISO 639-1.

rmp.showCaptions('en');

hideCaptions()

When invoked, this method will hide all closed captions tracks.

rmp.hideCaptions();

getCCVisibleLanguage()

This method will return String representing the language code for the currently displayed caption track. For side-loaded WebVTT closed captions files this will be a 2 digit ISO 639-1 string. For HLS & DASH in-manifest/in-band captions this will be the format presented in the manifest which may not be 2 digit ISO 639-1. If no caption is displayed (meaning all captions tracks are hidden) 'off' is returned.

rmp.getCCVisibleLanguage();

Captions API events

The following events fire only for vtt.js based implementations:

texttrackloaded

Fires each time a text track is successfully loaded.

texttrackloaderror

Fires each time a text track fails to load.

The following event fires for vtt.js, native VTT, hls.js and Shaka player embedded captions:

alltexttracksloaded

Fires when all text tracks have been loaded. One text track must at least successfully load for this event to fire.

Captions API methods

getCaptionsData()

This method will return Array of Object representing the raw data for the currently loaded captions track.

For vtt.js each item in the array is an Object representing a cue with the following properties available:

{
  align: String,
  endTime: Number,
  line: String,
  position: String,
  startTime: Number,
  text: String
}

For native VTT each item in the array is an Object representing the following properties:

{
  activeCues: TextTrackCueList,
  cues: TextTrackCueList,
  id: String,
  kind: String,
  label: String,
  language: String,
  mode: String,
  oncuechange: Function
}

For hls.js embedded captions each item in the array is an Object representing the following properties:

{
  autoselect: Boolean,
  default: Boolean,
  forced: Boolean,
  groupId: String,
  id: Number,
  lang: String,
  name: String,
  type: String,
  url: String
}

For Shaka player embedded captions each item in the array is an Object representing the following properties:

{
  active: Boolean,
  bandwidth: Number,
  id: Number,
  kind: String,
  label: String,
  language: String,
  mimeType: String,
  primary: Boolean,
  type: String
}

This method should be invoked immediately after the texttrackchanged event has fired to get the raw data for the newly loaded captions track.

getCaptionsList()

This method will return Array of Array representing the successfully loaded text tracks. Tracks that fail to load will not be listed. This method becomes available when alltexttracksloaded event fires. Each track in the tracks list is an Array with the following ordered data (the following is an example or returned value):

[
  "en",
  "English",
  "Raw VTT text",
  "default"
]

For each track: index 0 shows the language code for the track - index 1 shows the human readable language for the track - index 2 shows the raw text parsed from the VTT files (on iOS this is not available, instead the URL to the VTT file is shown) - index 3 shows '' or 'default' depending on whether or not the track is set as default. All items from the list are String.

setCaptionsList(newCCFiles)

This method will update the available captions for the player when using side-loaded VTT captions (e.g. ccFiles setting).

const newCCFiles = [
  ['de', 'Deutsch', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-de.vtt'],
  ['es', 'Spanish', 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-es.vtt']
];
rmp.setCaptionsList(newCCFiles);

Updating captions when changing player source

If you want to use update closed captions in the player several options are available:

• Side-loaded VTT captions (preferred method)
  • Call setSrc with your new content source
  • When srcchanged event fires call setCaptionsList with your new list of captions
• In-manifest VTT for HLS/DASH: when calling setSrc the player will attempt to update the available CC list, support for this feature varies depending on device/streaming engine
  • Shaka player: full support for DASH and HLS updates of VTT & TTML captions
  • hls.js: partial support for updates of VTT captions (updates of CEA* captions not supported) - feedback is welcomed to improve support
  • Native HLS (mainly for iOS): updates of captions depends on the native player capabilities to provide this feature - on iOS this means captions menu selector will only be available in fullscreen but will support changes in VTT captions when player source is changed
• Destroy player instance and replace player from DOM: yet a more taxing method than using setSrc but that will allow to update the captions list reliably