On This Page

Quick Start: Player Management

This document provides a hands-on introduction to the basic operations of the Player Management API.

Introduction

In this quick start you will perform the following tasks:

Create a player

Update the player to autoplay the video

Customize a player by adding a plugin

Display the configuration for a player

For details on the API used in this document you can view the Player Management API Overview document and the Player Management API reference.The steps in the document involve curl and other command-line tools that are native to Mac and Linux systems, but not part of the Windows operating system. If you are on Windows, you can get these tools by installing cygwin. During the install, you will be prompted for packages to install. Open the Net package, then check the curl option and then finish the installation. Once you have done this, you will be able to follow the Quick Start to Player Management successfully as written using the cygwin command line. Tools are available to run curl at the normal Windows command line, but not detailed in this document.

Get started

The approach this Quick Start takes is to use curl statements to communicate with the Player Service API. The curl tool is used at the command line to transfer data with URL syntax. More information about curl can be obtained from http://curl.haxx.se.

You certainly do not have to use curl as you do in this Quick Start for simplicities' sake. You can, of course, use your favorite language to communicate with the APIs. Check out the Setup for Player Management Samples which demonstrates how to use basic authentication, AJAX and JavaScript to write some mini-apps for basic tasks like creating a player, displaying all your players, deleting players, etc.

A few preliminary steps need to be taken before you can start using the API. These are:

Login to Studio. If you have multiple accounts, use the drop-down to select the one in which you'd like to create your new players. For the credential system to work properly, you need to have admin rights on this account. If you are unsure if a user has admin rights, go to the Users Settings page to see Users listed along with their role.

In Studio, be sure you have selected HOME from the lists of modules. In the top-left corner of the page you, just below the account name, will be able to copy your Account ID.

At the command line, enter the following to assign the Account ID value to an environment variable:

export ACCOUNT_ID=YourAccountID

Authentication will be handled by supplying your account email address as part of the curl statement, and then the API will prompt you for a password. Since the email address will be used frequently, also assign that value to an environment variable:

export EMAIL=YourEmailAddress

If you wish to confirm the environment variables have been assigned correctly, you can display them using the echo command, for instance: echo $ACCOUNT_ID .

You are now ready to start using the API.

Create a player

You can now create a player with a call to the Player Management API. This API call is explained in full detail in the Player Management API Overview document. It is suggested you copy and paste the following curl statements to the command line.

The following steps assist you in creating a player.

Note: If you are not comfortable using curl statements and the command line, many REST-client apps exist. Information on using a REST-client Chrome browser plugin called Postman is detailed in the Using Postman for HTTP Requests document.

The first curl statement creates the player and assigns a name and description. After you paste this statement at the command line and press Enter, you will be prompted for your password.

Video Cloud videos

Of course you can create a player using a video from your Video Cloud library. Instead of using a media section in the JSON data, you use a video_cloud section. The curl statement below shows player creation using a Video Cloud video's ID.

The policy_key is automatically added to the player's configuration. This is created using the Policy API, and it will allow for special restrictions to be placed on your player for accessing different videos. In other words, the policy key controls which videos can be viewed when.

You can also add your own policy key to a configuration instead of having one generated. The normal rules for player and player child config interaction apply here: a policy key that is set at the player child level will override any policy key set at the player level.

Update a player

You have now performed the basics for creating a player. Next, you will learn how to do a simple update of the player. In this case, you will set the player to autoplay the video in the player, if allowed by the browser.

In the returned JSON from player creation an id value was displayed. Copy this into a PLAYER_ID environment variable.

export PLAYER_ID=YourPlayerID

To update the player you will use the HTTP PATCH method. You will send data to update your player. You will set the autoplay option to true. Copy and paste the following curl statement and execute it.

Use one of the player implementations to be sure your published player is functioning correctly.

Customize a player

This section assumes you have associated a video with the player, either through Studio or via the Player Management API. Depending on your approach, the resulting player configurations may vary from what is shown.

You can customize your player using plugins. You can learn how to include pre-existing plugins in your player or build your own in the Quick Start: Plugin Development.

In this case you will use a very simple pre-existing plugin to overlay a text message on the video. Following is the code for a plugin that creates an HTML paragraph tag. Note: a classname and text is assigned to the paragraph, then it is appended to the existing player. This plugin already exists for your convenience and is located at //solutions.brightcove.com/bcls/video-js/new-player/first-plugin.js.

Copy the returned URL and browse it. You will see that the plugin is functioning and the plugin text is displayed.
There may be a slight delay before you see the plugin functioning correctly as it can take a small amount of time for the player to be published. If you don't see the plugin, periodically refresh your page.Plugin Text

When a plugin is added to the player using the Player Management API, be it a Brightcove supplied plugin or a custom plugin you have built, the plugin becomes part of the player code itself.

If you develop your own plugin and change the source code, be sure you re-publish your player as the new plugin code will NOT be part of the JavaScript file unless you do so.

Display configuration

To debug and confirm work you have done it is often helpful to view a player's configuration.

Another way to get a look at the player's configuration is by browsing the URL value returned and change the index.html to config.json.

Delivery system APIs

The Delivery System APIs allow for the management and deployment of a group of files, called a repository. These files are managed through REST APIs and through git. These APIs shouldn't be needed by most people when creating or editing players, but they can be a very interesting set of APIs to use for other purposes. If you'd like to try them out, you can do so here. For a hands-on introduction, try out the Quick Start to the Delivery System.