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 ufo.js script by Bobby van der Sluis 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 ufo.js file as well. The ufo.js is inserted in the HTML page right at the top:

<script type="text/javascript" src="ufo.js"></script>

An insertion javascript allows you to set the location of the SWF, it's width and height, the version and build of Flash that is needed (leave to 7 and 0 for maximum compatibility) and the backgroundcolor of the movie. You can also send a list of Flashvars 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!).

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 mediaplayer.swf to load it. Having MP3 or JPG or FLV files on a different server is no problem.

FLASHVARS

Flashvars are configuration options you can insert into your HTML code to control both behavior and appearance of the player/rotator. In the code example above, you could already see them: inside the "flashvars" attribute of your embed code, and stacked with the "&" symbol. This table has a list of all Flashvars, their default values are bold:

Name

Values

Explanation

file

URL (playlist.xml)

The location of the file to play. It can be a single file (MP3/FLV/RTMP/JPG/SWF/PNG/GIF, depending upon the player) or an RSS/XSPF playlist. For more info about playlists, see below.

autostart

true,false

Set this to "true" if you want your player/rotator to automatically start playing. The ImageRotator has this set to "true" by default.

shuffle

true,false

If you have a playlist, the player/rotator will shuffle through the items. Set this to "false" if you want to play all items in order.

repeat

true,false

Set this to true to make the player/rotator automatically continue playing after an item has finished.

backcolor

COLOR (0xFFFFFF)

Backgroundcolor of the player/rotator. In the "extras" folder of this download there's a colorpicker script with which you can pick a hexadecimal color.

frontcolor

COLOR (0x000000)

Texts / buttons color of the player/rotator. In the "extras" folder of this download there's a colorpicker script with which you pick a right hexadecimal color.

lightcolor

COLOR (0x000000)

Rollover/ active color of the player/rotator. In the "extras" folder of this download there's a colorpicker script with which you can pick a hexadecimal color.

displayheight

NUMBER (height-20px)

Height of the display, where images and videos are shown (not for imagerotator).

linkfromdisplay

true, false

If you defined links in your playlist or flashvars and set this to true, a click on the display will jump to the link. Else a click on the display will play/pause the item.

linktarget

FRAME (_SELF)

This is the target frame in which the link and fullscreen pages will show up. Set it to "_blank" to open them in a new window.

showicons

true, false

If set to false, the play and activity icons won't show. False is the default of the ImageRotator.

logo

URL (none)

Use this flashvar to set a logo in the bottomright corner of the display. The logo will show like a watermark, 25% transparent. If you use a PNG file with transparency, the logo will blend in nicely.

overstretch

true,false,fit,none

This flashvars controls the stretching of images/videos. The default "fit" will scale them disproportionally to exactly fit the display, "true" will scale proportionally to fill the display, "false" will scale proportionally to fit the display and "none" will leave the media at their original size.

showdigits

true,false

Set this to false to hide the digits for % loaded, elapsed and remaining time in the players (not for imagerotator).

showeq

true,false

If set to true, it shows a (fake) equalizer in the display (only mp3player).

showfsbutton

true,false

Set this to true to show the fullscreen button (mediaplayer and flvplayer).

fullscreenpage

URL (fullscreen.html)

HTML page to jump to for fullscreen. This HTML page has the SWF included at 100% screensize (mediaplayer and flvplayer).

fsreturnpage

URL (flvplayer.html)

HTML page to return to from fullscreen. This usually is the page you currently include the player into. Both the "fsreturnpage" and "file" are saved as a flashcookie before jumping to fullscreen, hence the fullscreen SWF knows where to go (mediaplayer and flvplayer).

fullscreenmode

true,false

Set this to true to tell the player it is in fullscreen mode (it's done in the fullscreen.html). If so, it shows the controls 50% transparent and links the fullscreen button to the fsreturnpage (mediaplayer and flvplayer).

volume

NUMBER (80)

Startup volume of the players (not for imagerotator).

rotatetime

NUMBER (10)

Number of seconds an image should be displayed (mediaplayer and imagerotator).

shownavigation

true,false

Set this to true to show the navigation bar (only for imagerotator).

transition

fade,bgfade, circles, blocks, fluids, lines, random

This flashvar sets the type of transition to use. The "random" transition will randomly pick one of the other transitions (only for imagerotator).

bufferlength

NUMBER (5)

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 (mediaplayer and flvplayer).

autoscroll

true,false

Set this to true to let the playlist automatically scroll, based upon the mouse cursor. It defaults to false, at which you'll see a scrollbar (not for imagerotator).

thumbsinplaylist

true,false

Set this to true if you want to show small thumbnails of the cover images in the playlist (not for imagerotator).

callback

URL (undefined)

You can set the location of a server-side script here to track callback statistics. The player/rotator will send the file, title and id of any song that is either started, paused or completed by the user. A small example of a statistics script can be found in the "extras" folder of this download. See it in action here at my website.

streamscript

URL (undefined)

URL of an optional script to use for 'fake streaming' FLV files, eg. through PHP, ASP or LigHTTPD. The parameters 'file' and 'pos' are sent to the script. An example is 'stream.php' in the 'extras' folder, more info can be found here, a running example can be found at my site.

enablejs

true, false

Set this to "true" to enable javascript interaction. An example of how to control the rotator with javascript can be found here at my website. Javascript interaction includes playback control, asynchroneous loading of media files and return of track information to javascript. Beware of the javascript functions and player id inside the HTML page, copy-paste these as well to make your javascript page work!

width

NUMBER

Force the width of your SWF to this size if you have a messed-up display after IE refreshes. Normally, just setting the width in your HTML will be sufficient.

height

NUMBER

Force the height of your SWF to this size if you have a messed-up display after IE refreshes. Normally, just setting the height in your HTML will be sufficient.

Note that you can urlencode your flashvars in order to prevent the use of the ? = & symbols. 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 player/rotator. The player/rotator looks at the filename (occurence of ".mp3",".flv",".jpg") 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. 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), make sure the extension of the single file you want to return is always reflected by the filename (e.g. getmovie.php%3Fid%3D123 > get.flv.php%3Fid%3D123), or the SWF will think it has to load a playlist.

Note that, for refering to RTMP streams, the additional "id" flashvar has to be sent as well. Example: "&file=rtmp://my.streaming.server/mypath&id=video_one". You can also insert streams into playlists with this file/id pair (see below).

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 in this download is in XSPF format. Here is a list of all flashvars and their 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 or enclosure

title

title

title

title

author

creator

author

author > name

link

info

link

link

image

image

media:thumbnail or itunes:image

-

id

identifier

guid

id

category*

album

category

category

start**

meta

-

-

* If you set the category element to "commercial", the interface will block for the duration of that item, to prevent skipping commercials. Please use this with care and only embed short commercial clips!

** The start flashvar allows you to provide a starting point in seconds for a playlist item (FLV or MP3). This way, you can turn a playlist into a chapter-index if your refer each item to the same file, but with different starting points. However, if you set a starting point 90sec inside a file, the player will still have to download the first 90sec as well. This is how the tag looks like in XSPF (the item will start at 120 seconds - 2 minutes):

<meta rel="http://www.jeroenwijering.com/start">120</meta>

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&image=preview.jpg".

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, the "external_feed.php" in the "extras" folder of this download). 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 playlist-related files in the "extras" folder of this download. First, the "force_download.php" script will enable you to force a download of your mediafiles instead of opening them in Windows Mediaplayer or any other program. If you copy this script to your website and fill out the "link" tags of your playlist like this: "force_download.php?file=path_to_my_file.mp3", the small link buttons of the playlist will act like download buttons for your files. Second, the "extras" folder contains a PHP example of how to create a playlist on-the-fly, either by pulling data off a database (php_mysql_playlist.php) or scanning a certain directory for mediafiles(php_readdir_playlist.php). In both cases you can feed the php file to the mediaplayer with the "file" flashvar.

SUPPORT

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 the list of flashvars first! 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. I created a Third Party forum category on my website to bring together site owners and freelance developers.

If you are familiar with actionscripting yourself, you should find that changing or adding to the players is quite simple. To get started, I've provided a clear documentation of the code, including a schematic overview of the players.

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.

FLV files: if your progressbar isn't running 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/.

FLV files: if the player works 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).

MP3 files: if you encounter too fast or too slow playback of MP3 files or if your progressbar is messed up, your MP3 files contain 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 frequancy that is a multitude of 11.025kHz (48kHz, for example, also poses 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 forum.