JW PLAYERS 3.12 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

COLOR FLASHVARS

APPEARANCE FLASHVARS

PLAYBACK FLASHVARS

INTERACTION FLASHVARS

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.

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 ATOM Tag
file <location> <enclosure> or <media:content> <link rel="enclosure">
title <title> <title> <title>
link <info> <link> <link>
id <identifier> <guid> <id>
image <image> <media:thumbnail> or <itunes:image> <link rel="image">
author <creator> <author> <name>
captions <link rel="captions"> <enclosure type="captions"> <link rel="captions">
audio* <link rel="audio"> <enclosure type="audio"> <link rel="audio">
category** <album> <category> <category>
start*** <meta rel="start"> - -
type**** last three characters of <location>or <meta rel="type"> mimetype of <enclosure> mimetype of <link rel="enclosure">

* The Image Rotator will only playback the 'audio' of the first item in the playlist, to provide background music. The players support a per-element extra audio track.

** The "category" element can be used to specify advertisements. You can set it to "preroll", "postroll" or "overlay". Use the "link" element of the playlistentry to set the commercial's URL. In the extras of my website, there's an advertisements example page.

*** The "start" element is only supported by XSPF playlists, and only works with streaming files (HTTP or RTMP). Use it to specify the starting position in seconds. Here's an example page.

**** 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.

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:

schematic overview of the players

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:

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.