HD Plugin for JW Player Release 2.1
www.longtailvideo.com March 26, 2011
Contents 1
Introduction
i
2
Configuration Options 2.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ii ii
3
Streaming Support 3.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ii iii
4
Youtube Support 4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iii iii
5
Playlist Support 5.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv iv
6
Skinning 6.1 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
v v
7
Changelog 7.1 Version 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 Version 2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
v v v
1 Introduction The HD plugin for the JW Player gives your viewers a way to toggle between a high definition and standard definition version of your videos. It works with progressive downloads, HTTP pseudostreaming, RTMP streaming and YouTube video. The plugin stores the viewer’s quality preference in a cookie, so they use a consistent video quality throughout playback. It supports playlists, as well as skinning (several skins support the plugin, offering a nicely integrated look).
2 Configuration Options The HD plugin supports the following configuration options: hd.file ( undefined ) Location of the high definition file to play, e.g. http://example.com/hd-video.mp4. hd.state ( false ) The default video quality to use for playback. When set true the player will start out with the HD version. Whenever a users toggles the HD quality, his setting is stored in a cookie. The cookie overrides the default state (false), the configuration option in turn overrides the cookie. hd.fullscreen ( false ) When set true, the player will automatically switch to the HD video file when a user enters fullscreen. The plugin does not enforce the HD quality in fullscreen, nor will it toggle down when exiting fullscreen. Note: When using progressively downloaded video files, playback will restart from the beginning when entering fullscreen.
2.1 Example Here is a basic example of the plugin, setting just an hd.file: <div id=’player’>Get Flash to see the video</div> <script type="text/javascript> jwplayer(’player’).setup({ file: ’/assets/standard.mp4’, flashplayer: ’/assets/player.swf’, plugins: { hd: { file: ’/assets/highdef.mp4’ } } }); </script>
Note: The examples in this guide use the - preferred - JW Embed method. Please see our Embedding Flash guide for other options like SWFObject.
3 Streaming Support We recommend using the HD plugin if you are serving progressively downloaded videos or an HTTP/RTMP server without dynamic streaming capabilities. If you are using an RTMP that can do dynamic streaming (like FMS 3.5+ or Wowza 2.0+), we recommend using the player’s built-in bitrate switching functionalities. This delivers the best experience for your viewers. There are some discrepancies between the various streaming protocols: • For progressive downloads, toggling video quality will cause the video to restart playback from the beginning. This is because it is not possible to seek to an arbitrary point with progressive downloads. • When the HD plugin is used in conjunction with a (non-dynamic) HTTP or RTMP streaming server, the video will resume playback at the current position.
• When using dynamic streaming through the JW Player’s bitrate switching, the HD plugin should not be used. The features are not compatible. In short, bitrate switching provides an amazing user experience because it automatically adjusts the video quality to the bandwidth and screen estate of the viewer. However, automatic bitrate switching is only available for dynamic RTMP and HTTP streaming servers. The HD plugin is the next best thing.
3.1 Example Here is an example using HTTP pseudostreaming. In addition to the regular hd.file option, the hd.fullscreen option is set to automate a toggle to HD when the user enters fullscreen mode: <div id=’player’>Get Flash to see the video</div> <script type="text/javascript> jwplayer(’player’).setup({ file: ’http://example.com/videos/low.mp4’, flashplayer: ’/assets/player.swf’, ’http.startparam’: ’starttime’, plugins: { hd: { file: ’http://example.com/videos/high.mp4’, fullscreen: true } }, provider: ’http’ }); </script>
4 Youtube Support Version 5.6 of the JW Player introduced improved YouTube support, amongst which the setting of the quality level for a video. The HD plugin leverages this feature. The plugin will detect if a video comes from YouTube, and offer a toggle between YouTube’s hd720 and medium quality levels. If a YouTube video is not available in HD, the HD icon will get greyed out.
4.1 Example Here is an example using YouTube. Note the hd.file option is not needed: <div id=’player’>Get Flash to see the video</div> <script type="text/javascript> jwplayer(’player’).setup({ file: ’XSGBVzeBUbk’, flashplayer: ’/assets/player.swf’, plugins: { hd: {} }, provider: ’youtube’ }); </script>
5 Playlist Support HD versions can be assigned to one or more videos in a playlist. You can mix progressive downloads, RTMP streaming, HTTP streaming and YouTube in one list. Since none of the XML playlist formats define elements for linking to HD files, the captions should be set using the JWPlayer XML namespace. In practice, the namespace is enabled by: • Setting an xmlns:jwplayer attribute in the main XML tag. • Prefixing the XML elements with jwplayer:, e.g. <jwplayer:sharing.code>.
5.1 Example Here is an example setup using a playlist. Note the hd.file option is not needed in the embed code: <div id=’player’>Get Flash to see the video</div> <script type="text/javascript> jwplayer(’player’).setup({ file: ’/assets/playlist.xml’, flashplayer: ’/assets/player.swf’, plugins: { hd: {} } }); </script>
Here is the playlist.xml of this example, containing 2 basic videos. The jwplayer:hd.file element defines the HD quality video for each entry. <rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/"> <channel> <item> <title>My first video</title> <description>This one starts the playlist.</description> <jwplayer:file>sd-video.mp4</jwplayer:file> <jwplayer:hd.file>hd-video.mp4</jwplayer:hd.file> </item> <item> <title>My second video</title> <description>This one concludes it all.</description> <jwplayer:file>sd-video-2.mp4</jwplayer:file> <jwplayer:hd.file>hd-video-2.mp4</jwplayer:hd.file> </item> </channel> </rss>
Note: Note the xmlns:jwplayer at the top. It is needed to validate the jwplayer:hd.file elements.
6 Skinning The HD plugin includes support for styling its controlbar or dock button through the JW Player PNG Skinning Model. If the dock is enabled, the player will place the dockIcon in the dock. Otherwise, it will place the controlbarIcon in the controlbar. See below image:
This skin, called Stijl, can be freely downloaded here. Many more skins support the HD plugin, since it’s quite popular.
6.1 Implementation In order to support the HD plugin in your skin, make sure that your skin contains an hd folder and this folder contains both a graphic called controlbarIcon.png and dockIcon.png. Your skin XML should then include the following component block, which links the PNG images to the HD plugin: <component name="hd"> <elements> <element name="dockIcon" src="dockIcon.png" /> <element name="controlbarIcon" src="controlbarIcon.png" /> </elements> </component>
7 Changelog 7.1 Version 2.0 • Migrated plugin to V5 API; new HD.as implements IPlugin and works natively with JW 5+. As of 2.0, the plugin doesn’t work with the 4.x player anymore. • Added basic support for PNG skinning, by allowing a custom controlbar and dock icon.
7.2 Version 2.1 • Added support for YouTube AS3, which is available as of JW Player 5.6. • Fixed a bug that caused the embed option hd.file to appear as the HD version of each file in the playlist. • Fixed a bug that made the HD plugin toggle to low quality on fullscreen if the hd.fullscreen option was used.