InStream API

[zach]

We'd like to add the ability for plugins (both Flash and JavaScript) to easily play back a piece of content without unloading the currently playing content. The most common use case would be to seamlessly play video ads for which the video location is available before / during / after a piece of video content, as with VAST implementations.

Any implementation should cover the following requirements:

• Should be able to play video through API call.
• Should be able to leverage Video and RTMP media providers.
• Should not interrupt timing / state for main video.
• Should not fire events as though it was the main video.
• Should fire events only to creator.
• Should work in both Flash and HTML5.
• Next/previous buttons removed from controlbar (since playlist now has only one item)

Proposed API: loadInstream

Flash plugin workflow

1. Plugin locks the player
2. Plugin calls player.loadInstream(item:PlaylistItem, options:IInstreamOptions):IInstreamPlayer
3. InStream player spawns new MediaProvider and places media element above existing media
4. InStream player creates copy of controlbar and display
5. InStream video plays
6. InStream video completes and sends a complete event through the IInstreamPlayer object. Plugin may call player.loadInstream() again to play an additional video.
7. If no additional ad is played, player removes the InStream player and reverts player to original state
8. Plugin unlocks player; original media resumes playback

JavaScript plugin workflow

The JavaScript plugin workflow should work the same way as with Flash; the loadInstream call should return a proxy object which exposes the API methods and events. The player would implicitly lock itself, since no locking mechanism is available in JavaScript

API Specification

player.loadInstream(item:PlaylistItem, options:IInstreamOptions):IInstreamPlayer

• loadInstream(playlistItem, configOptions):: Returns an InstreamPlayer object, which will allow plugins to access additional APIs to control instream playback and listen for events. Configuration options will include:
  • controlbarseekable (String): Allows the plugin to modify the controlbar's seek bar behavior during instream playback
    • "always" (default): Controlbar seek bar works as usual; can seek ahead and behind
    • "never": Controlbar seek bar is disabled
    • "backwards": User can seek backwards
  • controlbarpausable (Boolean): Enables (default) or disables the controlbar play/pause button
  • controlbarstoppable (Boolean): Enables (default) or disables the controlbar stop button
  • playlistclickable (Boolean): Enables (default) or disables the ability to click on playlist items during instream playback
  • autoload (Boolean): If true, the player begins loading the instream content, but doesn't display it until InstreamPlayer.play() is called. (Flash only)

IInstreamPlayer Methods

The InstreamPlayer object will expose the following methods:

• play(): Plays the instream video (i.e. if pause() was called or if the autoLoad option was passed into the call to loadInstream)
• pause(): Pauses the instream video
• seek(position): Seeks to a specific position
• getState(): Returns the current state of the instream video ("BUFFERING", "PLAYING", "PAUSED" or "IDLE")
• getPosition(): Returns the current playback position of the instream video
• getDuration(): Returns the duration of the instream video
• destroy(): stops the instream video and returns the player to its original (pre-instream) state

IInstreamPlayer Events

The InstreamPlayer will forward the following events:

JavaScript Event	Flash Event
onPlay	PlayerStateEvent.JWPLAYER_PLAYER_STATE
onPause	PlayerStateEvent.JWPLAYER_PLAYER_STATE
onBuffer	PlayerStateEvent.JWPLAYER_PLAYER_STATE
onIdle	PlayerStateEvent.JWPLAYER_PLAYER_STATE
onComplete	MediaEvent.JWPLAYER_MEDIA_COMPLETE
onTime	MediaEvent.JWPLAYER_MEDIA_TIME
onSeek	com.longtailvideo.jwplayer.events.MediaEvent.JWPLAYER_MEDIA_SEEK
onMeta	com.longtailvideo.jwplayer.events.MediaEvent.JWPLAYER_MEDIA_META
onMute	com.longtailvideo.jwplayer.events.MediaEvent.JWPLAYER_MEDIA_MUTE
onVolume	com.longtailvideo.jwplayer.events.MediaEvent.JWPLAYER_MEDIA_VOLUME
onFullscreen	ViewEvent.JWPLAYER_VIEW_FULLSCREEN
onError	PlayerEvent.JWPLAYER_ERROR
onInstreamClick	InstreamEvent.JWPLAYER_INSTREAM_CLICKED
onInstreamDestroyed	InstreamEvent.JWPLAYER_INSTREAM_DESTROYED

HTML5 Considerations

Some assumptions made for Flash mode may not be true in HMTL5 mode, due to restrictions in some HTML5 implementations (read: iOS). This will require some investigation, but some requirements (such as the one which states that the buffer for the currently playing media should be retained) may need to be relaxed.

[jeroen]

Amended this to #1067.

[jeroen]

Whoops, wrong ticket. 634 instead of 644

[pablo]

Additional API for ad use case:

  //This would optionally disable seeking (entirely, or forward)
__setControlbarSeekable__("both", "backwards", "none")
  //Enable/disable pause button
__setControlbarPauseable__(true/false)

[pablo]

Something to keep track of in the documentation:

A limitation in Flash which prevents the duplication of MovieClip objects will mean that SWF skins will not work properly in the InStream API. Instead, the API will use the default player skin for its controlbar and display components.

[pablo]

Another technical note to keep track of:

We'll be using a small optimization where we'll wait to display the video until the dimensions are present (if stretching is not "exactfit"). If width and height metadata are not available in the video, it won't ever be displayed unless stretching is "exactfit".

[pablo]

Implemented in [2049] and [2050]