JW PLAYERS 3.13 README
This readme contains information regarding the installation and configuration of the JW MP3 Player, JW FLV Player, JW Media Player and JW Image Rotator. It's also available in Chinese. Contents of this readme:
For a quick setup of flashvars, check out the setup wizard.
INSTALLING
The example HTML file in the download works right out of the box. If you look at it's source code (in a text or HTML editor), you can see that the SWF files are inserted in the page with a small javascript. These javascripts use the external swfobject.js script by Geoff Stearns in order to prevent the annoying "click here to activate" message. If you copy the SWF to your website, make sure you don't forget to copy the swfobject.js file as well. It is inserted in the HTML page right at the top:
<script type="text/javascript" src="swfobject.js"></script>
An insertion javascript allows you to set the location of the SWF, it's width and height, a name, the version of Flash that is needed and the backgroundcolor of the movie. You can also send a list of flashvars (with the addVariable() command) to the SWF to configure it (for that see the next paragraph). When the HTML page loads, the javascript replaces the element of your HTML with the "id" you provided in the javascript (make sure you have an element with that id!).
<p id="player"><a href="http://www.macromedia.com/go/getflashplayer">Get Flash</a> to see this player.</p>
<script type="text/javascript">
var so = new SWFObject('mediaplayer.swf','player','400','400','7');
so.addParam("allowfullscreen","true");
so.addVariable("file","test.flv");
so.addVariable("displayheight","300");
so.write('player');
</script>
If you cannot use javascript on your website (for example if you run the SWF on a profile site like MySpace), you can use an "embed" code instead of the javascript. Your SWF will probably be on another server then. That is OK, but note that your XML playlist (if used) should always reside on the same server than your SWF, or else the security restrictions won't allow the player to load it. Having MP3 or JPG or FLV files on a different server is no problem.
<embed src="http://www.myfileserver.com/folder/mediaplayer.swf" width="400" height="400"
type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer"
flashvars="file=http://www.myfileserver.com/folder/test.flv&displayheight=300" />
FLASHVARS
Flashvars are variables you can insert into your HTML code to control both behavior and appearance of the player/rotator. With the swfobject embed method, you add them with the addVariable() function and in the embed method they are inside the "flashvars" attribute, stacked with an "&" symbol. At this page you'll find a wizard in which you can easily set all flashvars. In the lists below, all flashvars are explained.
All variables with an * are also available to the rotator.
BASIC FLASHVARS
- displayheight (number): This flashvar is used by the players and sets the height of the display. It defaults to the height of the SWF object minus the controlbar (20px), but if you set it to a smaller height, the playlist will show up. If you set it to the height of the player itself (or larger), the controlbar will auto-hide over the video.
- file* (url): The location of the file to play. It can be a single file (MP3/FLV/RTMP/JPG/SWF/PNG/GIF) or a playlist for the players. The rotator only accepts playlists.
- height* (number): As with the width of the player/rotator, this variable is already set with a default embed code. However, sometimes (notably on IE), this won't get through (so you get a messed-up display). Then use this flashvar to tell the player/rotator how many pixels high it should be.
- image (url): If you play MP3 of FLV files, you can use this flashvar to show a preview image or album cover. It can be a JPG/SWF/PNG/GIF file. You can also assign an image for every item in a playlist.
- shownavigation* (true,false): Another flashvar only for the rotator. It enables/disables the navigation bar.
- transition* (bgfade,blocks,bubbles,circles,fade,flash,fluids,lines,random,slowfade): This flashvar is only used by the rotator. It sets the transition to use between images. "random" will show all transitions randomly. The default is "fade".
- width* (number): As with the height of the player/rotator, this variable is already set with a default embed code. However, sometimes (notably on IE), this won't get through (so you get a messed-up display). Then use this flashvar to tell the player/rotator how many pixels wide it should be.
COLOR FLASHVARS
- backcolor* (color): Backgroundcolor of the player/rotator. In the "extras" folder of this download there's a colorpicker script with which you can pick a color value. The default for the players is 0xFFFFFF (white) and for the rotator 0x000000 (black).
- frontcolor* (color): Texts / buttons color of the player/rotator. The default for the players is 0x000000 (black) and for the rotator 0xFFFFFF (white).
- lightcolor* (color): Rollover/ active color of the player/rotator. The default for the players is 0x000000 (black) and for the rotator 0xCC0000 (red).
- screencolor* (color): Color of the display background screen. The default is 0x000000 (black). With the rotator, change this to make images of different sizes blend nicely with your page. With the player, instead of choosing another color, you can of course also set a background image.
APPEARANCE FLASHVARS
- autoscroll (true,false): By default, the playlist area of the players will have a scrollbar if the number of items is too long. If you set this flashvar to "true", the scrollbar wil disappear and the playlist will scroll automatically, depending upon the mouse position.
- displaywidth (number of pixels): Instead of the "displayheight", you can set "displaywidth" to a size smaller that the SWF width to make the playlist appear at the right side of the display.
- kenburns* (true,false): Set this to true to apply the Ken Burns effect to images in the rotator. Note that this works best when using large images from the same server on a fast computer. Small images from different servers and slow computers produce blurry results and choppy motion. Works also best in combination with the "slowfade" transition.
- largecontrols (true,false): Set this to true to make the controlbar twice as large. This is useful to visually impaired users.
- logo* (url): Set this flashvar to put a watermark logo in the top right corner of the display. All image formats are supported, but transparent PNG files give the best results.
- overstretch* (true,false,fit,none): Defines how to stretch images/movies to make them fit the display. "true" will stretch them proportionally to fill the display, "false" will stretch them to fit. "fit" will stretch them disproportionally to fit both height and width. "none" will show all items in their original dimensions. Defaults to "fit" for the players and "false" for the rotator.
- showdigits (true,false,total): Set this to false if you don't want the elapsed/remaining time to display in the controlbar of the players. Quite handy to save some space. Set it to "total" to show the total time instead of the remaining time.
- showdownload (true,false): Set this to true to show a downloadbutton in the controlbar. The downloadbutton links to the link flashvar.
- showeq (true,false): Set to true to show a fake equalizer in the display. It adds a nice graphical touch when you are playing MP3 files.
- showicons* (true,false): Show or hide the play and activity icons in the middle of the display. Defaults to true for the players and false for the rotator. If set to false, the overlaid controlbar will also hide with the players.
- showstop (true,false): Set this to true to show a stop button in the controlbar.
- showvolume (true,false): Set this to false to hide the volume button and save space.
- thumbsinplaylist (true,false): If you have a playlist that also includes preview images with the <image> element, you can set this flashvar to "true" to show them in the playlist.
PLAYBACK FLASHVARS
- autostart (true,false,muted): Set this to "true" to make the player automatically start playing when the page loads. If set to "muted", the player will autostart with the volume set to 0 and an unmute icon in the display.
- bufferlength (number): This sets the number of seconds an FLV should be buffered ahead before the player starts it. Set this smaller for fast connections or short videos. Set this bigger for slow connections. The default is 3 seconds.
- deblocking (true,false): If set to "false", video will not deblock, resulting in a more pixelated, but better performing display. Use this for large screen / slow computer combinations.
- repeat* (true,false,list): By default, the players will stop playback after every item to preserve bandwidth (repeat=false). You can set this to "list" to playback all items in a playlist once, or to "true" to continously playback your song/movie/playlist.
- rotatetime* (number): Use this flashvar to set the number of seconds you want an image to display. The default is "10" for the mediaplayer and "5" for the rotator.
- shuffle* (true,false): If you use a playlist, the players and rotator will automatically shuffle the entries to prevent boredom. Set this flashvar to "false" to play all items sequentially.
- smoothing (true,false): If set to "false", video will not smooth, resulting in a more pixelated, but better performing display. Use this for large screen / slow computer combinations.
- start* (second): If you use RTMP or HTTP streaming (not for regular FLV or MP3 files); use this flashvar to specify an offset start position. You can also use this flashvar in XSPF playlists, so you can make a chapter index of a single file.
- volume* (number): The default volume for playback of sounds/movies is 80, but you can set another startup value with this flashvar.
INTERACTION FLASHVARS
- audio* (url): You can set this flashvar to the location of an external mp3 file that should serve as an additional audiotrack. Use this for accessibility commentary, director's comments or, with the imagerotator, background music.
- bwfile (url): Image to use for bandwidth checking; used in conjunction with bwstreams. Assign a simple image to this flashvar (this one will do nice), or the rtmp location of the serverside bwcheck script that can be downloaded here. Here's an example bandwidth checking player.
- bwstreams (comma-separated list of bitrates): The different streams to use for bandwidth checking; used in conjunction with bwfile. If, for example, you want to play the video video.flv and set this to 100,250,500,1000 and the player detects a bandwidth of 349kbps, the file video_250.flv will be played. Here's an example bandwidth checking player. Note that bandwidth checking is ignored for audio and images!
- callback (url): Set this flashvar to the location of a serverside script (PHP/ASP) that can process callbacks. The players will send a callback every time an item starts/stops, so you can save statistics with the serverside script. More info can be found in this demonstration page. An example callback script is placed in the "extras" folder of the downloads. Set this to "analytics" to send the callbacks automatically to Google Analytics.
- captions (url): You can set this flashvar to the location of an external textfile with captions. The players support SMIL's TimedText format (example) and the SRT format (example) used with ripped DVD's. Set this flashvar to "captionate" if your FLV file has Captionate captions embedded. If you use multitrack Captionate captions, you can set this flashvar to "captionate0", "captionate3" etc. to display a certain track. A live example of different captions can be found here. You can also assign captions for every item in a playlist.
- enablejs* (true,false): Set this to true to enable javascript interaction. This'll only work online! Javascript interaction includes playback control, asynchroneous loading of media files and return of track information to javascript.An example of all supported javascript functions can be found on this page.
- fsbuttonlink (url): The players automatically shows a fullscreen button if a user has installed a capable flashplayer (from 9.0.28). With this flashvar, you can link to an alternative page to display a sort-of fullscreen version of the player. Use serverside variables or the getQueryParamValue() function of SWF Object to send the "file" and any other flashvars to that fullscreen-substitute page.
- id (string): The unique identifier of the file to play. It will be sent to serverside callbacks(see below here, and is also used when using RTMP streams. In the latter case, the "file" flashvar points to the rtmp:// stream, and this "id" flashvar to the precise file to play. You can also assign an id for every item in a playlist.
- javascriptid* (string): If you control multiple players/rotators with javascript, you can use this flashvar to give each of them a unique ID. It will be returned with every call to the getUpdate() event. Demo on this page.
- link (url): Set here the url to an external URL, downloadeable version of the file, or force-download script you can use for downloading the file. You can assign link-clicks to the display (see below), the downloadbutton and every item in a playlist.
- linkfromdisplay* (true,false): You can set this flashvar to "true" to make a click on the image/video display to result in a jump to the "link" webpage. By default, a click on the display will play/pause the movie.
- linktarget* (frame): The targetframe a link (from the display or playlist buttons) will open into. The default is "_self". Set it to "_blank" to open links in a new window.
- recommendations* (url): URL to an XML with movies you want to recommend. The thumbs will show up when the current movie stops playing, just like YouTube. Here's an example XML, and in the wizard, there's an example setup.
- streamscript (url): This flashvar is the URL of an optional script to use for 'fake streaming' FLV or MP4 files, eg. through PHP, ASP or LigHTTPD. The parameters 'file' and 'pos' are sent to the script. An example file, "stream.php", can be found in the "extras" folder of the downloads. If you use the LigHTTPD FLV module, set this to the value "lighttpd" (works for FLV and MP4). Note that all FLV and MP4 files you want to fake-stream should have an array with keyframe-positions in their metadata! More info and a running example can be found at this page.
- type (mp3,flv,rtmp,jpg,png,gif,swf,rbs,3gp,mp4,m4v): The players determine the type of file to play based upon the last three characters of the "file" flashvar. This method doesn't work if you use database id's or mod_rewrite to retrieve the files. Therefore you can set this flashvar to tell the players of which filetype the file you want to play is. The type is also assigned to every item in a playlist. If no match is found, the player assumes it loads a playlist.
- useaudio (true,false): Set this to false to force the additional audiotrack to mute by default.
- usecaptions (true,false): Set this to false to force the captions to hide by default.
- usefullscreen (true,false): Set this flashvar to false if you don't want to use the flash9 fullscreen functionality. If you added a "fsbuttonlink" flashvar as well, this link will become the default action for the fullscreen page.
- usekeys (true,false): Set this to false to disable keyboard input (SPACE,UP,DOWN,LEFT,RIGHT) for the players.
Note that you must urlencode any ? = & symbols inside flashvars. The urlencoded values for these symbols are: ? → %3F, = → %3D, & → %26. So if your "file" flashvar has the value of getplaylist.php?id=123, you can set it like this: getplaylist.php%3Fid%3D123.
If you have lots of flashvars and you don't want to mess up your HTML pages, you can also aggregate your flashvars in a single XML file like this one. Next, assign this xml file to the config flashvar of your player. That way, all vars inside the config will be parsed with one line of code. Any additional flashvars you do set in your HTML will override the ones that are in the config XML.
PLAYLISTS
You can load a single file as well as an entire playlist of files into the players. The players look at the filename to determine whether a single file or a playlist is loaded. For example, if your file is test.mp3, it will presume you load a single MP3 file, because the extension is "mp3". If your filename is getlist.php, the SWF will see a playlist. If you use dynamic scripts to load a single file (e.g. getmovie.php%3Fid%3D123), you can tell the player which file it loads by using the additional "type" flashvar: "type=flv".
The players support three commonly used playlist formats to ensure maximum compatibility: XSPF (much used for CC music), RSS (much-used for Podcasts) and ATOM (much-used by Blogs). The example playlist.xml that comes with the downloads is in XSPF format. On my website, I've placed additional examples of both an xspf playlist and an rss playlist, with nearly all supported tags included. If you assign a regular feed without any media enclosures to the player, the player will use the API from Talkr.com to perform a text-to-speech operation on the feed's items, instantly turning your feed into a podcast!
Here is a complete list of all flashvars with corresponding XSPF/RSS/ATOM tags that are supported by the player/rotator:
Flashvar | XSPF Tag | RSS Tag | ASX Tag |
file | <location> | <media:content> | <ref> |
title | <title> | <title> | <title> |
link | <info> | <link> | <moreinfo> |
id | <identifier> | <guid> | - |
image | <image> | <media:thumbnail> | - |
author | <creator> | <author> | <author> |
duration | - | duration of <media:content> | <duration> |
type * | last three characters of <location> | mimetype of <enclosure> | - |
wildcard ** | meta.rel | - | param.name |
* If the XSPF "location" url doesn't contain a useful extension (e.g. "mp3" or "flv"), use the "meta" element to tell the player which filetype it is (e.g. <meta rel='"type">mp3</meta> ). For RSS and ATOM, the filetype is automatically extracted from the mimetype.
** With a wildcard, you can save any parameter you want to the player config. For example, with <meta rel="captions">captions.xml</meta>, you can set a captions entry with XSPF.
Note that, if you play a single file, you can send each item in this table as a flashvar to the SWF. This way, you can add an image, title, id, link, etc. to a single file as well. So if you have, for example, the flvplayer and a single file "video.flv" and want to display a preview image too, you can set the flashvars "file=video.flv" and "image=preview.jpg". For refering to RTMP streams, the additional "id" flashvar has to be sent as well. Example: "file=rtmp://my.streaming.server/mypath" and "id=video_one".
I'd like to point out two common pitfalls users encounter when using playlists. First, a playlist should always reside on the same server as the SWF file, due to security restrictions of the Flash Player (there is a small workaround, tunneling the external feed through a serverside script. Here's an example in PHP.). Second, always try to use full URL's (including the http:// part) when referring to files, links or images in your playlists. It will save you a lot of troubles with unresponsive SWF's or "file not found" errors!
I've included some additional PHP scripts in the "extras" folder of my website, two for auto-creating playlists and one for force-downloading files.
CUSTOMIZATION
I receive a lot of requests for creating customized versions of my players. In most cases however, a clever setting of the flashvars already fulfilled the requests, so please make sure you check these first! I've made an online wizard you can use to easily set all flashvars. Additionally, I do not design or program any particular (paid-for) customizations (I just don't have time for it), but interesting features will be plugged into the next update of the players.
If you are familiar with actionscripting yourself, you should find that changing or adding to the players is quite simple. To get started, check out this schematic overview of the player's code. Note that the flvplayer, mp3player and mediaplayer are identical in terms of code:

A player starts by instantiating either the ImageRotator or Mediaplayer class, which loads all config and playlist variables and sets up the MCV cycle. The config and feeder objects are available to each member of the MCV cycle. The two objects in red have javascript handlers, so all their functions are available through javascript. Here is an online page with examples of all javascript functions.
Communication between the MCV's members is strictly defined (with the updates, changes and events). Creating a complete new look for any of the players (or adding something like a rating field or recommendations) can be done by creating a new class that extends the AbstractView and instantiating it in the MediaPlayer.as class. The ControlbarView class is a good AbstractView extension to copy and modify for this purpose (it contains all controlbar graphics).
Because of the many requests to hide part of the url for media files to prevent stealing, I have added a single line of code to the script in the FLA's timeline. If you un-comment this line (//var prefix = "..."), you can set here a prefix url the players will use for the FLV/MP3/etc. Set this e.g. to the directory where your mediafiles are located (http://www.jeroenwijering.com/uploads/), and then you only have to add the filename of your mediafiles to the flashvars/playlists.
Placing the player/rotator into another Flash file is also possible. Just copy-paste the player or rotator symbol from the FLA file in the download to your FLA file. Also make sure you copy the "com" directory to the directory of your FLA file as well; it contains all scripting. If that's done, you can set all flashvars as variables in the root timeline and start the player from there as well. Make sure you set the "width" and "height" flashvar too, or the player/rotator will stretch to your entire stage! Here's an example:
// Set the flashvars (booleans and numbers should also be quoted)
var width = "320";
var height = "240";
var file = "my_video.flv";
var autostart = "true";
// Start the player
var mpl = new com.jeroenwijering.players.MediaPlayer(this.player);
Additionally, I have made the controller a public object, so you can control the mediaplayer with the getEvent() function from anywhere in your flash site (the schematic above has a list of all getEvent() options). Let's continue the small script above:
// Control the mediaplayer
mpl.controller.getEvent("volume",50);
mpl.controller.getEvent("playpause");
SUPPORT
Here's a small list with frequently-encountered problems:
- If you get strange display errors on IE (most notably after refreshing), the Stage dimensions are probably not properly set. You can use flashvars "width" and "height" to force specific dimensions to the player/rotator and fix this problem.
- Note that, due to security restrictions in the Flash Player, javascript interaction will not work when testing locally. Accessing remote media files or jumping to remote URL's also won't work because of this. Both will work fine if you test from your webserver.
- True fullscreen only works if you have the Flash Player 9,0,28,0 or higher installed. If you use the SWFObject javascript to embed your player, you can use it's auto-update functionality. Also make sure you have the parameter "allowfullscreen" set to "true" in your embed code!
- If the progressbar isn't running with your FLV file, or if your video dimensions are messed-up, your FLV file doesn't have correct metadata inserted. You can fix this by using the small tool available at www.buraks.com/flvmdi/.
- If the player plays FLV files on your computer but not on your website and your website is running of an IIS server, then the FLV mimetype isn't added to the server yet. You can check this by typing in the direct address to your FLV file in your browser. If you get a 404, you're on IIS without mimetype. Please contact your webserver administrator on this (if you're an admin, here's how to fix it).
- If you encounter too fast or too slow playback of MP3 files or if your progressbar is messed up, your MP3 files contains variable bitrate encoding. Flash isn't very good at handling these, it's best to stick to constant bitrate encoding. Also make sure to stick to a sampling frequency that is a multitude of 11.025kHz (48kHz, for example, also poses problems). The free iTunes software has a basic, decent MP3 encoder.
- The player/rotator will run quite OK inside the Flash Player 7. However, the following features are not supported: display of GIF/PNG images, smoothing of scaled images/video, VP6 encoded video, javascript control and the digits in the controlbar.
An up-to-date list of third-party plugins for each list can be found on my website, at the respective player's page. If you have written or seen an unlisted plugin, please report so in my forum!
For tips, tricks, additional info and bug reports, you can always have a look at my Support Forum.
For more info about the embedding of Flash in HTML, have a look at my Embedding Flash article.
For more info about Flash Video and some compression tips, check out my Flash Video Compression article.