mdaines / aud

"Aud" -- a simple library for sound in the browser

* To use Aud:

  1. Install Aud. Two options:
  
    a. Use Sprockets and put the Aud distribution in the
       appropriate place.
  
    b. Install manually. Aud expects its accompanying SWF file
       to be at /swf/aud.swf, but you can change this by
       modifying Aud.SWF_PATH in your script. Put the JavaScript
       source somewhere convenient and include it in your page.

  2. Ask for an Aud instance

    var sound = new Aud("sound.mp3");

  3. Play, pause, observe events

    sound.observe("timeupdate", function(e) {
      console.log(e.target.getCurrentTime() / e.target.getDuration());
    });
    
    sound.play(2000, 4000);
    
    setTimeout(function() {
      sound.stop();
    }, 1000);

* Aud supports these events:

    loadstart
    (dispatched immediately after the sound starts loading)
    
    progress
    (progress has been made loading the sound)

    load
    (the sound has finished loading)
    
    ioerror
    (an error occurred while loading the sound)

    timeupdate
    (the sound is playing and a new value for Aud#getCurrentTime
    is available)

    stopped
    (playback was stopped by Aud#stop)

    ended
    (playback reached the end of the sound or the end time specified
    by Aud#play)

* Aud instances let you ask about a couple things:

    Aud#getBytesLoaded
    Aud#getBytesTotal
    Aud#getDuration
    Aud#getCurrentTime

* Aud#play may be called at any time after the loadstart event is
  dispatched, allowing for streaming playback.

* When observing events, you get a fake "event object": just an
  otherwise blank object with a 'target' slot set to the associated
  Aud instance.

* Aud#play takes start and end arguments, allowing you to play a
  part of a sound. Both arguments are optional. End-time accuracy
  is not entirely guaranteed.
  
* Aud#play may be called before loading has completed. This allows
  you to stream sounds.

* Times are always in milliseconds.

* The path to aud.swf is configurable. Set Aud.SWF_PATH before asking
  for an Aud instance.