Managing Players Using the Backlot REST API
When you create a player and assign it to one or more assets in your account, it defines the playback options and the look and feel of your content.
Create a Player
[POST]/v2/players{ properties }
List Players
[GET]/v2/players
View Player Information
[GET]/v2/players/player_id
Delete a Player
[DELETE]/v2/players/player_id
Route Attributes
The following table describes all attributes that can be expressed through the route.
Route Attribute | Description |
---|---|
player_id | The ID of the player. To get a list of players, perform a get against the /players route. Type: String Default: None Example: /players/b4f1a93b779145b4a9c8ef15f8502345 |
Properties
The following table describes all properties that can be associated with a player. For an introduction to player visual components from an end user perspective, see Player V3 Components (Deprecated).
Property | Description | Required? |
---|---|---|
accent_color | Specifies the accent color in the web color format. Type: String Default: ffbb00 Example: "66FF33" Parent: ooyala_branding |
No |
alpha | Specifies the transparency of the watermark. Type: String Default: None Example: 1.0 Valid Values: 0.0 to 1.0 Parent: watermark |
No |
always_show | Shows the scrubber bar during video playback. Type: Boolean Valid Values: true | false Default: false Example: "false" Parent: scrubber |
No |
buffer_on_pause | Causes the video to buffer when paused. This is useful for users with slow network connections. Type: Boolean Valid Values: true | false Default: false Example: "false" Parent: playback |
No |
click_behavior | Specifies how the related video opens when its thumbnail is clicked. Type: String Valid Values: same_player | same_page | new_page Default: same_player Conditions: Required if related_videos is specified. Example: "same_player" Parent: related_videos |
Conditional |
click_url | The URL to which the user is directed when the watermark is clicked. Type: String Default: None Example: "www.mywebsite.com" Parent: watermark |
No |
default_closed_caption_language | Specifies the default language for closed captions. Type: String Default: None Example: "true" |
No |
digg_sharing | Enables Digg sharing. If enabled, show_share_button must be set to true. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
email_sharing | Enables users to share the video through email. If enabled, show_share_button must be set to true. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
enable_error_screen | Displays the Ooyala error screen if there is a playback error. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
facebook_sharing | Enables Facebook sharing. If enabled, show_share_button must be set to true. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
image_url | Read only. The URL to the placeholder thumbnail that is shown while scrubbing through a video. To upload a new image, see [Scrubber](/v2/docs/players_scrubber). Type: String Default: None Example: "http://ak.c.ooyala.com/ZnMmM6AO3C-iBubra3R2Xd6pXHgK/shelf123467931" Parent: scrubber |
No |
image_url | Read only. The watermark shown during a video. We accept .PNG, .JPG, .GIF and .SWF watermarks, and we recommend using .PNG files with transparent backgrounds. To upload a new image, see [Watermark](/v2/docs/players_watermark). Type: String Default: None Example: "http://ak.c.ooyala.com/ZnMmM6AO3C-iBubra3R2Xd6pXHgK/watermark123467943" Parent: watermark |
No |
is_default | Sets this player as the default player template to use when creating new players. Type: Boolean Valid Values: true | false Default: false Example: "true" |
No |
labels | Specifies a label to use for shared videos. Type: Array of strings Default: None Conditions: Required if source is specified. Example: ["videos_of_kittens","video_of_dogs"] Parent: related_videos |
Conditional |
name | Name of the player. Type: String Example: "My Player with Watermark" |
Yes |
ooyala_branding | Specifies branding options. Type: Container |
No |
order | Specifies whether related videos are sorted in ascending or descending order. Type: String Valid Values: "asc" | "desc" Default: "desc" Example: "desc" Parent: related_videos |
No |
playback | Specifies playback options. Type: Container |
No |
position | Specifies the display position of the watermark. Type: String Default: bottom-right Example: bottom-left Valid Values: bottom | bottom-left | bottom-right | left | right | top | top-left | top-right Parent: watermark |
No |
provider_homepage_url | The URL to your website home page. Type: String Default: None Conditions: Required if show_info_screen_homepage_link is set to true. Example: "http://myhomepage.com" |
Conditional |
related_videos | Specifies related video settings. Type: Container |
No |
scrubber | Specifies scrubber options. Type: Container |
No |
show_ad_countdown | Displays a countdown timer during the advertisement that lets the user when the video will start. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
show_bitrate_button | Displays a button that allows users to choose from available bitrates. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
show_channel_button | Displays the Channel button which users can click to view other content on the channel. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
show_embed_button | Displays an embed button which contains a code snippet for the video that users can embed on their websites. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
show_end_screen_replay_button | When the video completes, enables the user to click a button to replay the video. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
show_info_button | Enables the Info button which the user can use to view information about the video. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
show_info_screen_description | Displays the description of the video when the user clicks the Info button. If enabled, show_info_button must be set to true. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
show_info_screen_homepage_link | Displays a link to the video provider. If enabled, show_info_screen_homepage_link and show_info_screen_homepage_name must be specified. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
Conditional |
show_info_screen_title | Displays the title of the video when the user clicks the Info button. If enabled, show_info_button must be set to true. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
show_share_button | Enables the share button, which enables users to share the content with social networks. If you enable this button without enabling other sharing options (e.g., twitter_sharing), the button will appear with no options. Type: Boolean Valid Values: true | false Default: true Conditions: Required if one or more sharing options are specified. Example: "true" Parent: ooyala_branding |
Conditional |
show_volume_button | Displays the volume button. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
sort | Specifies how related videos are sorted. Type: String Valid Values: "upload_time" Default: "upload_time" Example: "upload_time" Parent: related_videos |
No |
source | Specifies which types of videos are displayed as related videos. Type: String Valid Values: shared_labels | specified_label Default: None Conditions: Required if related_videos is specified. Example: "same_player" Parent: related_videos |
Conditional |
stumbleupon_sharing | Enables StumbleUpon sharing. If enabled, show_share_button must be set to true. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
twitter_sharing | Enables Twitter sharing. If enabled, show_share_button must be set to true. Type: Boolean Valid Values: true | false Default: false Example: "true" Parent: ooyala_branding |
No |
url_sharing | Displays a Copy URL button. If enabled, show_share_button must be set to true. Type: Boolean Valid Values: true | false Default: true Example: "true" Parent: ooyala_branding |
No |
watermark | Specifies watermark options. Type: Container |
No |
Examples
Example: Create a Basic Player with Default Settings
This example creates a basic player that uses all default settings:
[POST] /v2/players{ "name": "Basic Player" }
Backlot returns a response similar to the following:
{ "ooyala_branding":{ "show_share_button":true, "twitter_sharing":false, "show_info_screen_homepage_link":true, "show_ad_countdown":true, "show_info_screen_title":true, "facebook_sharing":false, "show_info_button":true, "url_sharing":false, "email_sharing":true, "digg_sharing":false, "show_embed_button":true, "show_info_screen_description":false, "show_bitrate_button":false, "show_channel_button":true, "enable_error_screen":true, "show_end_screen_replay_button":true, "accent_color":"#ffbb00", "show_volume_button":true }, "name":"Basic Player", "provider_homepage_url":null, "related_videos":{ "click_behavior":"new_page", "order":"desc", "sort":"upload_time", "labels":[ ], "source":"shared_labels" }, "is_default":false, "scrubber":{ "image_url":null, "always_show":false }, "playback":{ "buffer_on_pause":false }, "id":"83fc33534581448eab446935baa6b1f0", "default_closed_caption_language":"", "watermark":{ "image_url":null, "click_url":null, "alpha":1.0, "position":"bottom-right" } }
Example: Change Accent Color and Enable Twitter and Facebook
This example changes the accent color to pink and turns on Twitter and Facebook sharing:
[PATCH]/v2/players/83fc33534581448eab446935baa6b1f0{ "ooyala_branding":{ "twitter_sharing":true, "facebook_sharing":true, "accent_color":"#FF1493" } }
Backlot returns a response similar to the following:
{ "ooyala_branding":{ "show_share_button":true, "twitter_sharing":true, "show_info_screen_homepage_link":true, "show_ad_countdown":true, "show_info_screen_title":true, "facebook_sharing":true, "show_info_button":true, "url_sharing":false, "email_sharing":true, "digg_sharing":false, "show_embed_button":true, "show_info_screen_description":false, "show_bitrate_button":false, "show_channel_button":true, "enable_error_screen":true, "show_end_screen_replay_button":true, "accent_color":"#FF1493", "show_volume_button":true }, "name":"Basic Player", "provider_homepage_url":null, "related_videos":{ "click_behavior":"new_page", "order":"desc", "sort":"upload_time", "labels":[ ], "source":"shared_labels" }, "is_default":false, "scrubber":{ "image_url":null, "always_show":false }, "playback":{ "buffer_on_pause":false }, "id":"83fc33534581448eab446935baa6b1f0", "default_closed_caption_language":"", "watermark":{ "image_url":null, "click_url":null, "alpha":1.0, "position":"bottom-right" } }
Example: List All Players
This example lists all players:
[GET]/v2/players
Backlot returns a list of players and their configuration settings.
Example: Delete a Player
This example deletes a player:
[DELETE]/v2/players/83fc33534581448eab446935baa6b1f0
Backlot returns a 200 response.