The Flash MP3 Player is the easiest way to add live music or podcasts to your website. It supports playback of a single MP3 file or an RSS/XSPF playlist, a wide range of flashvars (settings) for tweaking both behavior and appearance and an extensive, documented javascript/actionscript API. Contents of this readme:
This script is licensed under a Creative Commons License. It allows you to use and modify the script for noncommercial purposes. For commercial use, I distribute licenses of the script for 15 euros. For more info and instant ordering, please advance to my online order page!
You can download the Flash MP3 Player here. It includes the source files (Flash8) and a readme with tips regarding the installation and use of this script. please read it carefully!
An up-to-date list of third-party plugins for the Flash MP3 Player can be found on the Flash MP3 Player page. If you have written or seen an unlisted plugin, please report so in my forum!
The example mp3player.html works right out of the box. If you look at it's source code (in a text or HTML editor), you can see that both instances of the mp3player 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 mp3player 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 movie, it's width and height, the version and build of Flash that is needed (just leave this to 7 and 0) and the backgroundcolor of the movie. You can also send a list of so-called Flashvars to the script (for that see the next paragraph):
<p id="player1"><a href="http://www.macromedia.com/go/getflashplayer">Get the Flash Player</a> to see this player.</p>
<script type="text/javascript">
var FO = { movie:"mp3player.swf",width:"300",height:"20",majorversion:"7",build:"0",bgcolor:"#FFFFFF",
flashvars:"file=song1.mp3&showdigits=true&autostart=true" };
UFO.create(FO,"player1");
</script>
When the HTML page loads, the javascript replaces the part of your HTML with the "id" you provided in the javascript (in this case the paragraph with the id "player1"), and you have a Flash player running on your website.
If you cannot use javascript on your website (for example if you run the mp3player on a profile site like MySpace), you can use an "embed" code instead of the javascript. Your m3player.swf will probably be on another server then. That is OK, but note that your playlist.xml should always reside on the same server than your SWF, or else the security restrictions won't allow the mp3player.swf to load it:
<embed src="http://www.myfileserver.com/folder/mp3player.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&showdigits=true&autostart=true" />
The flashvars are settings you can insert into your HTML code to control both behavior and appearance of the mp3player. In the installation example above, you can see how to insert these flashvars: just insert them into the "flashvars" attribute of your embed code, and stack them with the "&" symbol. Here is a list of all flashvars, their default values are bold:
| Name | Values | Explanation |
| file | URL (song.mp3) | The location of the file to play. It can be a single MP3 file, or an RSS or XSPF playlist. For more info about playlists, see below. |
| autostart | true,false | Set this to "true" if you want the m3player to automatically start playing. |
| shuffle | true,false | If you have a playlist, the mp3player will shuffle through the songs. Set this to "false" if ou don't want that. |
| repeat | true,false | Set this to true to make the mp3player automatically repeat playing when a song is completed. |
| backcolor | COLOR (0xFFFFFF) | Backgroundcolor of the mp3player. 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 mp3player. 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 mp3player. In the "extras" folder of this download there's a colorpicker script with which you can pick a hexadecimal color. |
| displayheight | NUMBER (0) | Height of the display. If you add thumbnails to your playlist, you can set this greater than 0 (you can als use SWF animations for cool visualizations!). |
| linkfromdisplay | true, false | If you defined links in your playlist 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 MP3. |
| linktarget | FRAME (_SELF) | This is the target frame in which the links 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 in the display won't show. |
| overstretch | true,false,fit,none | This flashvars controls the stretching of the display images. 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" won't scale the images at all. |
| showeq | true,false | Shows a (purely cosmetic) equalizer in the display when set to true. If the displayheight isn't set, it defaults to a height of 50px. If you load an image into the display, it'll be shown behind the EQ. |
| showdigits | true,false | Set this to false to hide the digits for % loaded, elapsed and remaining time in the mp3player. |
| volume | NUMBER (80) | Startup volume of the mp3player. |
| 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. |
| thumbsinplaylist | true,false | Set this to true if you want to show small thumbnails of the cover images in the playlist. |
| callback | URL (undefined) | You can set the location of a server-side script here to track callback statistics. The mp3player will send the url, title and id of any song that is either started or completed by the user. A small example of a statistics script can be found in the "extras" folder of this download. |
| 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. The example uses the mediaplayer, but all controls are similar to the ones for the mp3player. |
| width | NUMBER | Force the width of your movie if you have a messed-up display in IE. Normally, just setting the width in your HTML will be sufficient. |
| height | NUMBER | Force the height of your movie if you have a messed-up display in IE. 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 getmp3.php?id=23421, you can set it like this: getmp3.php%3Fid%3D23421.
Besides a single file, you can also load an entire playlist of MP3 files into the mp3player. The mp3player supports two commonly used playlist formats to ensure maximum compatibility: RSS (much-used for Podcasts) and XSPF (much used for CC music). The example playlist.xml of this download is in XSPF format.
Note that you can also send each tag like a flashvar to the mp3player, in case you use a single MP3 file. So if you have a single file "song.mp3" and want to display a cover image, you can set the flashvars "file=song.mp3&image=albumcover.jpg". Here is a list of all flashvars and their corresponding XSPF/RSS tags that are supported by the mp3player. Their names should be self-explanatory:
| Flashvar | XSPF Tag | RSS Tag |
| file | location | enclosure or media:content |
| title | title | title |
| author | creator | author |
| link | info | link |
| image | image | media:thumbnail or itunes:image |
| id | identifier | guid |
| start | meta * | - |
* The start flashvar allows you to provide a starting percentage for each playlist item. 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 50% inside a file, the player will still have to download the first 50% as well. This is how the tag looks like in XSPF:
<meta rel="http://www.jeroenwijering.com/start">50</meta>
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 youyr playlists. It will save you a lot of troubles with unresponsive mp3players 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 MP3 files instead of opening them in your 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 or scanning a certain directory for mediafiles. In both cases you can feed the php file to the mp3player with the "file" flashvar.
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)
This player 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, javascript control and the digits in the controlbar.
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.
For tips, tricks, additional info and bug reports, you can always have a look at my forum's Flash MP3 Player threads.
For more info about the embedding of Flash in HTML, have a look at my Embedding Flash article.