Player Configuration Guide

account_id

The Video Cloud account ID associated with the player. This value cannot be modified.

ad_config_id

ad_config_id information:

• Data type: string
• Default: undefined
• A Dynamic Delivery SSAI ad configuration ID. In addition to being set on the player configuration, it can be set at runtime via the adConfigId query string parameter for iframe players or the data-ad-config-id attribute for in-page players. Either of these will override any value in the player configuration.

Other ways to set the value:

ad_failover

ad_failover information:

• Data type: boolean
• Default: undefined
• Set to true to enable ad failover behavior. This is a multi-part configuration that depends on:
  • Both IMA3 and SSAI plugins must be configured on the player.
  • An ad_config_id should be available, otherwise SSAI ads are not available.

When set to true, the player will delay its auto-initialization process until after the ad-block detection has made a decision. This may delay player initialization by up to 100 milliseconds or so.

application_id

application_id information:

• Data type: string
• Default: undefined
• The application ID is used to differentiate multiple uses of a single player in metrics. It is invisible to the user.

Other ways to set the value:

autoadvance

autoadvance information:

• Data type: string
• Default: Not initially enabled
• Used with playlists and sets the auto advance behavior of the playlist.

For more information see the Playlists section below, as well as the Playlist API document.

autoplay

autoplay information:

• Data type: boolean or string
• Default: false
• Indicates that the player should start playing immediately, on platforms where this is allowed.

If autoplay is set to a boolean value the browser's native autoplay behavior is used. If it is set to one of the following three valid string values, the following occurs:

• play: The player will manually try to call play.
• muted: The player will manually mute the player and call play.
• any: The player will first try to call play. If that fails, mute the player and call play.

If any of the above fail, the player will display the "Big Play Button" as if autoplay was set to false.

The following shows a curl statement to set the autoplay value:

Example using boolean values

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

Example using string values

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

Getting a video to autoplay can be a complex situation. See the Autoplay Considerations document for further details.

Other ways to set the value:

block_robots

block_robots information:

• Data type: boolean
• Default: undefined
• Only available in Brightcove Player 6.51.0 and newer.
• If true, adds a <meta> tag to the iframe embed HTML to prevent robots like Google’s crawler from indexing the contents of the iframe embed HTML.

Note that use, shown next, implies true:

<meta name="robots" content="noindex,nofollow">

context_menu

context_menu information:

• Data type: boolean or Object
• Default: true
• If true or an object, the player will include a context menu activated on every other right-click or long touch. This context menu can open a player information modal or a link to the Brightcove corporate website. For further information on use the context menu see the Brightcove Player Information Modal document.

  If an object, the following property is supported:

  Property	Effect
  brightcove_branding	Can be set to false explicitly to remove the About Brightcove link from the custom context menu.

  Example:

  "context_menu": {
    "brightcove_branding": false
  }

crossorigin

crossorigin information:

• Data type: boolean
• Default: false
• If true, the underlying <video> element will have crossorigin="anonymous". This means that any videos or text tracks pulled into the player must have CORS headers.

Other ways to set the value:

CSS color overrides

There are three properties that can be used to override the colors in the player. They are:

• controlColor: The color of the buttons and text (e.g., the playhead position and video duration)
• controlBarColor: The background color of the control bar and the big Play button
• progressColor: The color of the progress bar

Any valid CSS color (including hex colors, for instance) are acceptable values for these properties.

Here is a curl statement to set all three of the CSS properties to green, followed by a screenshot displaying the results:

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

debug

debug information:

• Data type: boolean
• Default: false
• If true, the player will be placed in debug mode. This can be used to turn on logging for various player components, such as the playback engine and analytics.

debugger

This property is deprecated, see context_menu.

dock

dock information:

• Data type: boolean
• Default: true
• If explicitly false, the player will not include the so-called dock where the video title and description can be displayed.

embed_id

embed_id information:

• Data type: string
• Default: undefined
• The Video Cloud embed ID associated with this player. If the value is default it means the player is not a child player. If the value is not default, it is a value representing the parent of the player.

Other ways to set the value:

errors

errors information:

• Data type: Object or boolean
• Default: true
• Explicitly setting false will prevent the player from including videojs-errors, which is the error messages plugin. Making this value false will cause the player to not show detailed error messages to viewers when an error occurs. Errors which prevent playback will still appear in the web developer console.

fullscreen_control (or fullscreenControl)

fullscreen_control information:

• Data type: boolean
• Default: true
• Indicates whether the fullscreen control should be shown in the control bar. If false, double-click-to-fullscreen action will be disabled, too.

The following shows a curl statement to set the fullscreen_control value:

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

The following two screenshots show the player with and without the fullscreen control:

hls

hls information:

• Data type: Object or boolean
• Default: {}
• If false, the player will not include videojs-http-streaming. Otherwise, an object will be passed as options for videojs-http-streaming.

initial_bandwidth

initial_bandwidth information:

• Data type: number
• Default: undefined
• Only available in 6.53.0 and newer
• Sets an initial bits-per-second value which is used to prime the playback engine's rendition selection to favor low or high bandwidth scenarios

language

language information:

• Data type: string
• Default: undefined
• Can be provided to set the lang attribute of the <html> element in an iframe embed and, therefore, the language of the player.

Other ways to set the value:

languages

languages information:

• Data type: Array of string
• Default: undefined
• Can be an array of strings that will cause the specified languages to be included in the player. The only languages that are valid are those included in Video.js. See the Localizing Brightcove Player document for more information.

Other ways to set the value:

loop

loop information:

• If true, causes the video to start over as soon as it ends.

Other ways to set the value:

media

The media property can be an object or array of objects and has child properties as shown in the following table.

Examples

A single source example:

"media": {
  "height": "300px",
  "poster": {
    "highres": "//path/to/poster.jpg"
  },
  "src": "//path/to/some/media-file.mp4",
  "width": "600px"
}

Multiple sources example:

"media": {
  "height": "300px",
  "poster": {
    "highres": "//path/to/poster.jpg"
  },
  "sources": [{
    "src": "//path/to/some/media-file.mp4",
    "type": "video/mp4"
  }, {
    "src": "//path/to/some/media-file.webm",
    "type": "video/webm"
  }],
  "width": "600px"
}

Multiple media objects example:

"media": [{
  "height": "300px",
  "src": "//path/to/some/media-file.mp4",
  "width": "600px"
}, {
  "height": "300px",
  "sources": [{
    "src": "//path/to/some/media-file.mp4",
    "type": "video/mp4"
  }, {
    "src": "//path/to/some/media-file.webm",
    "type": "video/webm"
  }],
  "width": "600px"
}]

For further information on which source will actually play, see the Determining Which Rendition Will Play document.

You can see which source is playing using the currentSrc() function. The following screenshot shows using the function in a browser console.

Media object with tracks example:

"media": {
  "height": "300px",
  "poster": {
    "highres": "//path/to/poster.jpg"
  },
  "sources": [{
    "src": "//path/to/some/media-file.mp4",
    "type": "video/mp4"
  }, {
    "src": "//path/to/some/media-file.webm",
    "type": "video/webm"
  }],
  "tracks": [{
    "src": "//path/to/captions.vtt",
    "srclang": "en",
    "label": "English"
  }],
  "width": "600px"
}

In the following JSON, you can see a media property containing:

• A poster.highres property
• A sources property containing two source objects, one for an HLS video and one for a MP4 video

  "media": {
    "poster": {
      "highres": "http://solutions.brightcove.com/bcls/assets/images/Tiger.jpg"
    },
    "sources": [{
      "type": "application/x-mpegURL",
      "src": "http://solutions.brightcove.com/bcls/assets/videos/Tiger.m3u8"
    }, {
      "type": "video/mp4",
      "src": "http://solutions.brightcove.com/bcls/assets/videos/Tiger.mp4"
    }]
  },

muted

muted information:

• Data type: boolean
• Default: false
• Determines whether sound is muted when the player loads.

Other ways to set the value:

picture_in_picture_control

picture_in_picture_control information:

• Data type: boolean
• Default: true
• Indicates whether the built-in picture-in-picture control should be shown in the control bar.

play_button

play_button information:

• Data type: object
• Default: undefined
• Adds CSS classes for custom player button styles, Brightcove Player versions 5+ only

Object properties:

playback_rates

playback_rates information:

• Data type: Array
• Default: None
• Array of playback rates to show in the playback rate control.

The values are read then presented in a playback rate control in the player's controlbar.

You can use either Studio or curl to change the value of the property:

  curl \
    --header "Content-Type: application/json" \
    --user $EMAIL \
    --request PATCH \
    --data '{
        "playback_rates": [0.1,1,2.5,6]
       }' \
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

player

player information:

• Data type: Object
• Default: Populate with player specific information
• Contains various meta-data about this player, most relevant listed in following table.

Property	Type	Effect
inactive	boolean	When true, the player will be displayed as a gray box with an error message explaining that the content owner has deactivated the player. See the inactive details content below this table for further information.
template.version	string	The template version number from which the player is built. You can manually set the player version using the PLAYERS module JSON Editor.
in_page_embed_url	string	Base URL used for in-page embed

inactive details

It is possible to make players inactive. You might want to do this to have a player stop serving content, but not have a 404 error appear if a deleted player is browsed.

To deactivate a player set the player field's inactive property to true, as follows:

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

Of course, if you wish to activate the player, you can set the inactive property to false.

Once the player is deactivated, if a user browses the player the following message will appear:

player_id

player_id information:

• Data type: string
• The Video Cloud player ID associated with a player

Other ways to set the value:

player_name

player_name information:

• Data type: string
• The Video Cloud player name associated with a player

playsinline

playsinline information:

• Data type: boolean
• Default: false
• Determines if the player should allow inline playback on platforms that require a playsinline attribute for inline/non-native-player playback (e.g. iOS).

Other ways to set the value:

plugins

The plugins array specifies the order to initialize video.js plugins and any customized settings to apply to them. The plugin must be supported by a corresponding scripts property URL entry, and if needed a supporting stylesheets URL. Each element of the plugins array is an object with a name property.

For example, if your plugins property appeared as follows:

"plugins": [{
  "name": "foo",
  "options": {
    "bar": true
  }
}]

At runtime, the foo plugin would be initialized with the supplied options:

player.foo({bar: true});

Any scripts or stylesheets included in a plugin object will be inlined in the same way as top-level scripts or stylesheets; they will be inlined before top-level assets.

options property details

In this options child property, you pass data to utilize at initialization time. The following JSON passes in a single object in the options.

  "plugins": [{
    "name": "navigateOnVideoEnd",
    "options" : {"redirectURL": "http://docs.brightcove.com"}
  }]

This gives you the ability to pass data to a plugin via the player configuration. For instance, to use the redirectURL object shown above, you would do the following in the plugin itself:

  videojs.registerPlugin('navigateOnVideoEnd', function (options) {
    var myPlayer = this;
    myPlayer.on("ended", function () {
      window.location.href = options.redirectURL;
    });
  });

Note: you use the standard plugin implementation, but use options as a parameter in the anonymous function. You can then access the value using options.propertyName notation.

Some Brightcove supplied plugins utilize the plugin registry and configuration is different than what shown here. See the Overview: Plugin Registry document for detailed information.

preload

preload information:

• Data type: string
• Default: none
• The preload attribute informs the browser whether or not the video data should begin downloading as soon as the video tag is loaded. The options are auto, metadata, and none.

Option details

• auto: Indicates that the whole video file could be downloaded, even if the user does not eventually watch the video. On the positive side, if the viewer plays the video, it can start playing immediately. On the negative side, this option will increase bandwidth consumption as the preload/load happens even if the viewer does not play the video.

• metadata (default): Load the meta data of the video, which includes information like the duration and dimensions of the video. This setting will also load several seconds of video data.

• none: Don't preload any of the video data. This will wait until the user clicks play to begin downloading.

Other ways to set the value:

  <video-js preload ...>
  or
  { "preload": "auto" }

query_string_to_window

query_string_to_window information:

1. • Name: query_string_to_window.target
   • Data type: string
   • Description: A destination object to create on the window, which will be populated with the entire parsed query string. For example, a use of query_string_to_window.target given the following in a player configuration:

       {
       "query_string_to_window": {"target": "queryStringParams"}
       }

     and given the following query string:

       ?foo=bar&nums=1&nums=2

     would yield the following window.queryStringParams global object would be available to the player and plugins:

       {
       foo: 'bar',
       nums: ['1', '2']
       }

2. • Name: query_string_to_window.globals
   • Data type: Array
   • Description: An array of property names of the window object, which will be populated from values found in the query string. Any matching properties that already exist on the window object or its prototype chain will not be set. For example, a use of query_string_to_window.globals given the following in a player configuration:

       {
       "query_string_to_window": {
         "globals": [
           "foo",
           "nums",
           "self"
         ]
       }
       }

     and give the following query string:

       ?foo=bar&nums=1&nums=2&self=not-allowed

     would yield the following window global object with the following properties added:

       window.foo; // 'bar'
       window.nums; // ['1', '2']
       
       // Because `self` already exists on the `window` object, it will not be set
       // and a warning will be logged to the browser console.
       window.self; // window

repeat

repeat information:

• Data type is boolean
• Will cause a playlist to repeat playing IF the player is a playlist player. That is, if the playlist property is used.
• Set at the top level of the player configuration.

scripts

scripts information:

• The data type is an array of strings referencing JavaScript files that are included with the player
• No default value
• At the time the player is built, these files will be downloaded and inlined into the resulting output so that they do not need to be subsequently fetched at runtime
• Scripts are inlined in the order they are specified in the scripts array:

  "scripts": [
    "https://example.com/script.js",
    "https://example.com/depends-on-script.js"
  ]

• Since scripts are inlined a specified order, you can safely include scripts that depend on one another

skin

skin information:

• Data type: boolean or string
• Default: undefined
• Determines the visual style variant that the player will use. This value is also reflected in the globally-accessible bc.SKIN property in the browser. It recognizes the following values:

  Value	bc.SKIN	Description
  "graphite"	"graphite"	Uses the old Brightcove Player style as well as some compatibility hacks.
  false	"none"	Disables all Brightcove Player styling. This is the option to use for a highly customized UI from the ground up.
  undefined	"luna"	Leaving this undefined will cause the player to use the default skin (a.k.a. Luna).

stylesheets

stylesheets information:

• An array of URL strings referencing CSS files that should be included with the player
• At the time the player is built, the additional stylesheets are downloaded and inlined into the player so that they do not need to be fetched at runtime
• Stylesheets are included in the order you specify them in the stylesheets array:

  "stylesheets": [
    "https://example.com/layout.css",
    "https://example.com/skin.css"
  ]

suppress_not_supported_error

suppress_not_supported_error information:

• Data type: boolean
• Default: undefined
• If true, an initial error that a source cannot be played is deferred until the first user interaction. Useful for hiding error from browsers that can't play video, e.g. Googlebot.

tech_order (or techOrder)

tech_order information:

• Data type: Array
• Default: ['html5','flash']
• By default Brightcove Player performs tech-first ordering when it searches for a source/tech combination to play videos. This means that if you have two sources and two techs, the player will try to play each video with the first tech in the tech_order option property before moving on to try the next playback technology. See the Guide: Playback Technology document for more information.

You can use the following curl statement to change the tech_order from the default of ['html5','flash'] to ['flash','html5']:

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

umd

umd (Universal Module Definition) information:

• Data type: boolean
• Default: true
• Only available in Brightcove Player 6.53.0 and newer
• When true, adds UMD (Universal Module Definition) boilerplate around the player for use with module systems like RequireJS. If set explicitly to false, the player will not work with module loaders and will simply expose the bc global variable.

volume_orientation

volume_orientation information:

• Data type: string
• Default: horizontal
• Only available in Brightcove Player 6.32.0 and newer
• The volume_orientation property determines if the volume level slider is oriented horizontally or vertically.

  

  

Valid values are:

You can use either Studio or curl to change the value of the property:

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

vttjs

vttjs information:

• Data type: string
• Default: vjs.zencdn.net CDN
• This is the same as the standard Video.js option vtt.js. The Brightcove Player uses vttjs instead as a dotted property name is not possible in the Player Management API and may be problematic elsewhere.
• Can be set as a data-vttjs attribute, a vttjs iframe query parameter, a vttjs setup option or vttjs in the player configuration.

wait_for_ad_block_detect

wait_for_ad_block_detect information:

• Data type: boolean
• Default: undefined
• When set to true, the player will delay its auto-initialization process until after the ad-block detection has made a decision. This may delay player initialization by up to 100 milliseconds or so. This does not need to be set to true when using ad_failover as the delaying behavior occurs in both cases.