Player Configuration Guide

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Create & Configure Players
API(s)
Player Management API

This topic describes how to view and alter the player configuration. The JSON syntax is documented as well.

Introduction

The properties you can set in the player configuration are detailed below (and listed in the left navigation) starting with account_id. Also included in this document is information on how to view and configure property values.

View configuration

An instance of the new Brightcove player's configuration is stored in a JSON file. You can see this JSON file, or parts of it, in several ways.

One way to view the player configuration is by changing the player's URL from ending with index.html to config.json. For example:

http://players.brightcove.net/1507807800001/HJyMlHiuZ_default/config.json

Some of the properties in the player configuration define the following:

  • The name and version of the player
  • The video(s) the player will playback
  • The account to which the player belongs
  • The player's ID
  • Any plugins the player can use, as well as the URLs for the locations of the plugin code
  • A poster to display before video playback

An example player configuration file, for a player from the Quick Start to Player Management, is as follows:

{
    "player": {
      "template": {
        "version": "0.9.5",
        "name": "single-video-template"
      }
    },
    "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"
      }]
    },
    "scripts": [
      "http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"
    ],
    "stylesheets": [
      "http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"
    ],
    "plugins": [{
      "name": "firstPlugin"
    }],
    "account_id": "1507807800001",
    "player_id": "54ade2f3-3b51-4a6b-bc87-32b9a0b81384",
    "embed_id": "default"
}
{
    "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"
      }]
    },
    "compatibility": true,
    "video_cloud": {
      "video": "4093372393001",
      "policy_key": "BCpkADawqM2FnBS3InxzDxU4bd4otJdHKvexlXfhs_XgSj3jmBHAsV2xANIvSPd4KiakMbiQM5oYJPopOcJD7vNnPWGPGsnXCO3_ZGdjPmur53WV_a4JUPWHCLt5oiyekN44i24jZzHMB6hT"
    },
    "player": {
      "template": {
        "name": "single-video-template",
        "version": "6.5.0"
      }
    },
    "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
    "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
    "plugins": [{
      "name": "firstPlugin"
    }]
}

GET with $PLAYER_ID/configuration endpoint

You can retrieve the same information just shown by using the HTTP GET method. Using GET with the /$PLAYER_ID/configuration endpoint you can retrieve the published player's configuration information. An example curl statement, and the JSON retrieved is shown here:

curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request GET \
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
{
    "player": {
      "template": {
        "version": "0.9.5",
        "name": "single-video-template"
      }
    },
    "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"
      }]
    },
    "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
    "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
    "plugins": [{
      "name": "firstPlugin"
    }]
}
{
    "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"
      }]
    },
    "compatibility": true,
    "video_cloud": {
      "video": "4093372393001",
      "policy_key": "BCpkADawqM2FnBS3InxzDxU4bd4otJdHKvexlXfhs_XgSj3jmBHAsV2xANIvSPd4KiakMbiQM5oYJPopOcJD7vNnPWGPGsnXCO3_ZGdjPmur53WV_a4JUPWHCLt5oiyekN44i24jZzHMB6hT"
    },
    "player": {
      "template": {
        "name": "single-video-template",
        "version": "6.5.0"
      }
    },
    "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
    "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
    "plugins": [{
      "name": "firstPlugin"
    }]
}

GET method $PLAYER_ID endpoint

The HTTP GET method used with the /$PLAYER_ID endpoint is the way to retrieve complete player information. This approach gives a superset of player configuration you have just seen. You can think of this endpoint showing you configuration information "one level up" and includes current configuration information for both the preview and published player versions. An example curl statement, and the JSON retrieved is shown here:

curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request GET \
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID
{
    "id": "HJyMlHiuZ",
    "name": "Video Cloud CURL 10 March",
    "branches": {
      "preview": {
        "configuration": {
          "plugins": [{
            "name": "firstPlugin"
          }],
          "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
          "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
          "player": {
            "template": {
              "version": "6.5.0",
              "name": "single-video-template"
            }
          },
          "video_cloud": {
            "policy_key": "BCpkADawqM2FnBS3InxzDxU4bd4otJdHKvexlXfhs_XgSj3jmBHAsV2xANIvSPd4KiakMbiQM5oYJPopOcJD7vNnPWGPGsnXCO3_ZGdjPmur53WV_a4JUPWHCLt5oiyekN44i24jZzHMB6hT",
            "video": "4093372393001"
          },
          "compatibility": true,
          "media": {
            "sources": [{
              "src": "http://solutions.brightcove.com/bcls/assets/videos/Tiger.m3u8",
              "type": "application/x-mpegURL"
            }, {
              "src": "http://solutions.brightcove.com/bcls/assets/videos/Tiger.mp4",
              "type": "video/mp4"
            }],
            "poster": {
              "highres": "http://solutions.brightcove.com/bcls/assets/images/Tiger.jpg"
            }
          }
        },
        "video_cloud": {
          "aspect_ratio_height": "9",
          "aspect_ratio_width": "16",
          "video_id": "4093372393001",
          "poster_image_url": "http://brightcove.vo.llnwd.net/e1/pd/1507807800001/1507807800001_4093546643001_7c09c5bb-7643-414d-81da-847a7e5e3654-AWSAccessKeyId-AKIAJWBBMGHEBQ6SISMA-Expires-1425580379-Signature-h4xCk8Zf9xH-2Be779r9ltwGI7Jzg-3D-vs.jpg?pubId=1507807800001&videoId=4093372393001"
        },
        "updated_at": "2017-08-23T18:09:52.590Z",
        "template_updated_at": "2017-08-23T17:48:55.615Z",
        "preview_url": "http://preview-players.brightcove.net/v1/accounts/1507807800001/players/HJyMlHiuZ/preview/embeds/default/master/index.html"
      },
      "master": {
        "configuration": {
          "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"
            }]
          },
          "compatibility": true,
          "video_cloud": {
            "video": "4093372393001",
            "policy_key": "BCpkADawqM2FnBS3InxzDxU4bd4otJdHKvexlXfhs_XgSj3jmBHAsV2xANIvSPd4KiakMbiQM5oYJPopOcJD7vNnPWGPGsnXCO3_ZGdjPmur53WV_a4JUPWHCLt5oiyekN44i24jZzHMB6hT"
          },
          "player": {
            "template": {
              "name": "single-video-template",
              "version": "6.5.0"
            }
          },
          "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
          "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
          "plugins": [{
            "name": "firstPlugin"
          }]
        },
        "video_cloud": {
          "poster_image_url": "http://brightcove.vo.llnwd.net/e1/pd/1507807800001/1507807800001_4093546643001_7c09c5bb-7643-414d-81da-847a7e5e3654-AWSAccessKeyId-AKIAJWBBMGHEBQ6SISMA-Expires-1425580379-Signature-h4xCk8Zf9xH-2Be779r9ltwGI7Jzg-3D-vs.jpg?pubId=1507807800001&videoId=4093372393001",
          "video_id": "4093372393001",
          "aspect_ratio_width": "16",
          "aspect_ratio_height": "9"
        },
        "updated_at": "2017-08-23T18:10:11.843Z",
        "template_updated_at": "2017-08-23T17:48:55.622Z",
        "preview_url": "http://preview-players.brightcove.net/v1/accounts/1507807800001/players/HJyMlHiuZ/master/embeds/default/master/index.html"
      }
    },
    "created_at": "2017-08-23T17:48:55.615Z",
    "accountId": "1507807800001",
    "embed_count": 1,
    "url": "http://players.brightcove.net/1507807800001/HJyMlHiuZ_default/index.html"
}
{
    "accountId": "1507807800001",
    "branches": {
      "preview": {
        "configuration": {
          "plugins": [{
            "name": "firstPlugin"
          }],
          "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
          "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
          "player": {
            "template": {
              "version": "1.5.0",
              "name": "single-video-template"
            }
          },
          "video_cloud": {
            "policy_key": "BCpkADawqM3ClR-sni6Tc0sFppBHaE91MRyLjE8kUwQjOkXjmK-b2R9fN3IuOnRf_4uuV2LSFwT3eeKUxgYU75eT0c20JEnUKpKU6L-oyjn81zE_P1NF0HJBZiyXyqtHcAdvTpTb29d4S-BH",
            "video": "3495887198001"
          }
        },
        "video_cloud": {
          "aspect_ratio_height": "14",
          "aspect_ratio_width": "25",
          "video_id": "3495887198001",
          "poster_image_url": "http://brightcove.vo.llnwd.net/e1/pd/1507807800001/1507807800001_3495968128001_humbles-scrappy-statue2-vs.jpg?pubId=1507807800001"
        },
        "updated_at": "2014-10-23T14:33:21.107Z",
        "preview_url": "http://preview-players.brightcove.net/v1/accounts/1507807800001/players/a90a8479-9831-46f6-9eab-90efc7fb9c6b/preview/embeds/default/master/index.html"
      },
      "master": {
        "configuration": {
          "video_cloud": {
            "video": "3495887198001",
            "policy_key": "BCpkADawqM3ClR-sni6Tc0sFppBHaE91MRyLjE8kUwQjOkXjmK-b2R9fN3IuOnRf_4uuV2LSFwT3eeKUxgYU75eT0c20JEnUKpKU6L-oyjn81zE_P1NF0HJBZiyXyqtHcAdvTpTb29d4S-BH"
          },
          "player": {
            "template": {
              "name": "single-video-template",
              "version": "1.5.0"
            }
          },
          "scripts": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js"],
          "stylesheets": ["http://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"],
          "plugins": [{
            "name": "firstPlugin"
          }]
        },
        "video_cloud": {
          "poster_image_url": "http://brightcove.vo.llnwd.net/e1/pd/1507807800001/1507807800001_3495968128001_humbles-scrappy-statue2-vs.jpg?pubId=1507807800001",
          "video_id": "3495887198001",
          "aspect_ratio_width": "25",
          "aspect_ratio_height": "14"
        },
        "updated_at": "2014-10-23T14:33:41.201Z",
        "preview_url": "http://preview-players.brightcove.net/v1/accounts/1507807800001/players/a90a8479-9831-46f6-9eab-90efc7fb9c6b/master/embeds/default/master/index.html"
      }
    },
    "id": "a90a8479-9831-46f6-9eab-90efc7fb9c6b",
    "name": "1031+on+Oct+23",
    "created_at": "2014-10-23T14:32:21.384Z",
    "embed_count": 1,
    "url": "http://players.brightcove.net/1507807800001/a90a8479-9831-46f6-9eab-90efc7fb9c6b_default/index.html"
}

Set name/description

To alter the player configuration you use the /$ACCOUNT_ID/players/$PLAYER_ID/configuration endpoint, and that is this document's emphasis. There are, however, two properties you change using just the /$ACCOUNT_ID/players/$PLAYER_ID endpoint. Those two properties are name and description.

The first code block shows an example curl statement that changes a player's name and description. Note the JSON response shows preview versions of the player are generated by the PATCH method, so you will need to publish the player to get the optimized versions.

curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request PATCH \
--data '{
  "name": "My New Player Name",
  "description": "My new player description"
}' \
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
{
    "id": "62da9b4d-b8aa-45d5-ba46-f77eac9c9059",
    "preview_url": "http://preview-players.brightcove.net/v1/accounts/1507807800001/players/62da9b4d-b8aa-45d5-ba46-f77eac9c9059/preview/embeds/default/master/index.html",
    "preview_embed_code": "<iframe src='//preview-players.brightcove.net/v1/accounts/1507807800001/players/62da9b4d-b8aa-45d5-ba46-f77eac9c9059/preview/embeds/default/master/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>"
}

Setting values

You can set the player configuration values using any tool that issues HTTP method calls. You can see curl statements used in the Quick Start to Player Management and AJAX use explained in many of the Brightcove Player examples.

Configuring properties

Some configuration properties are set by the Player Management Service and are not modifiable. Those are:

  • account_id
  • player_id
  • embed_id

All other properties detailed below are modifiable.

Details on the properties follow.

account_id

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

ad_config_id

ad_config_id information:

  • 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.
  • Data type: String
  • Default: undefined

ad_failover

ad_failover information:

  • 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.
  • Data type: Boolean
  • Default: undefined

application_id

application_id information:

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

autoadvance

autoadvance information:

  • Used with playlists and sets the autoadvance behavior of the playlist.
  • Data type: String
  • Default: Not initially enabled

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

autoplay

autoplay information:

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

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

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

Note that autoplay is supported on Apple iOS devices only if muted used concurrently.

base_url (for IP restriction issues)

Problems can occur when using IP restrictions with Brightcove Players used outside North America. When a Brightcove Player is asked to load a video from a Video Cloud account, it connects to the catalog at this addresshttps://edge.api.brightcove.com/playback/v1/.

That Edge endpoint behaves in a way that can cause problems for IP restriction:

  • When hitting Edge from WITHIN North America, it hits Edge directly, and Edge sees the user's IP address. It can either allow or deny access to the catalog as per the IP Restriction whitelist. This is desired functionality.
  • When hitting Edge from OUTSIDE North America, it goes via Cloudfront for load-balancing/local caching CDN reasons. That's important, because as a result of this, Edge sees the Cloudfront IP instead of the user's IP, and denies everyone, because Cloudfront isn't on the whitelist (and never should it be, because then anyone using Cloudfront would have access).

To resolve this issue, you can configure the player to use an alternative Edge endpoint, edge-elb.api.brightcove.com. This change must be made to every player that needs to access the IP restricted account from outside North America.

The actual configuration change involves setting a value for the Video Cloud base_url. Remember, this should ONLY be changed if IP restrictions are used with Brightcove Players outside of North America. For an existing player, you would use the following curl command that uses the PATCH HTTP method (you must substitute your data for the environment variables $EMAIL, $ACCOUNT_ID and $PLAYER_ID):

curl
--header "Content-Type: application/json"
--user $EMAIL
--request PATCH
--data '{
    "video_cloud": {
  "base_url": "https://edge-elb.api.brightcove.com/playback/v1/"
    }
  }'
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

If you are new to curl, the following documents will be of help:

compatibility

compatibility information:

  • Adds a compatibility layer for Brightcove Player 1.x (Video.js v4) that re-introduces a number of properties and methods that were deprecated or removed in Brightcove Player 5.x (Video.js v5).
  • If you have deep functionality or style customizations, this ensures your player works identically before and after the upgrade.
  • You can remove this layer once your customizations have been checked against Video.js v5.
  • Data type: boolean
  • Default value: false
curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request PATCH \
--data '{
  "compatibility": true"
}' \
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

crossorigin

crossorigin information:

  • 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.
  • Data type: Boolean
  • Default: false

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
Player with CSS Overrides
Player with CSS Overrides

debugger

The debugger shows player information in a modal window. See the Player Information Modal document for full information.

dock

dock information:

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

embed_id

embed_id information:

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

errors

errors information:

  • 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.
  • Data type: Object or Boolean
  • Default: true

flash

flash information:

  • Can be used to provide custom Flash options to Video.js.
  • Data type: Object
  • Default: undefined

fullscreenControl

fullscreenControl information:

  • Indicates whether the fullscreen control should be shown in the control bar
  • Data type: boolean
  • Default: true

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

curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request PATCH \
--data '{
  "autoplay": true,
  "fullscreenControl": 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:

Player with Fullscreen Control
Player with Fullscreen Control
Player with No Fullscreen Control
Player with No Fullscreen Control

hls

hls information:

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

Inactive player

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:

Deactivated Player
Deactivated Player

language

language information:

  • Can be provided to set the lang attribute of the <html> element.
  • Data type: String
  • Default: undefined

languages

languages information:

  • 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.
  • Data type: Array of String
  • Default: undefined

media

The media property has child properties as shown in the following table.

Property Data Type Description
src string
  • The URL of the video file to load into the player
sources array of objects
  • An array of source objects, in order of preference
  • The elements of this array are translated directly to source elements
  • A source object should have two properties: src and type
  • The type attribute is the MIME type of the video, as specified in the HTML5 standard
title string
  • Content of the <title> element of the page
poster.highres string
  • The file path to the poster image, relative to the root directory of the skin
height string
  • The height of the video
  • The default value is relative to the width and is appropriate for a video with a 2:1 aspect-ratio
width string
  • The width of the video
  • The default value is relative to the height and is appropriate for a video with a 2:1 aspect-ratio
tracks array
  • An array of track objects
  • The default value is undefined
  • The elements of this array are translated almost directly to track elements. See the Add Captions to Videos document for an example of using tracks with Brightcove Player.

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"
  }]
},

The source that is selected for playback is determined by the video order you've configured and the capabilities of the browser and device on which the player is loaded. If you haven't altered the defaults, and HLS is supported natively, the player will check if any of the sources point to HLS videos and select the first one it finds. If HLS is not supported natively or no HLS video sources have been specified, HTML playback will be attempted next. As previously, the first playable source will be selected. If the first two attempts to play the video fail, Flash fallback will be tried.

To summarize, the play order specifies your preferred playback medium and then each configured option tries all of the available sources and uses the first one it knows how to play.

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

Current Source
Current Source

player

player information:

  • Contains various meta-data about this player, for instance inactive and template.version.
  • Data type: Object
  • Default: Populate with player specific information

play_button

play_button information:

  • The following properties are available for modification via player configuration:
    Property Type Effect
    hover string glow or darken; default is pink / progress color
    shape string square or rectangle; default is a circle
    position string topLeft or topRight; default is center
  • Data type: Object

player_id

player_id information:

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

player_name

player_nae information:

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

Playlists

There are now two different playlist implementations, detailed in the Using Playlists document. The default is version 2. Information for configuring both versions is detailed here.

Both configurations will show how to set the following:

  • autoadvance: Assigned integer number in seconds to delay before loading the next video in the playlist; value of 0 assigned will cause no wait between videos; value of null assigned will cause no auto advance.
  • playOnSelect: Assigned true so when clicking an item from the playlist menu will cause the video to play when loaded, even if the previous video in the player was paused.

Playlist version 2 (Default)

To configure playlists using the version 2 plugin, you use the Plugin Registry. Here is a curl statement to configure the use of the Playlist version 2 plugin:

curl \
  --header "Content-Type: application/json" \
  --user $EMAIL \
  --request POST \
  --data '{
      "name": "Plugin Registry Test Player",
      "configuration": {
        "video_cloud": {
          "video": "4093372393001"
        },
        "plugins": [
          {
            "registry_id": "@brightcove/videojs-bc-playlist-ui",
            "version": "2.x"
          }
        ]
      }
  }' \
  https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players

See the Plugin Registry document for information on its use and benefits.

To set the playOnSelect and autoadvance options when creating the player use the following:

curl \
  --header "Content-Type: application/json" \
  --user $EMAIL \
  --request POST \
  --data '{
      "name": "Plugin Registry Test Player",
      "configuration": {
        "video_cloud": {
          "video": "4093372393001"
        },
        "plugins": [
          {
            "registry_id": "@brightcove/videojs-bc-playlist-ui",
            "version": "2.x",
            "options": {
              "playOnSelect": true
            }
          }
        ],
        "autoadvance": 2
      }
  }' \
  https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players

Playlist Version 1 (Legacy)

In addition to autoadvance and playOnSelect two other properties that are used to configure the use of playlists version 1. They are:

  • playlist: Assigned true to have a player use playlists.
  • adjusted: Assigned true to have the player adjust player dimensions for playlist.

Here is a curl statement to set three of the playlist related properties:

curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request PATCH \
--data '{
  "playlist": true,
  "autoadvance": 2,
  "studio_configuration": {
    "player": {
      "adjusted": true,
      "height": "",
      "width": ""
    }
  }
}' \
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

To set playOnSelect for playlists version 1 use the following curl statement:

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

Programmatically determining if player contains a playlist

If you are using JavaScript in a page that contains a player and wish to check if a playlist plugin is being used you can use the following:

player.hasPlugin('playlist')

If you are checking for the presence of a playlist plugin, and not in a page with a player (for instance when checking a list of players for use with a connector), you have to use a bit more complicated process. You would read the player's configuration, then check to see if the plugins section of the player's JSON contains "name": "bcPlaylistUi". One solution for that task follows:

var theJSON = {},
  pluginAra = [],
  ifFound = [],
  theJSONString =
  '{"account_id":"1507807800001","autoadvance":0,"autoplay":false,"compatibility":true,"embed_id":"default","fullscreenControl":true,"id":"r1fbqySRZ","player":{"inactive":false,"template":{"locked":false,"name":"single-video-template","version":"6.8.3","version_alias":null}},"player_id":"r1fbqySRZ","player_name":"playlist v2 junk","playlist":true,"plugins":[{"injected_version":"2.1.2","name":"bcPlaylistUi","options":{"playOnSelect":true},"registry_id":"@brightcove/videojs-bc-playlist-ui","version":"2.x"}],"preload":"metadata","scripts":["//players.brightcove.net/videojs-bc-playlist-ui/2.1.2/videojs-bc-playlist-ui.min.js"],"studio_configuration":{"player":{"adjusted":true,"height":150,"width":300}},"stylesheets":["//players.brightcove.net/videojs-bc-playlist-ui/2.1.2/videojs-bc-playlist-ui.css"],"updated_at":"2017-10-30T18:06:07.800Z","video_cloud":{"policy_key":"BCpkADawqM2_X3Xxh3xln23EqlR3BETHrfycIPT-a7kqhBi6q8g3XOmTr3tEJiFoi_YmI7vfbJzS4mY0Un5RACc3jC8cLVqyvmfWFLI-tG5oJYGXNUrvOwRJYQEt2eVpMZnBd0FH22i7Mtk3","video":null}}';

theJSON = JSON.parse(theJSONString);
pluginAra = theJSON.plugins;
ifFound = pluginAra.filter(function(pluginAra) {
  return pluginAra.name === "bcPlaylistUi"
});
if (ifFound.length === 1) {
  console.log('Contains playlist plugin');
} else {
  console.log('No playlist');
}

plugins

The plugins property 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, and can also contain an optional options property:

  • name: The name of the video.js plugin, taken from the supporting JavaScript code
  • options: An object hash of settings overrides to provide to the plugin at initialization time

Options child

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. The the Overview: Plugin Registry document for detailed information.

preload

preload information:

  • 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.
  • Data type: String
  • Default: none
  • 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.

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

query_string_to_window

query_string_to_window information:

Used to control the population of the global namespace (window) from query string parameters. This is useful particularly in cases of embedded players, such as Google's AMP components or Facebook Instant Articles. The parsing of query strings is done using the Node.js querystring module. Use of this configuration object requires at least one of the following sub-properties. Both can be used simultaneously.
    • Name: query_string_to_window.target
    • 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']
      }
    • Name: query_string_to_window.globals
    • 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. 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 so you can safely include scripts that depend on one another

skin

skin information:

  • Select the Brightcove Player 1.x skin instead of the Brightcove Player 5.x look.
  • If you enable this option, you will also need to make sure Brightcove Player 1.x compatibility property is also set to true.
  • Only valid value is graphite.
    curl \
    --header "Content-Type: application/json" \
    --user $EMAIL \
    --request PATCH \
    --data '{
      "skin": "graphite",
      "compatibility": true
    }' \
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
  • If you wish to remove the skin entirely and use one of your own design, you can set remove the default skin by using this PATCH statement:
    curl \
    --header "Content-Type: application/json" \
    --user $EMAIL \
    --request PATCH \
    --data '{
      "skin": "graphite",
      "compatibility": true
    }' \
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
    curl \
    --header "Content-Type: application/json" \
    --user $EMAIL \
    --request PATCH \
    --data '{
        "skin": false
      }' \
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

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

techOrder

techOrder information:

  • 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 techOrder option property before moving on to try the next playback technology. See the Guide: Playback Technology document for more information.
  • Data type: Array
  • Default: ['html5','flash']

video_cloud

With this property you can create a player using a video from your Video Cloud library. The curl statement below shows player creation using a Video Cloud video's ID.

curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request POST \
--data '{
    "name": "Video Cloud CURL 10 March",
    "configuration": {
      "video_cloud": {
        "video": "4093372393001"
      }
    }
  }' \
  https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players