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:
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!).
<p id="player"><a href="http://www.macromedia.com/go/getflashplayer">Get Flash</a> to see this player.</p>
<script type="text/javascript">
var FO = { movie:"mediaplayer.swf",width:"300",height:"20",majorversion:"7",build:"0",bgcolor:"#FFFFFF",
flashvars:"file=playlist.xml&autostart=true" };
UFO.create(FO,"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 mediaplayer.swf 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="300" height="200" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http://www.myfileserver.com/folder/playlist.xml&autostart=true" />
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.
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.
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.
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.