From Justin.tv API Wiki

Contents 1 Introduction 2 Javascript Bridge 3 API Object 3.1 Methods 3.1.1 play_live(channel:String, quality:String) 3.1.2 play_playlist(channel:String, ?quality) 3.1.3 get_volume():Float 3.1.4 change_volume(x:Float) 3.1.5 mute():Float 3.1.6 unmute():Float 3.1.7 resume_video() 3.1.8 pause_video() 3.1.9 play_next_playlist() 3.1.10 play_prev_playlist() 3.1.11 addEventListener("video", callback) 3.1.12 set_buffer_time(length) 3.1.13 resize_player(width, height) 3.1.14 get_screencap():flash.display.BitmapData 3.1.15 post_screencap(to_url:String) 3.1.16 set_channel_password(password:String) 3.1.17 get_quality_list() 3.2 Events 3.2.1 buffering 3.2.2 stop_buffering 3.2.3 buffer_full 3.2.4 buffer_empty 3.2.5 stream_lost 3.2.6 video_not_found 3.2.7 playing_playlist_video(title, url) 3.2.8 connected 3.2.9 started 3.2.10 broadcast_finished 3.2.11 total_viewer_count(total) 3.2.12 stream_viewer_count(stream) 4 JtvEvent extends Event 4.1 Properties 4.1.1 event_type:String 4.1.2 info:Object 5 Example Code

Introduction

The easiest way to get a custom player up and running is with the Javascript API. This page documents the lower-level javascript and flash interfaces, which are sligtly more powerful but also a lot more work to integrate.

The Live Video SWF api is designed to make integrating with Justin.tv painless and quick for anyone who wants to build a player to view live video on the web. We host a barebones swf at http://www.justin.tv/widgets/live_api_player.swf. You just use a flash.display.Loader to load the player with your API key, video_height and video_width parameters to specify how large you want the playback window to be, and our player handles the rest. We expose a simple API for playing live video, playlists, and changing the volume. You can see the details below. Warning: standard API keys are limited to 1000 player loads every hour. You should apply for a whitelisted key at https://justintv.wufoo.com/forms/player-load-whitelist-application/ if you want more. If you don't need complete customization, you can use the embed player which works out of the box; documentation is available at channel/embed.

Javascript Bridge

You can also use the Live Video SWF api from Javascript without using any flash at all. Simply pass a flashvar in enable_javascript=true and the API swf will use ExternalInterface to make all of the API calls below available to Javascript (with the same signatures). It will also dispatch events to window.on_video(event, info); you can override the callback path by adding another flashvar like javascript_callback_path=MyObject.handle_on_video. It dispatches the same events listed below as well.

API Object

Methods

play_live(channel:String, quality:String)

Play the live video on a given channel. Get the quality from get_quality_list()

play_playlist(channel:String, ?quality)

Play the playlist on a given channel with an optional quality argument

get_volume():Float

Returns a number between 0 and 100

change_volume(x:Float)

Takes a number between 0 and 100

mute():Float

Mutes the volume

unmute():Float

Unmutes the volume

resume_video()

Resume the currently paused video

pause_video()

Pause the currently playing video

play_next_playlist()

Play the next playlist video in the list (only if playing playlist video)

play_prev_playlist()

Play the previous playlist video in the list (only if playing playlist video)

addEventListener("video", callback)

Dispatches video events, as listed below.

set_buffer_time(length)

Sets the buffer time for the stream in seconds (default 2)

resize_player(width, height)

Resizes the player to a given width and height

get_screencap():flash.display.BitmapData

Grab a screencap from the current live video

post_screencap(to_url:String)

Grab a screencap from the current live video, encode it as a jpeg image, and POST it to a given url

set_channel_password(password:String)

Set the password that the api swf will use for the stream, if the stream has a channel password. Must be called before play_live(channel).

get_quality_list()

Gets the list of available qualities to use as the 2nd argument to play_live

Events

buffering

Every full second that a live video stream has an empty buffer, this event is dispatched.

stop_buffering

If a stream that previously dispatched a buffering event receives data, it dispatches this event

buffer_full

When the stream's buffer becomes full, this event is dispatched. The first time this event is dispatched is when live video starts playing.

buffer_empty

When the stream's buffer becomes empty, this event is dispatched.

stream_lost

When the player gives up on the stream (after waiting 10 seconds for data with no success), this event is dispatched.

video_not_found

If you request to play a channel live and that channel is not live, this event is dispatched.

playing_playlist_video(title, url)

Whenever a playlist video starts playing, this event is dispatched. When a playlist video finishes, the next starts automatically, and this event is dispatched.

connected

Whenever you successfully connect to the server to play live video, this event is dispatched.

started

Whenever you successfully issue a PLAY message to the server to play live video and it is acknowledged, this event is dispatched.

broadcast_finished

When the broadcaster ends their broadcast of a live stream you are watching, this event is dispatched.

total_viewer_count(total)

Periodically the server will issue an update with the total number of viewers currently on Justin.tv. This event contains that value.

stream_viewer_count(stream)

Periodically the server will issue an update with the total number of viewers currently watching your stream. This event contains that value.

JtvEvent extends Event

Properties

event_type:String

The name of the event (eg. started, connected, stream_lost)

info:Object

An object that contains arbitrary key value pairs associated with the event

Example Code

This simple example for an ActionScript 3 project created in Adobe Creative Studio (the Flash studio). It simply loads and plays the apidemo stream in a 640x480 window. Create an fla and paste the code into the "Actions" pane, or simply download our example fla [1].

// You must allow justin.tv; for simplicity of developing against localhost as well I've allowed *
flash.system.Security.allowDomain("*");

// You must use these settings; otherwise our player will go crazy. You should be using these settings anyway because they're better.
stage.scaleMode = flash.display.StageScaleMode.NO_SCALE;
stage.align = flash.display.StageAlign.TOP_LEFT;

// Create the loader!
var loader = new flash.display.Loader();

// Handler for when you've loaded the swf
function loaded(e){
	// Add the loader to the stage
	addChild(loader);
	// Access the API!
	loader.content.api.play_live("apidemo");
}

// When we're done loading, trigger the callback
loader.contentLoaderInfo.addEventListener(flash.events.Event.COMPLETE, loaded);
// Load the player at 640x480 size (video will be automatically letterboxed properly)
loader.load(new flash.net.URLRequest("http://www.justin.tv/widgets/live_api_player.swf?video_height=480&video_width=640&consumer_key=YOUR_API_KEY"));

If you wanted to be able to read parameters passed to the player via the embed HTML code (such as channel name) using the "flash vars" functionality, you could change the loaded() function in the code above to this:

function loaded(e){
	addChild(loader);

	var flashVars=this.loaderInfo.parameters;      // Get all parameters
	loader.content.api.play_live(flashVars.channelName);  // Read the channelname parameter
}

And the HTML embed code would then be similar to:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="640" height="480">
        <param name="movie" value="player.swf" />
        <param name="quality" value="high" />
        <param name="flashvars" value="channelName=officecam" />
        <embed src="player.swf" flashvars="channelName=officecam" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" width="640" height="480"></embed>
      </object>