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"
}
}
Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. To launch the scratchpad, go to Ooyala API Scratchpad.
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.
Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. To launch the scratchpad, go to Ooyala API Scratchpad.
Example: Delete a Player
This example deletes a player:
[DELETE]/v2/players/83fc33534581448eab446935baa6b1f0
Backlot returns a 200 response.
Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. To launch the scratchpad, go to Ooyala API Scratchpad.