FLASH PLAYERS 3.7 README

This readme contains information regarding the installation and configuration of my Flash MP3 Player, Flash Video Player, Flash Media Player and Flash Image Rotator. Contents of this readme:

• Installing (embed codes for your site)
• Flashvars (all configuration options):
  • Basic flashvars
  • Color flashvars
  • Appearance flashvars
  • Playback flashvars
  • Interaction flashvars
• Playlists (how to create playlists)
• Customization (how to customize the players)
• Support (common pitfalls plus support links)

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:

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!).

Get Flash to see this player.

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.

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* (fade,bgfade,blocks,circles,fluids,lines,random): 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).

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.
• 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 bottom right corner of the display. If you've set the "link" flashvar as well, the logo will link to there. Again, 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): Set this to false if you don't want the elapsed/total time to display in the controlbar of the players. Quite handy to save some space.
• 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.
• thumbsinplaylist (true,false): If you have a playlist that also includes preview images with the element, you can set this flashvar to "true" to show them in the playlist.

PLAYBACK FLASHVARS

• autostart (true,false): Set this to "true" to make the player automatically start playing when the page loads.
• 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 5 seconds.
• 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.
• volume (number): The default volume for playback of sounds/movies is 80, but you can set another startup value with this flashvar.

INTERACTION FLASHVARS

• 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.
• 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. An example of both formats can be found in the "extras" folder of the download and a live example 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.
• link (url): If you have set a watermark logo, you can set this flashvar to a web address you want the logo to link to. You can also assign a link for every item in a playlist.
• linkfromdisplay* (true,false): Additionally, you can set this flashvar to "true" to make a click on the image/video display result in a jump to the "link" webpage.
• linktarget* (frame): The targetframe a link (from logo, display or playlist buttons) will open into. The default is "_self". Set it to "_blank" to open links in a new window.
• streamscript (url): This flashvar is the 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 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". Note that all FLV 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): 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.
• 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.

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. Here is a complete list of all flashvars and their corresponding XSPF/RSS/ATOM tags that are supported by the player/rotator: