JavaScript API

From DevWiki

Revision as of 16:53, 23 February 2011 by Spectrer (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Back to Home

Contents


JS Reference Docs


Examples

The scripts listed below do not necessarily work for, nor are they intended for any particular site. They are simply examples to assist in the learning process. We will add more here as needed.


Overview

Our JavaScript API allows you to control the playback of web media in Boxee (flash, silverlight, movenetworks, native html 5.0 video and more). We are constantly building and improving this API. Everything on here is subject to change. However we will make sure everything remains backwards compatible.

Boxee plays media in a very unique way. The Boxee player itself is not a flash player. SWFs are not wrapped in a special Boxee player. Generally speaking Boxee, when it comes to Flash playback (or any other type of web content: text, video, audio), Boxee is a web browser, literally. When you ask Boxee to play a video from the web, say from YouTube, we load the YouTube URL the video is located on. Not the SWF. Boxee uses the Mozilla/Gecko engine to open the specified website, the same way a user would do using the Firefox browser.

With the player now rendering this website on screen, we overlay our OSD (on screen display), or and show the website as part of the Boxee look and feel. Note that you can also suppress the display of our OSD. Boxee then uses a JavaScript engine to "orchestrate" the site's playback and decide which components to show and when (e.g. locating the actual player and making it show full screen).

This is where the JavaScript API comes into play. Using this API developers can not only simulate 'user clicks' any place (x,y) on the website, but you can also interact with the entire page itself. An browser.execute() function allows you to execute any JavaScript code on the page as you please. You can tie in the Boxee OSD functions (pause, play, seek, volume) with the JavaScript API. This allows you to send commands, in JavaScript, to the browser. When users press pause, you might want to send 'document.playerid.pause()' to the browser and so on.

In addition, you can send all sorts of events to the browser, such as keyUp, mouseWheelUp, mouseMove, keyLeft, keyRight and much much more.


Control Scripts

Control scripts are called on by the Boxee player and used to manage playback functionality. These scripts can be defined in different ways and can be located in different places. When a the player loads a url, it will look for scripts in the following places/order:

bx-jsactions

1. specified in flash:// protocol media link
If using the flash potocol (flash://) for media links, the bx-jsactions parameter can be used to specify the URL for the control script to be loaded. Notice the bx-jsactions param in the example below.
See the Boxee RSS Specifications for more details on how to construct a proper link using the flash protocol.
flash://joost.com/src=http%3A%2F%2Fjoost.com%2Fembed%2F13600&bx-jsactions=http%3A%2F%2Fmyserver%2Fcontrol.js

local

2. used for debugging only
Does not load if bx-jsactions is specified.
See Testing and Debugging below.
/opt/boxee/system/players/flashplayer/joost.js

boxee server

3. Default location scripts created by boxee devs
Does not load if bx-jsactions is specified or loaded locally.
The Boxee server uses a number of methods to find a proper control script, including the domain from the url provided. These are scripts are written and managed by Boxee developers.

metadata tag

4. if available, will always be loaded
A control script url can be specified by web developers in the <head> tag of any page.
If exists, this script will load regardless of any others that may have already been loaded. Can be used to override predefined scripts.
<meta name="boxee-control" content="http://mysite.com/boxee/mysite.js" />

object src

4. loaded if no script was found before
If no control scripts have been located up to this point, Boxee will load the url and attempt to automatically locate the proper object on the page. (flash, silverlight, etc..)
If an object is found (<object> or <embed> tags), boxee will then look for the src or data attribute in that object.
Once found, the player will again check first locally, then on the boxee servers for the proper script.
<embed src="http://cdn.episodic.com/player/EpisodicPlayer.swf?pid=294" />


Testing & Debugging

You can write and test scripts locally, making the process much easier. Boxee will look in your local install folder for a domain.js to use before looking on our servers or another source. For this to work you must place your scripts under the flashplayer folder in your install directory (listed below). You can then use boxee.log(str) or alert(str) to debug your code. Make sure you enable logging with boxee.enableLog(true); before trying to debug your code.

Important Note: Viewing the js output in terminal is not available in Windows. To get the output we suggest using DebugView. You can download it here.


Windows

Use DebugView to monitor javascript output.

C:\Program Files\Boxee\system\players\flashplayer\
Linux

Lauch boxee from a terminal to monitor javascript output

/opt/boxee/system/players/flashplayer/
OSX

Open Console.app and select DATABASE SEARCHES > Console Messages to view javascript output.

/Applications/Boxee.app/Contents/Resources/Boxee/system/players/flashplayer/
Personal tools