[[PlayerToc(flash)]]

= JW Player: Events Overview =

Internally, the player is split up into three central components; the [browser:trunk/as3/com/jeroenwijering/player/Controller.as Controller], the [browser:trunk/as3/com/jeroenwijering/player/Model.as Model] and the [browser:trunk/as3/com/jeroenwijering/player/View.as View]. The Controller takes care of user and API input, the Model manages the actual playback and the View manages all interfaces. Here's [wiki:FlashOverview some more info].

Each of the three has a set of events it can fire, thereby controlling each other. By listening to these events through the [wiki:FlashApi API], external scripts and plugins instantly get state updates of the player. The [wiki:FlashApi API] also offers the ability to trigger events of the View (for example sending a ''PLAY'' event, after which the player starts playback). 

Note that some events are sent by both the View and the Controller (e.g. ''SEEK''). The View then sends the raw event to the Controller, who checks its values (e.g. if the position isn't < 0). The corrected value is immediately thereafter broadcasted by the Controller  (a new ''SEEK'' event).

== Controller events ==

Here's an overview of all events the Controller sends. Regardless of the event, the Controller always includes these three parameters:

 * '''id''' (''String''): ID of the player in the HTML DOM. Used by javascript to [wiki:FlashApi#Initialization reference the player].
 * '''client''' (''String''): A string representing the client the player runs in (e.g. ''FLASH WIN 9,0,115,0''). 
 * '''version''' (''String''): A string representing the major version, minor version and revision number of the player (e.g. ''4.2.95'').

 ControllerEvent.ITEM::
 Fired when the player switches to a new playlistitem. The new item will immediately start playing. The currently playing item is always available through the [wiki:FlashVars#Behaviour item] flashvar. Parameters:
 * '''index''' (''Number''): index of the new view in the playlist.
 
 ControllerEvent.MUTE::
 Fired when the sound is muted or unmuted. The current mute state is always available through the [wiki:FlashVars#Behaviour mute] flashvar. Parameters: 
 * '''state''' (''Boolean''): the new mute state. If ''true'' the player will mute.
 
 ControllerEvent.PLAY::
 Fired when the player toggles playback (playing/paused). Parameters:
 * '''state''' (''Boolean''): the new playback state. If ''true'' the player plays. If ''false'' the player pauses.

 ControllerEvent.PLAYLIST::
 Fired when a new playlist has been loaded into the player. The current playlist is always available through the [wiki:FlashApi#Readingvariables API]. Parameters:
 * '''playlist''' (''Array''): A reference to the new playlist. 

 ControllerEvent.RESIZE::
 Fired when the player is resized or enters/leaves fullscreen mode (which is effectively also a resize). The current fullscreen state, width and height are always available through the [wiki:FlashVars#Behaviour fullscreen], [wiki:FlashVars#Layout height] and [wiki:FlashVars#Layout width] flashvars. Here's [wiki:FlashOverview#Resizing more info on resizing]. Parameters:
 * '''fullscreen''' (''Boolean''): The new fullscreen state. If ''true'' the player is in fullscreen.  
 * '''height''' (''Number''): When [wiki:FlashVars#Behaviour resizing] is turned off (default), this is the height of the ''Display''. When [wiki:FlashVars#Behaviour resizing] is turned on, this is the overall height of the player. 
 * '''width''' (''Number''): When [wiki:FlashVars#Behaviour resizing] is turned off (default), this is the width of the ''Display''. When [wiki:FlashVars#Behaviour resizing] is turned on, this is the overall width of the player.

 ControllerEvent.SEEK::
 Fired when the player is seeking to a new position in the video/sound/image. Parameters: 
 * '''position''' (''Number''): the new position in the file, in seconds. Two and a half minutes correspond to a position of ''150''.

 ControllerEvent.STOP::
 Fired when the player stops loading and playing. The playback state will turn to ''IDLE'' and the ''position'' of a video will be set to 0. No parameters.

 ControllerEvent.VOLUME::
 Fired when the volume level is changed. The current volume is always available through the [wiki:FlashVars#Behaviour volume flashvar]. Parameters:
 * '''percentage''' (''Number''): new volume percentage. Can be 0 to 100.


== Model events ==

Here's an overview of all events the Model sends. Regardless of the event, the Model always includes these three parameters:

 * '''id''' (''String''): ID of the player in the HTML DOM. Used by javascript to [wiki:FlashApi#Initialization reference the player].
 * '''client''' (''String''): A string representing the client the player runs in (e.g. ''FLASH WIN 9,0,115,0'').
 * '''version''' (''String''): A string representing the major version, minor version and revision number of the player (e.g. ''4.2.95'').

 ModelEvent.BUFFER::
 Fired when the playback buffer changes. The buffer indicates how long the player still has to load before starting playback. When the buffer is emptying during playback, stuttering may occur. The [wiki:FlashVars#Behaviour bufferlength flashvar] allows you to set the size of the buffer (is 1 second by default). Parameters:
 * '''percentage''' (''Number''): percentage in which the buffer is filled. Can be 0 to 100.
 
  ModelEvent.ERROR::
 Fired when a playback error occurs. The player then automatically stops. Parameters:
 * '''message''' (''String''): the error message, e.g. ''file not found'' or ''no suiteable playback codec found''.

 ModelEvent.LOADED::
 Fired when the player is busy loading the currently playing video/image/sound. Parameters: 
 * '''loaded''' (''Number''): the number of bytes of the file that are currently loaded.
 * '''total''' (''Number''): the total size of the file in bytes.
 * '''offset''' (''Number''): when [http://www.longtailvideo.com/support/tutorials/HTTP-Video-Streaming HTTP streaming] is used, this is the offset in bytes where the video last started playing. 

 ModelEvent.META::
 Fired when metadata is retrieved by the model. This can be a wide range of data, e.g. video data like ''width'', ''height'' or ''bitrate'', embedded captions and images, RTMP status messages, cuepoints, id3 tags or RTMP ''bandwidth'' values. All metadata items are sent as separate parameters with this call.

 ModelEvent.STATE::
 Fired when the playback state of the video changes. Use this to check when a video has started (newstate=BUFFERING), is paused (newstate=PAUSED) or finished (newstate=COMPLETED). The current state is always available through the [wiki:FlashVars#Behaviour state flashvar]. Parameters:
 * '''oldstate''' (''IDLE'', ''BUFFERING'', ''PLAYING'', ''PAUSED'', ''COMPLETED''): the previous playback state. 
 * '''newstate''' (''IDLE'', ''BUFFERING'', ''PLAYING'', ''PAUSED'', ''COMPLETED''): the new playback state. 

 ModelEvent.TIME::
 Fired when the playback position is changing (i.e. the videosound/image is playing). It is fired with a resolution of 1/10 second, so there'll be a lot of events. This is needed for tight timing with e.g. closed captioning. Parameters:
 * '''duration''' (''Number''): total duration of the file in seconds. Two and a half minutes correspond to a duration of ''150''.
 * '''position''' (''Number''): current playback position in the file, in seconds. Two and a half minutes correspond to a position of ''150''.


== View events ==

Here's an overview of all events the View sends. Regardless of the event, the View always includes these three parameters:

 * '''id''' (''String''): ID of the player in the HTML DOM. Used by javascript to [wiki:FlashApi#Initialization reference the player].
 * '''client''' (''String''): A string representing the client the player runs in (e.g. ''FLASH WIN 9,0,115,0''). 
 * '''version''' (''String''): A string representing the major version, minor version and revision number of the player (e.g. ''4.2.95'').

 ViewEvent.FULLSCREEN::
 Fired when the user wants to enter/leave fullscreen. This only works in actionscript, and only as a direct result of a mouseclick. The current fullscreen state is always available through the [wiki:FlashVars#Behaviour fullscreen] flashvar.Parameters:
 * '''state''' (''Boolean'') {''optional''}: the new fullscreen state. 

 ViewEvent.ITEM::
 Fired when the user wants to play a specific playlistitem. The currently playing item is always available through the [wiki:FlashVars#Behaviour item] flashvar.Parameters:
 * '''index''' (''Number''): the new item to play.


 ViewEvent.LINK::
 Fired when the user requests to navigate to a  [wiki:FlashVars#Fileproperties link]. Parameters:
 * '''index''' (''Boolean'') {''optional''}: When set, this is the playlistitem whose [wiki:FlashVars#Fileproperties link] the player navigates to. When not set, the link of the current item is used.

 ViewEvent.LOAD::
 Fired when the user wants to load a new file or playlist. Parameters: 
 * '''object''' (''String''): this can be the url of either a single video/song or a playlist. The Controller will auto-detect this and start the [wiki:FlashOverview#Fileloading file loading].

 ViewEvent.MUTE::
 Fired when the user wants to mute/unmute the player. The current mute state is always available through the [wiki:FlashVars#Behaviour mute] flashvar.Parameters: 
 * '''state''' (''Boolean'') {''optional''} : The new mute state. If omitted, the Controller will perform a toggle.

 ViewEvent.NEXT::
 Fired when the user wants to play the next playlistitem. No parameters. 

 ViewEvent.PLAY::
 Fired when the user wants to pause or resume the player. Parameters: 
 * '''state''' (''Boolean'') {''optional''} : The new playback state. If omitted, the Controller will perform a toggle.

 ViewEvent.PREV::
 Fired when the user wants to play the previous playlistitem. No parameters.

 ViewEvent.REDRAW::
 Fired when the user wants to issue a redraw of the canvas (e.g. after a resize or after showing/hiding the playlist). No parameters.

 ViewEvent.SEEK::
 Fired when the user wants to seek in the current image/video/sound. Parameters:
 * '''position''' (''Number''): the new position in the file, in seconds. Two and a half minutes correspond to a position of ''150''.

 ViewEvent.STOP::
 Fired when the user wants to stop loading and playing. No parameters.

 ViewEvent.VOLUME::
 Fired when the user wants to change the playback volume. The current volume is always available through the [wiki:FlashVars#Behaviour volume flashvar]. Parameters:
 * '''percentage''' (''Number''): new volume percentage. Can be 0 to 100.