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.

Note: For more information about REST API commands for the Ooyala player, see the Backlot API Reference.

Note: To change the default player (see is_default), simply specify the new player you want as default. Do not try to "unset" the earlier default.

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

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

Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.

Note: You can get this information at any time by generating a get request against the player ID (e.g., [GET] /v2/players/83fc33534581448eab446935baa6b1f0).

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.

Was this article helpful?

LEAVE FEEDBACK

Rate this article: