Brightcove Player Plugins

In this topic you will learn about Brightcove supplied plugins for the Brightcove Player which are used to enhance the player is some way.

Additional resources

The following documents provide greater insight into creating and using plugins:

Introduction

A plugin for the Brightcove Player uses a combination of HTML, JavaScript and/or CSS to somehow customize the player. In other words, anything you can do in a web page, you can do in a plugin.

Broadly, plugins can be developed to:

  • Modify default behavior
  • Add functionality
  • Customize appearance (that cannot be done in standard CSS)

Brightcove plugins

The Overview: Player Plugins document lists the plugins supplied by Brightcove and which plugins are loaded by default.

Brightcove supplied plugins can be used in a number of ways. Although all can be implemented using the Plugins section in Studio's PLAYERS module, some have a dedicated section to load the functionality, like advertising, endscreens and social. You can also get some extra help for some plugins in the Plugins section as shown in these screenshots:

add plugin in Studio
brightcove supplied plugin

Adding plugins in Studio

If you choose not to, or there is no way to add a plugin another way, use the following form. As shown, first select Custom Plugin, the the form will appear to complete.

add plugin in Studio
add plugin in Studio

You see you add the plugin name, an Internet accessible link to the JavaScript file, to the CSS file (if needed) and options.

Default plugins

There are three plugins loaded by default. (In reality, this makes them no longer plugins but simply player features.) They are:

  • DRM: Enables delivery of DRM protected content to the widest possible variety of browsers and devices.
  • Errors - Allows the player to display user friendly messages when it encounters an error. The display is an overlay that is semi-transparent and styled by the default style sheet.
  • HLS - Plays HLS video on platforms that don't support HLS but do have Flash Player. The enables the video content in the m3u8 manifest to be played in the player.

If you do not wish to have a certain plugin loaded, you can prevent that by setting the particular default plugin(s) to false when creating/updating a player or child player. Note that the hls, debugger and errors fields are nested under the configuration property, and not in any other grouping property, when using a POST to create a new player:

curl \
  --header "Content-Type: application/json" \
  --user $EMAIL \
  --request POST \
  --data '{
      "name": "MySamplePlayer",
      "configuration": {
        "media": {
          "sources": [{
            "src":"http://solutions.brightcove.com/bcls/assets/videos/Tiger.mp4",
            "type":"video/mp4"
          }]
        },
        "hls": false,
        "errors": false
      }
    }' \
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players

If you wish to turn off the hls, debugger and/or errors plugin(s) with an existing player, you must use a PATCH as follows:

curl \
  --header "Content-Type: application/json" \
  --user $EMAIL \
  --request PATCH \
  --data '{
      "hls": true,
      "errors": true
    }' \
  https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

How to detect if a default plugin is loaded?

You can determine if a default plugin is loaded by going to a browser's Console when using the URL or embed_in_page implementations of a player and seeing if the corresponding plugin object is present. The following screenshot shows presence of the plugin.

default-plugin-with-hls

If you have set a particular default plugin NOT to be loaded, it's object will not be present in the page. In the following screenshot you see that the HLS plugin object is NOT present:

default-plugin-no-hls

Pass data

You can also use an additional options child property with plugins. This allows you to pass data to the plugin for use at initialization time. It also makes plugins more flexible as reuse of plugins is greatly enhanced when you can can pass different implementation data for different uses of a single plugin.

For a complete discussion of the option property see the Pass Data to the Plugin document.

Plugin and postMessage()

In an iframe player implementation you may wish to send data into the iframe from the parent page. This is possible using JavaScript's postMessage() method. Briefly, in the parent page you use postMessage() to send a message into the iframe, which uses an event listener to get the message and act upon it.

See the Play Video from iframe Parent document for a complete explanation and working example.

Role of stylesheets

It is not uncommon to have both a plugin and associated stylesheet for that plugin. For example, in the simple plugin used in the Step-by-Step: Player Management, the plugin itself uses JavaScript to place text on the player, whereas the associated stylesheet controls color, font-size and positioning. This can be abstracted into the following best practice:

  • A plugin should have an associated stylesheet to perform tasks stylesheets do best. Only do styling in the plugin if it cannot be done in a stylesheet, for example, dynamic selection of stylesheets.

Compatibility

The open source videojs player, on which the Brightcove Player is based, has many plugins built for it. These plugins are compatible with the Brightcove Player only as long as the version of the videojs player is the same version on which the Brightcove Player is based. The Brightcove Player may be version-wise either ahead of, or behind, the open source videojs player.