= Javascript controlled Flash MP3 player =

This is a very small (2.1KB) flash object which can be controlled via Javascript.
This allows to build the player UI using HTML, CSS and JS only, without having
to program in ActionScript.

== Features ==

* Open source (GNU/GPL)
* Simple scriptable JS interface
* Debug interface to trace communications between JS and player
* Flashblock support
* Lightweight: using from 10 to 90% less cpu resources than other flash players
* Don't crash Flash player if the client doesn't have a sound card
* MP3 files are streamed, playing starts  before the end of the download
* Reading of ID3 tags
* play, pause, stop, set volume, set position (skipping)
* events and callbacks
* intelligent polling, no flash-JS communication unless necessary
* multiple players/applets allowed in the same page

== How to use ==

You can use the examples provided as a start of your player.

Insert the Flash somewhere in the page:

  <object id="myPlayer" class="playerObject" type="application/x-shockwave-flash" data="player.swf" width="50" height="20">
    <param name="movie" value="player.swf" />
    <param name="AllowScriptAccess" value="always" />
    <param name="FlashVars" value="listener=player" />
  </object>

Note that the 'listener' flash variable gives the name of the JS object which will be called from the flash applet.

To allow the Flash-JS communication in IE you have to also insert this:

  <!--[if IE]>
  <script type="text/javascript" event="FSCommand(command,args)" for="myPlayer">
  eval(args);
  </script>
  <![endif]-->

Note that the 'for' argument must match the object id.

You can also insert the <object> using javascript.

Then when the flash will be loaded and ready to be used (this might happen after the user allowed the flash applet), it will call the onInit callback of your JS listener. Refer below for other callbacks and how to call a method of the Flash applet from JS.

== JS callbacks called from the Flash applet ==

* **onInit**: called when the applet is loaded and ready to play music
* **onInitFail**: called when the applet tried to load but failed, probably because the client system doesn't have a soundcard.
* **onUpdate**: called when the song is playing, every 5 iterations (each ~200ms)
* **onSoundComplete**: called at the end of the currently playing song
* **onID3**: called when the Flash player gets the ID3 tags from the streamed file, this may never be called if the file doesn't have ID3 tags

== Call a Flash method from JS ==

To call a method of the Flash applet from your script you have to use this.object.SetVariable. Example:

  this.object.SetVariable("method:play", "");

Will ask the Flash applet to load and play the URL set earlier (using setUrl). The first parameter to SetVariable is the method to call and the second one is the argument to pass to the method.

== Flash applet methods ==

* **setUrl** (argument: MP3 file URL): sets this URL, but the URL is not loaded until the play method is fired
* **play** (no argument): loads and play the URL set using setUrl
* **pause** (no argument): pauses the playing
* **stop** (no argument): stops the playing
* **setPosition** (argument: position in the song, in seconds): skip the song to this position

== JS object properties ==

Those properties are filled by the Flash applet in your listener:

* position: currently playing position
* duration: song duration (unreliable until the file is fully loaded)
* volume: player volume
* isPlaying: true if a song is playing
* isPaused: true if a song is playing
* bytesLoaded: number of bytes loaded
* bytesTotal: size of the MP3 file, in bytes
* bytesPercent: loaded percents of the file
* id3: array containing all ID3 tags

== Changelog ==

Published in 2009.