JW Player: Overview

This page gives a high level overview of the features and structure of the JW Player: its configuration through flashvars, skinning and plugin loading, event structure, file loading and resizing process. Here's a simple schematic of the internal structure of the player:

Flashvars

First, all flashvars are loaded, by the Configger utility class. Flashvars are variables you can set to change the layout and behaviour of the player. You also use flashvars to load media files or plugins into the player. Flashvars are set by adding a flashvars attribute to the HTML code that embeds the player in your site.

You don't have to set all flashvars in your HTML code, since they all have default values. These defaults are listed in the flashvars overview page.

Skinning

After the flashvars are loaded, the player proceeds to loading a skin, if you have set one. A skin is an external SWF file that provides a new look to the player. A number of skins is available as a free download in the addons section of longtailvideo.

You can also create your own skin if you know how to design with Adobe Flash CS4.

Event structure

When the skin is loaded, the player will initialize its internal framework, the MVC triad. It splits up the functionality of the player in three sections:

• The Model manages the playback of the videos. It contains a string of classes that can each playback a specific file (e.g. video) or stream (e.g. rtmp) format. A list of all formats can be found here.
• The View manages all user interfaces: the controlbar/playlist/display, the externally loaded plugins and the javascript API.
• The Controller checks and forwards all directive from the View to the Model and manages the playlist.

Plugins

After the MVC framework is initialized, the plugins are being loaded (if the plugins flashvar is set). Plugins are standalone SWF files that add functionality to the player (e.g. for closed captioning or advertisements). There's a big number of plugins available at longtailvideo. Plugins are hosted at the plugins.longtailvideo.com domain.

Usually, plugins have their own flashvars (e.g. the captions.file flashvar for the captions plugin), to customize them or tell them which files to load. These flashvars (that always begin with the name of the plugin and a dot) were already loaded in step 1 of the player initialization, so plugins can immediately setup themselves.

PlayerReady

When all plugins are loaded the player is completely ready to start playback. At this point the player sends a ping to a playerReady function in javascript. When sent, the player is ready to receive events from and send events to javascript.

The player will also send two events itself:

• If the file flashvar is set, the player will send a LOAD event, loading the video or playlist.
• The player sends a REDRAW event, so all plugins and components are resized to fit the entire area of the SWF.

Both these events are explained in more detail below.

File loading

Because the JW Player handles a wide range of filetypes and formats, the file loading features a small decision list to determine which playback model to use:

1. First, the player checks if a type flashvar is set. An example type is rtmp, for RTMP streaming, or http, for HTTP streaming. If the type is set, the player loads the file and assigns the right playback model.
2. If there is no type flashvar, the player looks at the extension of the file flashvar. If it is a known media format (such as .flv), the player will load the file and assigns the right playback model (video). If the extension is not a known media format (such as .xml), the player will presume the file is a playlist. It tries to load and parse the playlist.
3. When the playlist can indeed be loaded and parsed (the player can parse a string of XML playlist formats, the player repeats step 1 and 2 for every entry in the playlist. If any of these entries have no type set or no known extension, they are dropped.

If the file or playlist has loaded and the autostart flashvar is turned on, the player will also immediately start playback.

There's two common pitfalls that cause a lotof file loading issues:

• Sometimes a mediafile has not a known file extension, e.g. due to security tokens added to the file (song.mp3?token=Kaj893Kdio3d). By setting the type flashvar (type=sound) the file is still being loaded correctly.
• When using a streaming server (e.g. rtmp or http), people sometimes forget the type flashvar, which causes the video that should be played streaming to be played as a progressive download (since the player sees the .flv or .mp4 extension and presumes it is a video).

Bitrate Switching

Player 4.6 introduces a mechanism for bandwidth detection and dynamic stream switching, across all video models. Bitrate switching is enabled by loading multiple levels of one video in the player, using an XML playlist with media:content element. The most suiteable stream is determined based upon two parameters:

• The width of the video window: the best stream whose width is smaller is selected.
• The bandwidth of the connection: the best stream whose bitrate is smaller is selected.

Depending on the streaming type, there is a number of bitrate selection moments. If the width/bandwidth since the last check have changed, the stream switches.

• For the video model, the stream is only selected on startup.
• For the http model, the stream is selected on startup, on a fullscreen switch and on a video seek.
• For the rtmp model in general, the stream is similarly set on startup, fullscreen and seek.
• For the 'rtmp model connecting to an fms3.5 server, the stream is also set every time a big change in available bandwidth is detected.

The current width, bandwidth and bitrate level are all available as flashvars. A couple of notes:

• Switches are not done on a buffer underrun. Switching heuristics that use this as one of the parameters tend to switch bitrates often (especially when on an unstable connection).
• Stream switching for RTMP based upon bandwidth only works if the server implements a checkBandwidth call. This is default in FMS 3.0, and trivial to setup with Wowza. If there's no checkBandwidth handler, streams will be switched solely based upon the available video dimensions.
• Stream switching with http and rtmp always result in a re-buffering (a wait). Stream switching with fms3.5 is completely unobtrusive, but it generallly takes ~10 seconds (2 keyframes) until the switch is actually performed. For example, after clicking the fullscreen button on the player, it takes ~10 seconds until the high-quality stream kicks in.

Resizing

The JW Player resizes itself automatically to the dimensions of the Flash container in HTML. The resizing is managed like this:

• At the beginning of each resize operation, the display (the video screen) gets the entire canvas.
• Next, the player walks through every plugin to see if it has a size and position flashvar set. For example, the default controlbar has a bottom position and a size of 20 pixels. The player reads this and subtracts 20 pixels from the bottom of the display.
• Some plugins (such as the dock) have their position set to over. The player will then simply set the dimensions of this plugin to match those of the display.
• When all plugins have been positioned, the player issues a RESIZE event. It is up to each plugin then to position itself where the player wants it to be.

Here is an intentionally exaggerated example string of flashvars of a player with four plugins that each have a position:

plugins=plugin1,plugin2,plugin3,plugin4&plugin1.position=bottom&plugin1.size=40&plugin2.position=right&plugin2.size=200&plugin3.position=top&plugin3.position=80&plugin4.position=left&plugin4.size=100

The corresponding player layout would then be:

Fullscreen

In fullscreen, the screen-division mechanism is not used. Instead, the display is given all screenspace. Only the plugins that are on top of the display will be visible. There is one exception: the controlbar.position will automatically be set to over when the player jumps to fullscreen.

In fullscreen, the player also uses the hardware-scaling mechanism of the Flash plugin. Simply rendering the player at the full resolution of your monitor will undo a lot of the HW-fullscreen performance gains, so a small decision is being made:

• If the dimensions of the video are smaller than your monitors' resolution / 2, the player is resized to half your monitor resolution.
• If the dimensions of the video are larger than your monitors' resolution / 2, the player is resized to the dimensions of the video.
• If the dimensions of the video are larger than your monitors' overall resolution, the player is resized to your monitor resolution.

The dock

The 4.5 player introduces a new level of flexibility for plugins in the form of our so-called dock. The dock houses and organizes buttons that link to plugin features such as HD switching or closed captions. It not that dissimilar from the dock MAC know from OS X. Other video services such as Hulu and Vimeo offer a similar solution, which makes this docking as an emerging best practice. Here is an example of the dock in action, with HD and sharing features:

Get the Flash Player to see this player.

The dock will automatically fade out when a video plays and fade in again when a user moves his mouse over the player. Note that the dock is shown just by setting the dock=true flashvar. Also note that the dock will use the color flashvars for rollovers, if they are set.

---