[[PlayerToc(flash)]]


= 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:

[[Image(overview.png)]]


== Flashvars ==

First, all [wiki:FlashVars 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 [wiki:FlashFormats 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 [wiki:FlashVars flashvars overview page].



== Skinning ==

After the flashvars are loaded, the player proceeds to loading a skin, if you [wiki:FlashVars 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 [http://www.longtailvideo.com/addons/skins addons section of longtailvideo].

You can also [wiki:SkinningThePlayer 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 [http://en.wikipedia.org/wiki/Model-view-controller 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 [wiki:FlashFormats can be found here].
 * The '''View''' manages all user interfaces: the controlbar/playlist/display, the [wiki:PluginsBuilding externally loaded plugins] and the [wiki:FlashApi 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 [wiki:FlashVars 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 [http://www.longtailvideo.com/addons/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 [wiki:FlashApi 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 [wiki:FlashEvents LOAD event], loading the video or playlist.
 * The player sends a [wiki:FlashEvents 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 [wiki:FlashVars type flashvar] is set. An example ''type'' is ''rtmp'', for [wiki:FlashFormats#RTMPStreaming RTMP streaming], or ''http'', for [wiki:FlashFormats#HTTPStreaming 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 [wiki:FlashFormats 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 [wiki:FlashVars 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 [wiki:FlashFormats#BitrateSwitching 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 [wiki:FlashFormats#HTTPStreaming 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 [wiki:FlashVars#Layout 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 [wiki:FlashEvents 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: 

[[Image(pluginspace.png)]]

=== 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 [http://labs.adobe.com/wiki/index.php/Flash_Player:9:Update:Full-Screen_Mode_HW 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 [http://www.hulu.com Hulu] and [http://www.vimeo.com 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:

[[JWPlayer(480,260,file=/player/testing/files/bunny.flv&image=/player/testing/files/bunny.jpg&dock=true&plugins=hd,sharing&hd.file=/player/testing/files/bunny.mp4&lightcolor=5588CC&frontcolor=000000&stretching=fill&backcolor=FFFFFF&sharing.link=http://www.bigbuckbunny.org)]]

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 [wiki:FlashVars#Layout color flashvars] for rollovers, if they are set.

----