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, MPEG-DASH & progressive download
• In-manifest/in-band closed captions for live and on-demand video:
  • HLS: WebVTT, TTML IMSC1 & CEA 608/708
  • MPEG-DASH: WebVTT, CEA 608/708, SubRip SRT, SubViewer, SubStation Alpha,LyRiCs & TTML IMSC1

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. As such an out-of-the-box user interface is available to 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.

autoBumpCaptionsOnVisibleControlBar: Boolean

By default there is a little bump in up position for the captions to remain visible when the control bar is also visible. This setting disables this change in position, which might be needed for some captions types. Default: true.

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.<TextTrack>

This setting holds WebVTT closed captions data such as language, name, URI and default behaviour. Each TextTrack Object is having the following properties:

• lng: String - the 2 digit ISO 639-1 (two-letter) language code
• name: String - the track name (to be displayed in captions module)
• uri: String - the URI to vtt file
• default: Boolean - is this text track enabled by default on player start?

const ccFiles = [
  {
    lng: 'en',
    name: 'English',
    uri: 'https://www.radiantmediaplayer.com/media/vtt/captions/cc.vtt',
    default: false
  },
  {
    lng: 'fr',
    name: 'Français',
    uri: 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-fr.vtt',
    default: true
  }
];

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/10.1.4/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 = [
    {
      lng: 'en',
      name: 'English',
      uri: 'https://www.radiantmediaplayer.com/media/vtt/captions/cc.vtt',
      default: false
    },
    {
      lng: 'fr',
      name: 'Français',
      uri: 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-fr.vtt',
      default: false
    }
  ];
  // Your player settings
  const settings = {
    licenseKey: 'your-license-key',
    src,
    width: 640,
    height: 360,
    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');

  // Player initialisation
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);  
      console.log('player ready');
    } catch (error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer(); 

</script>

HLS & MPEG-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 & MPEG-DASH for the following caption types. Language information for the captions are directly read from the HLS or MPEG-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)
• MPEG-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 MPEG-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/10.1.4/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmp"></div>
<script>
// This sample MPEG-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,
    width: 640,
    height: 360,
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };
  const rmp = new RadiantMP('rmp');

  // Player initialisation
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);  
      console.log('player ready');
    } catch (error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();

</script>

Captions API

We provide a unified captions API allowing to programatically control captions being displayed by the player regardless of the nature of the captions track. Refer to our player API documentation for guidance on using our player API.

Captions API events

texttrackchanged

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

texttrackloaded

Fires each time a text track is successfully loaded.

texttrackloaderror

Fires each time a text track fails to load.

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

showCaptions(lng)

This method will display closed captions for the queried input language (lng). The input language parameter must be a 2 digit ISO 639-1 (two-letter) String for side-loaded WebVTT closed captions files. For HLS & MPEG-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();

ccVisibleLanguage getter (String)

This getter 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 & MPEG-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.ccVisibleLanguage;

captionsData getter

This getter returns an Array of Object representing the raw data for the currently loaded captions track.

For vtt.js (externally loaded), an Object representing a cue with the following properties:

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

For native text tracks (externally loaded for iOS), an Object representing cues with the following properties:

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

For hls.js, 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 (MPEG-DASH or HLS with hlsEngine: 'shakaplayer' setting), 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.

captionsList getter|setter (Array.<TextTracks>)

get|set Array.<TextTracks> representing the current list of loaded text tracks.
For captionsList getter: tracks that fail to load will not be listed. Use when alltexttracksloaded API event fires.
Example:

const currentTextTracks = rmp.captionsList;
const newTextTracks = [
  {
    lng: 'de',
    name: 'Deutsch',
    uri: 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-de.vtt',
    default: false
  },
  {
    lng: 'nl',
    name: 'Nederlands',
    uri: 'https://www.radiantmediaplayer.com/media/vtt/captions/cc-nl.vtt',
    default: false
  }
];
rmp.captionsList = newTextTracks;

Updating captions when changing player source

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

• Side-loaded VTT captions
  • Call setSrc with your new content source
  • When srcchanged event fires use captionsList setter with your new list of captions
• In-manifest VTT for HLS/MPEG-DASH: when calling setSrc the player will attempt to update the available captions list, support for this feature varies depending on device/streaming engine
  • Shaka player: full support for MPEG-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