Ooyala Player API Reference

Overview

This document covers the various options to customize aspects of the Ooyala Player. The first section details the parameters available in the JavaScript embed code. The second and third sections provide a reference for the JavaScript and ActionScript APIs. Due to security model restrictions, the JavaScript and ActionScript interfaces are mutually exclusive with ActionScript taking precedence in the case of a conflict. The final section documents an alternative embed method for sites that do not accept JavaScript embeds.

Query String Parameter Reference

A set of parameters that can be passed to the Ooyala Player for basic customizations.

Ad Pass-Through Parameter Reference

A set of parameters that can be passed to the Ooyala Player for advanced ad tracking and targeting.

JavaScript API

A JavasScript reference for controlling the player programatically.

ActionScript 3 API

An ActionScript reference for controlling the player programatically.

HTML5 API

An HTML5 reference for controlling the player programatically.

Query String Parameter Reference

• alwaysShowScrubber - Specify true to enable always showing the main control bar and scrubber feature. Default is false and will only show the controls on hover.
• autoplay – If set to 1, play the video upon display.
• browserPlacement – For a channel, specify where external controls are placed, either left or right. Can include a percentage or a width in pixels that will be occupied by the controls as in left40 for left and 40% of the width, or left200px to specify left and 200 pixels. The default left or right value is 50%.
• embedCode – Specify the embed code for a video or channel.
• height – Specify the height, in pixels, of the player.
• hide – Disables specific player functionality. This parameter accepts all to disable all controls or a comma-separated list that can contain any combination of volume, fullscreen, channels, sharing, info, embed or endscreen. If in a chromeless layout, disabling the loadingIndicator is also possible.
• layout – If set to chromeless, removes chrome and start screen. If not specified, the player will revert to its default layout.
• loop – If set to 1, automatically replay the video when it finishes.
• thruParam_<adplatform> - The values of these parameters are tags from your respective ad server or ad network. More details can be found in the Ad Pass-Through Parameter Reference.
• transition – Specify play to show the next movie or specify selector to show the channel browser after each video in a channel. Default is play.
• view – Specify whether the initial state of the player is normal (shows the video) or the channel. Default is normal.
• width – Specify the width, in pixels, of the player.
• wmode – Sets the transparency,layering and positioning in a browser. Possible values are window, opaque, or transparent. Opaque players sit on the lowest level whereas transparent players sit at the top most level. Default is window.

Query String Caveats

If the height is set to less than 200 or the width is set to less than 300, the controls of the player will not be exposed as the panels do not have enough space to expand.

Query String Examples

Standard:

<script src="http://player.ooyala.com/player.js?width=750&height=312&embedCode=dwbjp-XdAc-w6mATLnMIuwBRxHfF5vRK"></script>

Hide the sharing, info and embed buttons with channel browser on the right occupying 300px of the space:

<script src="http://player.ooyala.com/player.js?embedCode=xpaTQ6lmnTkZSM1K6tzrPAWmznGo9fON&browserPlacement=right300px&hide=sharing,info,embed&width=700&height=300"></script>

Autoplay the first video, browser on the left occupying 28% of the space:

<script src="http://player.ooyala.com/player.js?embedCode=xpaTQ6lmnTkZSM1K6tzrPAWmznGo9fON&autoplay=1&browserPlacement=left28&width=700&height=300"></script>

Ad Pass-Through Parameter Reference

The values of these parameters are tags from your ad server or ad network account and can be passed to the Ooyala Player for advanced ad tracking and targeting. Below is the list of the thruParam_ options that we currently support for ad servers and ad networks:

• thruParam_thruParam_adapTv-ads-manager - Adap.tv
• thruParam_adify - Adify
• thruParam_adtech - AdTech
• thruParam_atlas - Atlas
• thruParam_brightroll - Brightroll
• thruParam_brightrollOverlay - Brightroll Overlay
• thruParam_cbsi - CBS Interactive
• thruParam_dartEnterprise - DART Enterprise
• thruParam_dartEnterpriseOverlay - DART Enterprise Overlay
• thruParam_doubleclick - DoubleClick
• thruParam_freewheel - FreeWheel
• thruParam_google - Google AdSense
• thruParam_lightningcast - Lightningcast
• thruParam_liverail - LiveRail (VAST)
• thruParam_liverail-ads-manager - LiveRail
• thruParam_videoad - Ooyala Video Ad
• thruParam_openx - OpenX
• thruParam_as247 - Open AdStream 24/7
• thruParam_tremor-ads-manager - Tremor Media
• thruParam_tv2n - TV2N
• thruParam_vast - VAST
• thruParam_vastOverlay - VAST Overlay
• thruParam_yume - YuMe

The example usage would look like &thruParam_<adplatform>=<value>.

Example embed string using thruParam_yume and a YuMe value:

<script src="http://player.ooyala.com/player.js?width=650&height=250&embedCode=g1Y2ljOr3HMz1rs3DiN47ihopM6XdW&thruParam_yume=ssMediaID%3tdm5iOozjsh21e8VltWXW4dPF1H8A"></script>

JavaScript API

This section of the document provides a class reference to the various get and set commands available through the JavaScript interface and example code along with a link to a live example displaying the capabilities of the API.

To enable the JavaScript API, you need to supply several parameters in the JavaScript embed snippet:

• callback - Name of the JavaScript function that will receive event notification callbacks. This function should be declared with three parameters:

playerId (String) - ID of player invoking the callback

eventName (String) - Name of the notification

parameters (Object) – Extra notification parameters

For example:

<script src="player.ooyala.com/player.js?callback=receiveOoyalaEvent&playerId=player&width=480&height=360&
embedCode=llMDQ6rMWxVWbvdxs2yduVEtSrNCJUk1"></script>

<script>
function receiveOoyalaEvent(playerId, eventName, eventParams) {
  ...
}
</script>

JavaScript Class Reference

  orderBy: "uploadedAt,DESC" or "uploadedAt,ASC"

Event notifications delivered to callback function. Please note that inter-browser compatibility issues prevent use of standard DHTML events.

JavaScript Bitrate Selection API

The Bitrate Selection API allows developers to programmatically obtain current buffer size, as well as get and set bitrates. In order to select a bitrate, we offer two different workflows:

• select a bitrate based on its quality (auto, low, medium, or high). For example, if you set the bitrate quality to high, the player will decide which is the highest available encoding.
• select a bitrate based on its kbps number (sum of both audio and video encodings). For example, consider a video with the following available bitrates: [600 kbps, 1000 kbps, 3000 kbps, 4000 kbps]. You can set the bitrate quality to be any of those values.

Bitrate Selection JavaScript Class Reference

JavaScript Example Code

Available at http://www.ooyala.com/playerScripting-demo.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>JavaScript Example of the Ooyala Player API</title>
</head>

<body>

<script src="http://player.ooyala.com/player.js?callback=receiveOoyalaEvent&playerId=player&width=480&height=360&embedCode=llMDQ6rMWxVWbvdxs2yduVEtSrNCJUk1&version=2"></script>
<script>

function receiveOoyalaEvent(playerId, eventName, eventArgs) {
var ciecc,ttc,ecc,vc;

  switch(eventName) {
    case "playheadTimeChanged":
      onPlayheadTimeChanged(eventArgs);
      break;
    case "stateChanged":
      onStateChanged(eventArgs);
      break;
    case "currentItemEmbedCodeChanged":
      onCurrentItemEmbedCodeChanged(eventArgs);
      ciecc=eventArgs;
      break;
    case "totalTimeChanged":
      onTotalTimeChanged(eventArgs);
      ttc=eventArgs;
      break;
    case "embedCodeChanged":
      onEmbedCodeChanged(eventArgs);
      ecc=eventArgs;
      break;
    case "volumeChanged":
      onVolumeChanged(eventArgs);
      break;
    case "apiReady": 
      //note: apiReady event has no eventArgs (3rd call-back parameter)
      onCurrentItemEmbedCodeChanged(ciecc);
      onTotalTimeChanged(ttc);
      onEmbedCodeChanged(ecc);
      break;
  }
}

function onEmbedCodeChanged(eventArgs) {
  document.getElementById("embedCode").innerHTML =
    eventArgs.embedCode + " == " + document.getElementById("player").getEmbedCode();
  document.getElementById("title").innerHTML = eventArgs.title + " == " + 
    document.getElementById('player').getTitle();
}

function onCurrentItemEmbedCodeChanged(eventArgs) {
  document.getElementById("currentItemEmbedCode").innerHTML = eventArgs.embedCode +" == " + document.getElementById("player").getCurrentItemEmbedCode();
  document.getElementById("currentItemTitle").innerHTML = eventArgs.title +" == " + document.getElementById("player").getCurrentItemTitle();
}

function onTotalTimeChanged(eventArgs) {
  document.getElementById("totalTime").innerHTML =
    eventArgs.totalTime + " == " + document.getElementById("player").getTotalTime();
}

function onPlayheadTimeChanged(eventArgs) {
  document.getElementById("playheadTime").innerHTML =
    eventArgs.playheadTime + " == "+document.getElementById("player").getPlayheadTime();
}

function onVolumeChanged(eventArgs) {
  document.getElementById("volume").innerHTML =
    eventArgs.volume + " == " + document.getElementById("player").getVolume();
}
function onStateChanged(eventArgs) {
  document.getElementById("state").innerHTML =
    eventArgs.state + " == " + document.getElementById("player").getState();
}
</script>

State <span id="state"></span>
<br>
Embed Code <span id="embedCode"></span>
<br>
Title <span id="title"></span>
<br>
CurrentItemEmbedCode <span id="currentItemEmbedCode"></span>
<br>
CurrentItemTitle <span id="currentItemTitle"></span>
<br>
Total Time <span id="totalTime"></span>

<br>
Playhead Time <span id="playheadTime"></span>
<br>
Volume <span id="volume"></span>
<br>
<button onclick="document.getElementById('player').playMovie()">Play</button>
<button onclick="document.getElementById('player').pauseMovie()">Pause</button>
<button onclick="document.getElementById('player').setPlayheadTime(document.getElementById('player').getPlayheadTime() + 30)">
+30s</button>
<br><br>
<button onclick="document.getElementById('player').setQueryStringParameters({embedCode:'8wNTqa-6MkpEB1c7fNGOpoSJytLptmm9',hide:'share,fullscreen'})">Switch Movie</button>

<%= partial :"ganalytics" %>
</body>
</html>

ActionScript 3 API

ActionScript 3 Class Reference

package com.ooyala.api

public class Player extends UIComponent

    orderBy: "uploadedAt,DESC" or "uploadedAt,ASC"
  

ActionScript Bitrate Selection API

The Bitrate Selection API allows developers to programmatically obtain current buffer size, as well as get and set bitrates. In order to select a bitrate, we offer two different workflows:

• select a bitrate based on its quality (auto, low, medium, or high). For example, if you set the bitrate quality to high, the player will decide which is the highest available encoding.
• select a bitrate based on its kbps number (sum of both audio and video encodings). For example, consider a video with the following available bitrates: [600 kbps, 1000 kbps, 3000 kbps, 4000 kbps]. You can set the bitrate quality to be any of those values.

Bitrate Selection ActionScript Class Reference

Flex ActionScript 3 API Interface

package com.ooyala.api
{
  /**
  * Player API
  */
  [Event (name="currentItemEmbedCodeChanged" )]
  [Event (name="embedCodeChanged" )]
  [Event (name="playComplete" , type="flash.events.Event" )]
  [Event (name="loadComplete" )]
  [Event (name="playheadTimeChanged" )]
  [Event (name="stateChanged" )]
  [Event (name="totalTimeChanged" )]
  [Event (name="volumeChanged" )]

  public class Player extends UIComponent
  {

    /**
    * Load the Ooyala player
    */
    public function load():void

    /**
    * Pass "query string parameters" to change the movie or channel in the player.
    * You can pass a string (similar to HTML Snippet query string
    * and FlashVars in direct Flash embed) or properties of an object
    */
    public function set queryStringParameters(parameters:*): void
    /**
    * embedCode of the player itself (in the case of a channel, will be channel)
    */
    [Bindable (event="embedCodeChanged" )]
    public function get embedCode():String
    /**
    * Convenient shortcut for set queryStringParameters('embedCode='+value)
    * i.e. Reloads movie/channel in player
    */
    public function set embedCode(value:String): void
    /**
    * Total time (in seconds) of the currently active item in the player
    * In the case of a channel, total length of the current video in the channel
    */
    [Bindable (event="totalTimeChanged" )]
    public function get totalTime():Number
    /**
    * Playhead time for the current active video in the player
    * In the case of a channel, playhead time of the current video in the channel
    */
    [Bindable (event="playheadTimeChanged" )]
    public function get playheadTime():Number
    /**
    * Seek within the active video in the channel
    */
    public function set playheadTime(value:Number): void
    /**
    * Player Volume setting
    */
    [Bindable (event="volumeChanged")]
    public function get volume():Number
    public function set volume(value:Number): void
    /**
    * The current state of the player. One of:
    * playing
    * paused
    * buffering
    * finished
    * error
    */
   [Bindable (event="stateChanged")]
   public function get state():String
   /**
   * The embedCode of the current video in the player.
   * In the case of a channel, this will be the embedCode
   * of the current video in the channel
   */
   [Bindable (event="currentItemEmbedCodeChanged" )]
   public function get currentItemEmbedCode():String
   /**
   * Play the current video or channel
   */
   public function play():void
   /**
   * Play the current video or channel
   */
   public function pause():void

  }//end of class
}

Flex ActionScript 3 Example – Getting Started

This is the first of two examples that illustrate the ability of the Ooyala player to be embedded in an Adobe Flex application using Adobe ActionScript 3. This example shows a basic integration while the following "Additional Functionality" example shows how to use more of the features exposed in the API. Sample source code, including these two examples, is available here: http://www.ooyala.com/api/ooyala_player_flex_api_demo.zip.

Please note that your player will need to target Flash 10. More information on this can be found at http://opensource.adobe.com/wiki/display/flexsdk/Targeting+Flash+Player+10.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
  applicationComplete="player.load()"
  backgroundColor="#000000"
  layout="vertical"
  xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:ooyala="com.ooyala.api.*"
  >
  <ooyala:Player
    id="player"
    width="100%"
    height="100%"
    embedCode="x0b2E6REM6ksHP8PMsOaWRNkq2uwLyFv"
    loadComplete="player.playMovie()"
  />
</mx:Application>

Flash ActionScript 3 Example Project

In addition to the Flex ActionScript examples, we have an Flash project example available at http://www.ooyala.com/api/ooyala_player_flash_api_demo.zip.

Flex ActionScript 3 Example – Additional Functionality

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
  applicationComplete="player.load()"
  backgroundColor="#000000"
  layout="absolute"
  xmlns:ooyala="com.ooyala.api.*"
  >
  <ooyala:Player id="player" width="100%" height="100%"
    queryStringParameters="{source.selectedItem}"
    />
    <mx:HBox y="0" horizontalCenter="0"
      backgroundColor="black" backgroundAlpha="0.5"
      borderColor="white" borderStyle="solid" borderThickness="1"
      cornerRadius="10"
      paddingLeft="10" paddingTop="10" paddingRight="10" paddingBottom="10"
      >
      <mx:VBox color="white" fontWeight="bold" minWidth="150">
        <mx:Label text="Current Time: {player.playheadTime.toFixed(2)}s"/>
        <mx:Label text="Total Time: {player.totalTime}s"/>
        <mx:Label text="Volume: {(player.volume * 100).toFixed(0)}%"/>
        <mx:Label text="Play State: {player.state}"/>
      </mx:VBox>
      <mx:ComboBox id="source" selectedIndex="0" labelField="comboboxLabel">
        <mx:Array>
          <mx:Object
      comboboxLabel="Sample Video #1"
      embedCode="x0b2E6REM6ksHP8PMsOaWRNkq2uwLyFv"
      hide="sharing,fullscreen,endscreen"
          />
          <mx:Object
            comboboxLabel="Sample Video #2"
            embedCode="sxM2I6UiPuCkPaUuWM6KObYoyA-MOBcn"
            hide="info"
          />
        </mx:Array>
      </mx:ComboBox>
    <mx:Button label="Play" click="player.playMovie()"
      visible="{player.state != 'playing'}"
      includeInLayout="{player.state != 'playing'}"/>
    <mx:Button label="Pause" click="player.pauseMovie()"
      visible="{player.state == 'playing'}"
      includeInLayout="{player.state == 'playing'}"/>
    <mx:Button label="seek -30s" click="player.playheadTime -= 30"/>
    <mx:Button label="seek +30s" click="player.playheadTime += 30"/>
    <mx:Button label="volume 25%" click="player.volume = 0.25"/>
  </mx:HBox>
</mx:Application>

Player Object Embed Code

For situations where JavaScript embeds are not accepted, such as certain blog or social networking sites, we offer this as an example of using object embed code to include the Ooyala player. We recommend using the JavaScript embed wherever possible. The object embed code removes the ability for viewers to be automatically upgraded to the latest Flash version along with a lack of support for the JavaScript API covered earlier in this document.

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="ooyalaPlayer" width="640" height="480"
 codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
<param name="movie" value=" http://player.ooyala.com/player.swf" />
<param name="bgcolor" value="#000000" />
<param name="allowScriptAccess" value="always" />
<param name="allowFullScreen" value="true" />
<param name="flashvars" value="embedCode=9qbTrtNmh_YxuWN7ifQ38ttUkska9UF4" />
<embed src="http://player.ooyala.com/player.swf" bgcolor="#000000" width="640" height="480"
name="ooyalaPlayer"
align="middle" play="true" loop="false"
allowscriptaccess="always" type="application/x-shockwave-flash"
allowfullscreen="true"
flashvars="embedCode=9qbTrtNmh_YxuWN7ifQ38ttUkska9UF4"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>

HTML5 API

This section describes how to customize the playback experience on HTML5 devices, including iOS devices. The HTML5 API provides some of the most commonly used API calls for HTML5 playback: play, pause, seek, and change embedCode. Note that iOS devices only support user-initiated actions. For example, a video can only play when a user clicks a UI element such as a play button; videos cannot play automatically.

To enable the API, you need to supply several parameters in the JavaScript embed snippet:

• callback -- Name of the function that will receive event notification callbacks.
• playerId (String) -- ID of player invoking the callback
• parameters (Object) -- Extra notification parameters

For example:

<script src="http://player.ooyala.com//player.js
?width=608
&callback=playerAPICallback
&embedCode=s0MmVvMTrSlB1ZLzaWXnKZaa42Ib5rJV
&height=342
&playerId=ooplayer">
</script>

HTML5 Class Reference

HTML5 Demo

Available at http://www.ooyala.com/html5-demo.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
    <head>
        <meta http-equiv="Content-type" content="text/html; charset=utf-8">

            <title>Test HTML5 Player for iOS</title>

            <script type="text/javascript" src="http://www.ooyala.com/nuplayer/jquery.js"></script>
            <script type="text/javascript" charset="utf-8">
    var skipStartScreen = false;

    function get_player() {
      return document.getElementById('ooplayer');
    }
    function play() {
      get_player().playMovie();
    }
    function pause() {
      get_player().pauseMovie();
    }
    function setPlayheadTime() {
      get_player().setPlayheadTime($('#playhead_time').val());
    }
    function setEmbedCode() {
      get_player().setEmbedCode($('#embed_code').val());
    }

  </script>

    </head>

    <body>
        <div id="player_controls">
            <input type=button value="Play" onclick="play()"/>
            <input type=button value="Pause" onclick="pause()"/>
            <input type=button value="Set Playhead Time" onclick="setPlayheadTime()"/>
            <input type=text size="5" id="playhead_time"/>
            <input type=button value="Change Embed Code" onclick="setEmbedCode()"/>
            <input type=text size="40" id="embed_code"/>
        </div>


        <div id="player-box">
            <div id="drag-handle"> </div>


            <script src="http://player.ooyala.com//player.js?width=608&embedCode=s0MmVvMTrSlB1ZLzaWXnKZaa42Ib5rJV&height=342&playerId=ooplayer"></script>


            <div id="dimensions"></div>
        </div>
    </body>
</html>