Display Overlay Plugin

Overview

You can control the display of the overlay message based on:

• Player events - such as play, pause or custom events
• Time interval - at a specified time during video playback

The sample video below demonstrates the use of the Overlay Plugin. An overlay will appear on start as well as different time periods, one starting at five seconds. Start and pause the video to see the overlay react to those events.

This topic contains the following sections:

• Implementing using Players module
• Implementing using custom code
• Overlay Plugin options

Implement using Players module

To implement the Overlay Plugin using the Players module, follow these steps:

1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
2. Click the link for the player to open the player's properties.
3. In the left navigation, click Plugins.
4. Expand the Add a Plugin dropdown menu, and select Custom Plugin.

   

5. For the Plugin Name enter overlay.
6. For the JavaScript URL, enter:

   https://players.brightcove.net/videojs-overlay/3/videojs-overlay.min.js

7. For the CSS URL, enter:

   https://players.brightcove.net/videojs-overlay/3/videojs-overlay.css

8. Enter the configuration options in the Options(JSON) text box. The example below will display an anchor at the bottom of the player starting at the 2 second mark and ending at the 6 second mark.

   {
     "overlays": [
       {
         "align": "bottom",
         "start": 2,
         "end": 6,
         "content": "<a href='http://www.brightcove.com'>Proceed to Home Page</a>"
       }
     ]
   }

9. Check to be sure the form appears as follows:

   

10. Click Save.
11. To publish the player, click Publish & Embed > Publish Changes.
12. To close the open dialog, click Close.

Implement using code

To implement the plugin using custom code, you will configure the following plugin properties:

• scripts - JavaScript supplied for the plugin and will not change for different plugin implementations
• stylesheets - CSS supplied to you for the plugin and will not change for different plugin implementations
• plugin name - Always overlay
• plugin options - Contains an array of properties and values

To add the plugin to your code, follow these steps:

1. Add the overlay plugin default style sheet. You can use the default style sheet, or create your own styles.

   <link href="https://players.brightcove.net/videojs-overlay/3/videojs-overlay.css" rel='stylesheet'>

2. Add the videojs-overlay.js script file to include the overlay plugin. This plugin will automatically register itself when included in your page.

   <video-js id="myPlayerID"
       data-account="1752604059001"
       data-player="972ee851-3d7e-43a0-8db1-2c6fb06bad34"
       data-embed="default"
       controls="">
   </video-js>
   
   <script src="https://players.brightcove.net/1752604059001/972ee851-3d7e-43a0-8db1-2c6fb06bad34_default/index.min.js"></script>
   
   <script src="https://players.brightcove.net/videojs-overlay/3/videojs-overlay.min.js"></script>

3. Get a reference to the Brightcove Player. In this example, we are creating a variable named myPlayer and assigning it a reference to the player.

   <script>
     videojs.getPlayer('myPlayerID').ready(function() {
       var myPlayer = this;
     });
   </script>

   To display an overlay message, use the options property to pass data to the plugin. This example shows how to include 3 overlay messages:

   • First overlay:
     • This is displayed when the play event is dispatched and is hidden when the pause event is dispatched.
   • Second overlay:
     • This is displayed when the video playback passes 5 seconds and is hidden when the video playback passes 10 seconds.
     • This is positioned in the bottom right corner of the player.
   • Third overlay:
     • This is displayed when the video playback passes 12 seconds and is hidden when the video playback passes 17 seconds.
     • This is positioned in the bottom left corner of the player.
     • Since this overlay does not have a content option defined, it uses the default value of Default overlay content, defined before the overlays array.
    

   If you include the overlay script in your code, you can define messages as follows:

   <script id="pageScript" type="text/javascript">
     videojs.getPlayer('myPlayerID').ready(function() {
       var myPlayer = this;
       myPlayer.overlay({
       content: '<strong>Default overlay content</strong>',
       overlays: [{
         align: "top",
         content: 'This event-triggered overlay message appears when the video is playing',
         start: 'play',
         end: 'pause'
       }, {
         content: 'This timed overlay message appears between 5 and 10 seconds',
         start: 5,
         end: 10,
         align: 'bottom-right'
       }, {
         start: 12,
         end: 17,
         align: 'bottom-left'
       }]
     });
    });
   </script>

Options

The following plugin options are used to control the overlay object:

• align:
  • The value must be a supported string value.
  • This defines where to show the overlay. If you include the default stylesheet, the following values are supported: top-left, top, top-right, right, bottom-right, bottom, bottom-left, left.
• attachToControlBar:
  • The value can be a string or boolean. If the value is a string, the value must be the name of a ControlBar component.

  • If set to true or a string value, bottom aligned overlays will adjust positioning when the control bar minimizes. This has no effect on overlays that are not aligned to bottom, bottom-left, or bottom-right. The option is for use with the default control bar, and may not work for custom control bars. Bottom aligned overlays will be inserted before the specified component. Otherwise, bottom aligned overlays are inserted before the first child component of the ControlBar. All other overlays are inserted before the ControlBar component.

  • The option can set for all eligible alignments by using it at the top level:

    myPlayer.overlay({
      content: 'Default overlay content',
      attachToControlBar : true,
      overlays: [{
        align: "top",
        content: 'This event-triggered overlay message appears when the video is playing',
        start: 'play',
        end: 'pause'
      }, {
        content: 'This timed overlay message appears between 5 and 10 seconds',
        start: 5,
        end: 10,
        align: 'bottom-right'
      }, {
        start: 12,
        end: 17,
        align: 'bottom-left'
      }]
    });

    Or for individual overlay objects:

    myPlayer.overlay({
      content: 'Default overlay content',
      overlays: [{
        align: "top",
        content: 'This event-triggered overlay message appears when the video is playing',
        start: 'play',
        end: 'pause'
      }, {
        content: 'This timed overlay message appears between 5 and 10 seconds',
        start: 5,
        end: 10,
        align: 'bottom-right'
      }, {
        start: 12,
        end: 17,
        align: 'bottom-left',
        attachToControlBar : true
      }]
    });

    A top level setting can be overridden by option use on individual overlay objects.

  • The visual impact can be seen in these screenshots:

    

    

    

• class:
  • A custom HTML class to add to overlay elements. You define the style as you would any class selector, with the exception that you must use the .video-js selector along with the selector you choose (the specificity must be increased so the style is not overridden):

    .video-js .customOverlay {
      color: yellow;
      background-color: red;
    }

  • The option can set for all eligible alignments by using it at the top level:

    myPlayer.overlay({
      content: 'Default overlay content',
      class: 'customOverlay',
      overlays: [{
        align: "top",
        content: 'This event-triggered overlay message appears when the video is playing',
        start: 'play',
        end: 'pause'
      }, {
        content: 'This timed overlay message appears between 5 and 10 seconds',
        start: 5,
        end: 10,
        align: 'bottom-right'
      }]
    });

    Or for individual overlay objects:

    myPlayer.overlay({
      content: 'Default overlay content',
      overlays: [{
        class: 'customOverlay',
        align: "top",
        content: 'This event-triggered overlay message appears when the video is playing',
        start: 'play',
        end: 'pause'
      }, {
        class: 'customOverlay2',
        content: 'This timed overlay message appears between 5 and 10 seconds',
        start: 5,
        end: 10,
        align: 'bottom-right'
      }]
    });

    A top level setting can be overridden by option use on individual overlay objects.

• content:
  • The value can be a string or DOM object.
  • This is the HTML that will be contained in the overlay. You can pass in a string, an HTML element or a DOM DocumentFragment.
  • The default value is the string This overlay will show up while the video is playing.
  • This option can be set at the top level, or for individual overlay objects.
• end:
  • The value can be a string or number.
  • This defines when to hide an overlay. If the value is a string, it is interpreted as an event name. If it is a number, the overlay will be hidden when that time (in seconds) in the video playback has passed. If the value is a string, it is interpreted as a Brightcove Player event name, like play, pause or ended. A list of all player events is located in the Player API.
• overlays:
  • An array of overlay objects.
  • An overlay object should consist of at least an start and end option. Other options used as desired.
• showBackground:
  • The value is boolean.
  • Determines whether or not to include background styling & padding around the overlay. This setting can be overridden by being set on individual overlay objects.
• start:
  • The value can be a string or number. This defines when to show an overlay.
  • If it is a number, the overlay will be displayed when that time (in seconds) in the video playback has passed.
  • If the value is a string, it is interpreted as a Brightcove Player event name, like play, pause or ended. Here are some helpful links:
    • Player events
    • Player API reference
  • Here's an example that displays overlay text before the video starts playing:

    videojs.getPlayer('myPlayerID').ready(function() {
      var myPlayer = this;
      myPlayer.overlay({
        content: '<strong>Default overlay content</strong>',
        overlays: [{
          align: "top",
          content: 'This event-triggered overlay message appears before the video starts playing',
          start: 'loadstart',
          end: 'play'
        }]
      });
    });

You can use any event dispatched from the player, which are defined in the Player Methods/Events API document, or you can use your own custom events.

All of these properties are optional, but you may get strange results if you don't include at least the start and end properties.

Styling the overlay

Two styles could be helpful for you when working with the overlay. They are detailed here.

Hide the background

The following CSS will hide the background:

.vjs-overlay.vjs-overlay-top.vjs-overlay-background {
  width: 100 % ;
  margin: auto;
  left: 0;
  background: none;
}

Hide the overlay

The following CSS will hide the background:

.hide-overlay.vjs-overlay {
  display: none;
}

Both of these styles are helpful in the Brightcove Player Sample: Toggling an Overlay document.

Changelog

See the changelog here.