Please install the Flash Plugin
or
, etc.) you want to load the JW Player into. If the element is a tag, the attributes of that tag (e.g. the width and src) are loaded into the player. The options are the list of configuration options for the player. The configuration options guide contains the full overview. Here’s an example with a bunch of options: Loading the player ... Though generally a flat list, there are a couple of options that can be inserted as structured blocks inside the setup method. Each of these blocks allow for quick but powerful setups: • playlist: allows inline setup of a full playlist, including metadata. • levels: allows inline setup of multiple quality levels of a video, for bitrate switching purposes. • plugins: allows inline setup of JW Player plugins, including their configuration options. • events: allows inline setup of JavaScripts for player events, e.g. when you want to do something when the player starts. • players: allows inline setup of a custom player fallback, e.g. HTML5 first, fallback to Flash. The sections below explain them in detail. 1.4.3 Skins The JW Player has a wide variety of skins that can be used to modify the look and feel of the player. They can be downloaded from our AddOns Library. To embed a JW Player 5 skin, simply place the ZIP file on your web server and add the skin property to your embed code: Loading the player ... Note: If you’re configuring the Embedder to run primarily in HTML5 mode using the Players block, you’ll need to take the additional step of unzipping the skin ZIP and uploading its contents to your web server in the same location as the ZIP file itself. Your skin’s folder structure would look something like this: /skins/modieus/modieus.zip /skins/modieus/modieus.xml /skins/modieus/controlbar/ /skins/modieus/playlist/ etc. 1.4.4 Playlist Previously, loading a playlist in the JW Player was only available by using an XML playlist format like RSS or ATOM. With the JW Player embed method though, it is possible to load a full playlist into the player using the playlist object block. Here is an example. In it, a playlist of three items is loaded into the player. Each item contains a duration hint, the file location and the location of a poster image. Loading the player... Note: The playlist.position and playlist.size options control the visible playlist inside the Flash player. To date, the HTML5 player doesn’t support a visible playlist yet (though it can manage a playlist of videos). A playlist can contain 1 to many videos. For each entry, the following properties are supported: • file: this one is required (unless you have levels, see below). Without a video to play, the playlist item is skipped. • image: location of the poster image. Is displayed before the video starts, after it finishes, and as part of the graphical playlist. • duration: duration of the video, in seconds. The player uses this to display the duration in the controlbar, and in the graphical playlist. • start: starting point inside the video. When a user plays this entry, the video won’t start at the beginning, but at the offset you present here. • title: title of the video, is displayed in the graphical playlist. 6 Chapter 1. Embedding the player JW Player for Flash and HTML5, Release 5.3 • description: description of the video, is displayed in the graphical playlist. • streamer: streaming application to use for the video. This is only used for RTMP or HTTP streaming. • provider: specific media playback API (e.g. http, rtmp or youtube) to use for playback of this playlist entry. • levels: a nested object block, with multiple quality levels of the video. See the levels section for more info. 1.4.5 Levels The levels object block allows you to load multiple quality levels of a video into the player. The multiple levels are used by the Flash player (HTML5 not yet) for RTMP or HTTP bitrate switching. Bitrate switching is a mechanism where the player automatically shows the best possible video quality to each viewer. Here’s an example setup, using RTMP bitrate switching (also called dynamic streaming). Note the additional streamer option, which tells the player the location of the RTMP server: Loading the player... Here is another example setup, this time using HTTP bitrate switching. The HTTP switching is enabled by setting the provider option to http: Loading the player... 1.4. JW Embedder 7 JW Player for Flash and HTML5, Release 5.3 1.4.6 Plugins Plugins can be used to stack functionality on top of the JW Player. A wide array of plugins is available in our library, for example for viral sharing, analytics or advertisements. Here is an example setup using both the HD plugin and the Google Analytics Pro plugin: Loading the player... Here is another example, using the sharing plugin. In this example, plugin parameters are also included in the playlist block: Loading the player... 1.4.7 Events The events block allows you to respond on player events in JavaScript. It’s a short, powerful way to add player - pager interactivity. Here is a swift example: Loading the player ... Here is another example, with two event handlers. Note the onReady() handler autostarts the player using the this statement and the onVolume() handler is processing an event property: Loading the player ... See the API reference for a full overview of all events and their properties. 1.4.8 Players The players option block can be used to customize the order in which the JW Player uses the different browser technologies for rendering the player. By default, the JW Player uses this order: 1. The Flash plugin. 2. The HTML5 tag. Using the players block, it is possible to specify that the Embedder try the HTML5 player first: Loading the player ... 1.4.9 Player Removal In addition to setting up a player, the JW Player embed script contains a function to unload a player. It’s very simple: 1.4. JW Embedder 9 JW Player for Flash and HTML5, Release 5.3 jwplayer("container").remove(); This formal remove() function will make sure the player stops its streams, the DOM is re-set to its original state and all event listeners are cleaned up. 10 Chapter 1. Embedding the player CHAPTER TWO PLAYER API The 5.3 player introduces a new, shorthand javascript API for interacting with your website. This API abstracts any differences between Flash and HTML5; any code you write will work with both technologies. For versions 5.2 and below, the player used the 4.x JavaScript API. A reference for that API can be found on the player support site. 2.1 Getting started First, you’ll need to upload the API library (jwplayer.js) to your web server. We recommend putting it, along with player.swf, in a folder called jwplayer in the root of your site. Once it’s on your web server, add this bit of code to your HTML pages, in the of your page: To get a sense of the possibilities of what you can do with the API, here’s a quick example that showcases how to control the player from the page: Loading the player ... Start the player Get current position Of course it’s also possible to have the player manipulate the page. Here’s a second example, using the event block of the JW Player embedder: Loading the player ... 11 JW Player for Flash and HTML5, Release 5.3 The following sections give a detailed description of the JW Player API, describing how to: • Select a player. • Get variables from a player. • Call functions on a player. • Listen to events from a player. 2.1.1 Embedding with SWFObject If you embed the player using SWFObject, rather than the built-in setup() function, you can still use the JavaScript API, although you’ll need to wait for Flash to be loaded on the page before interacting with the API. SWFObject 2.2 includes a callback function (in this example, named flashLoaded) which is executed when SWFObject has finished embedding Flash into the page. Make sure you wait until this function is called before making any calls to the API. Here’s a simple example of using the SWFObject callback: var flashvars = { file:"/videos/video.mp4" }; var params = { allowfullscreen:"true", allowscriptaccess:"always" }; var attributes = { id:"player", name:"player" }; swfobject.embedSWF("/jwplayer/player.swf", "container", 320, 240, "9.0.115", "false", flashvars, params, attributes, flashLoaded); function flashLoaded(e) { // e.ref is a reference to the Flash object. We’ll pass it to jwplayer() so the API knows wh // Add event listeners jwplayer(e.ref).onReady(function() { alert("Player is ready"); }); jwplayer(e.ref).onPlay(function() { alert("Player is playing"); }); // Interact with the player jwplayer(e.ref).play(); } 12 Chapter 2. Player API JW Player for Flash and HTML5, Release 5.3 2.1.2 Embedding with an or tag If you embed the player directly using an or tag, simply pass your tag’s id to the API when referencing the player: 2.2 Selecting The first thing you need to do when attempting to interact with a JW Player, is to get a reference to it. The easiest way, probably sufficient for 95% of all use cases is this: // Start the player on this page jwplayer().play(); Only when you have multiple players on a page, you need to be more specific on which player you want to interact with. In that case, there are three ways to select a player: • With the id of the element you instantiated the player over: jwplayer("container").play(); • With the actual DOM element itself: var element = document.getElementById("container"); jwplayer(element).play(); • With the index in the list of players on the page (in order of loading): jwplayer(2).play(); Note: The selector jwplayer(0) is actually the same as jwplayer(). 2.3 Variables Here is a list of all the variables that can be retrieved from the player: 2.2. Selecting 13 JW Player for Flash and HTML5, Release 5.3 getBuffer() Returns the current PlaylistItem’s filled buffer, as a percentage (0 to 100) of the total video’s length. getFullscreen() Returns the player’s current fullscreen state, as a boolean (true when fullscreen). getMetadata() Returns the current PlaylistItem’s metadata, as a javascript object. This object contains arbitrary key:value parameters, depending upon the type of player, media file and streaming provider that is used. Common metadata keys are width, duration or videoframerate. getMute() Returns the player’s current audio muting state, as a boolean (true when there’s no sound). getPlaylist() Returns the player’s entire playlist, as an array of PlaylistItem objects. Here’s an example playlist, with three items: [ { duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" }, { title: "cool video", file: "/uploads/bbb.mp4" }, { duration: 542, file: "/uploads/ed.mp4", start: 129 } ] getPlaylistItem(*index*): Returns the playlist item at the specified index. If the index is not specified, the currently playing playlistItem is returned. The item that is returned is an object with key:value properties (e.g. file, duration and title). Example: { duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" } getWidth() Returns the player’s current width, in pixels. getHeight() Returns the player’s current height, in pixels. getState() Returns the player’s current playback state. It can have the following values: •BUFFERING: user pressed play, but sufficient data has to be loaded first (no movement). •PLAYING: the video is playing (movement). •PAUSED: user paused the video (no movement). •IDLE: either the user stopped the video or the video has ended (no movement). getPosition() Returns the current playback position in seconds, as a number. getDuration() Returns the currently playing PlaylistItem’s duration in seconds, as a number. getVolume() Returns the current playback volume percentage, as a number (0 to 100). 2.4 Functions Here is a list of all functions that can be called on the player: 14 Chapter 2. Player API JW Player for Flash and HTML5, Release 5.3 setFullscreen(state) Change the player’s fullscreen mode. Parameters: •state:Boolean (true): Set the player’s fullscreen mode to fullscreen if true, and return to normal screen mode if false. setMute(state) Change the player’s mute state (no sound). Parameters: •state:Boolean (true): Mute the player if true, and unmute if false. load(playlist) Loads a new playlist into the player. The playlist parameter is required and can take a number of forms: •Array: If an array of PlaylistItem objects is passed, load an entire playlist into the player. Example: [ { duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" }, { title: "cool video", file: "/uploads/bbb.mp4" }, { duration: 542, file: "/uploads/ed.mp4", start: 129 } ] •Object: If a PlaylistItem is passed, load it as a single item into the player. Example: { duration: 32, file: "/uploads/video.mp4", image: "/uploads/video.jpg" }, •String: Can be an XML playlist, or the link to a single media item (e.g. an MP4 video). playlistItem(index) Jumps to the playlist item at the specified index. Parameters: •index:Number: zero-based index into the playlist array (i.e. playlistItem(0) jumps to the first item in the playlist). playlistNext() Jumps to the next playlist item. If the current playlist item is the last one, the player jumps to the first. playlistPrev() Jumps to the previous playlist item. If the current playlist item is the first one, the player jumps to the last. resize(width, height) Resizes the player to the specified dimensions. Parameters: •width:Number: the new overall width of the player. •height:Number: the new overall height of the player. Note: If a controlbar or playlist is displayed next to the video, the actual video is of course smaller than the overall player. play(state) Toggles playback of the player. Parameters: •state:Boolean (undefined): if set true the player will start playing. If set false the player will pause. If not set, the player will toggle playback. pause(state) Toggles playback of the player. Parameters: •state:Boolean (undefined): if set true the player will pause playback. If set false the player will play. If not set, the player will toggle playback. 2.4. Functions 15 JW Player for Flash and HTML5, Release 5.3 stop() Stops the player and unloads the currently playing media file from memory. seek(position) Jump to the specified position within the currently playing item. Parameters: •position:Number: Requested position in seconds. setVolume(volume) Sets the player’s audio volume. Parameters: •volume:Number: The new volume percentage; 0 and 100. 2.5 Events Here is a list of all events the player supports. In javascript, you can listen to events by assigning a function to it. Your function should take one argument (the event that is fired). Here is a code example, with some javascript that listens to changes in the volume: jwplayer("container").onVolume( function(event) { alert("the new volume is: "+event.volume); } ); Note that our official embed method contains a shortcut for assigning event listeners, directly in the embed code: Loading the player ... And here’s the full event list: onBufferChange(callback) Fired when the currently playing item loads additional data into its buffer. Event attributes: •percent: Number: Percentage (between 0 and 100); number of seconds buffered / duration in seconds. onBufferFull(callback) Fired when the player’s buffer has exceeded the player’s bufferlength property (default: 1 second). No attributes. onError(callback) Fired when an error has occurred in the player. Event attributes: •message: String: The reason for the error. 16 Chapter 2. Player API JW Player for Flash and HTML5, Release 5.3 onFullscreen(callback) Fired when the player’s fullscreen mode changes. Event attributes: •fullscreen: boolean. New fullscreen state. onMetadata(callback) Fired when new metadata has been discovered in the player. Event attributes: data: Object: dictionary object containing the new metadata. onMute(callback) Fired when the player has gone into or out of the mute state. Event attributes: •mute: Boolean: New mute state. onPlaylist(callback) Fired when a new playlist has been loaded into the player. Event attributes: •playlist: Array: The new playlist; an array of PlaylistItem objects. onPlaylistItem(callback) Fired when the player is playing a new media item. Event attributes: •index Number: Zero-based index into the playlist array (e.g. 0 is the first item). onReady(callback) Fired when the player has initialized and is ready for playback. No attributes. onResize(callback) Fired when the player’s dimensions have changed (the player is resizing or switching fullscreen). Event at- tributes: •width: Number: The new width of the player. •height: Number: The new height of the player. onPlay(callback) Fired when the player enters the PLAYING state. Event attributes: •oldstate: String: the state the player moved from. Can be PAUSED or BUFFERING. onPause(callback) Fired when the player enters the PAUSED state. Event attributes: •oldstate: String: the state the player moved from. Can be PLAYING or BUFFERING. onBuffer(callback) Fired when the player enters the BUFFERING state. Event attributes: •oldstate: String: the state the player moved from. Can be PLAYING, PAUSED or IDLE. onIdle(callback) Fired when the player enters the IDLE state. Event attributes: •oldstate: String: the state the player moved from. Can be PLAYING, PAUSED or BUFFERING. onComplete(callback) Fired when the player has finished playing the current media. No event attributes. onTime(callback) When the player is playing, fired as the playback position gets updated. This happens with a resolution of 0.1 second, so there’s a lot of events! Event attributes: •duration: Number: Duration of the current item in seconds. •offset: Number: When playing streaming media, this value contains the last unbuffered seek offset. 2.5. Events 17 JW Player for Flash and HTML5, Release 5.3 •position: Number: Playback position in seconds. onVolume(callback) Fired when the player’s volume changes. Event attributes: •volume: Number: The new volume percentage (0 to 100). 2.6 Chaining Note that every API call to a JW Player in turn returns the player instance. This makes it possible to chain API calls (like with jQuery): jwplayer().setVolume(50).onComplete(function(){ alert("done!"); }).play(); 18 Chapter 2. Player API