MooSound ======================== MooSound is a MooTools API for Flash-enabled sound management. That may not seem very exciting on its own, but if you need to add sounds to your page using MooTools, you'll probably find it useful. License ------------------------ Copyright (c) 2007, 2008 Michelle Steigerwalt and released under LGPL 2.1 . Credits ------------------------ This plugin utilizes and comes packaged with the MooTools JavaScript framework. This version of the plugin requires MooTools version 1.2. You can build a custom download to meet your needs at . The Robot Song is from the Interrobang Cartel . The buttons in the demo once again come from the Sweetie Icon Pack . (Thanks again, Joe!) Everything else created by Michelle Steigerwalt . Boring API Documentation ======================== Here's a really long, really detailed listing of every method callable with this API (hopefully I'll find a more engaging way to display all this raw information later). Class Composition ------------------------ Playlist is a global Singleton with methods for manipulating the Sound objects on a page. The most notable methods are loadSound(s) and getSound. Playlist.loadSounds ------------------------ Loads an array of URLs as Sound files. ### Syntax: Playlist.loadSounds(songsArray[, options]); ### Arguments: 1. songsArray - (*array*) An array of strings representing the locations of sound files to include. 2. options - (*object*, optional) The options (see the options section of the Sound class documentation below). ### Returns: * (*Playlist*) The Playlist instance. ### Example: var sounds = ['song1.mp3', 'song2.mp3', 'song3.mp3']; Playlist.loadSounds(sounds, { onLoad: function() { alert("Sound loaded!"); } }); Playlist.loadSound ------------------------ Exactly the same as loadSounds above, except that a string is passed as the sound URL instead of an array of strings. ### Syntax: Playlist.loadSound(song[, options]); ### Arguments: 1. song - (*string*) A string representing the location of sound file to register. 2. options - (*object*, optional) The options (see the options section of the Sound class documentation below). ### Returns: * (*Playlist*) The Playlist instance. ### Example: Playlist.loadSound('mySound.mp3', { onLoad: function() { alert("Sound loaded!"); } }); Playlist.getSound ------------------------ Returns a Sound object based on its key (key defaults to URL). ### Syntax: Playlist.getSound(key); ### Arguments: 1. key - (*string*) The key (URL) of the Sound object. ### Returns: * (*Sound*) The Sound instance or null. ### Example: var mySound = Playlist.getSound('mySound.mp3').start(); Playlist.stopSounds ------------------------ Stops all playing sounds immediately. ### Syntax: Playlist.stopSounds(); ### Returns: * (*Playlist*) The Playlist instance. ### Example: Playlist.stopSounds(); //Silence. Playlist.playRandom ------------------------ Plays a random Sound. ### Syntax: Playlist.playRandom(); ### Returns: * (*Playlist*) The Playlist instance. ### Example: //Silence. Playlist.playRandom(); //Music, yay! \o/ Sound Methods ------------------------ NOTE: The Sound.initialize method should be treated as a private method. **Instantiating Sound objects should only occur through the Playlist Class.** ### Options: * autostart - (*boolean*, defaults to false) If autostart is set to true, the song will begin playing as soon as it's ready. * streaming - (*boolean*, defaults to true) If streaming is set to true, the file will be streamed, rather than downloaded and then played. * volume - (*int*, defaults to 50) A value from 0-100, representing the volume of the Sound. * pan - (*int*, defaults to 0) A value from -50 (left) to 50 (right), representing the balance of the Sound. * progressInterval - (*int*, defaults to 500) The length of time (milliseconds) between calls to the Flash instance in order to check the progress of the Sound file download. * positionInterval - (*int*, defaults to 500) The length of time (milliseconds) between calls to the Flash instance in order to check the current time position of the Sound file. ### Sound Events: #### onRegister Fires when the sound is registered with the SWF file. #### onLoad Fires when the sound has completed its download. #### onPlay Fires when the sound begins playing. #### onPause Fires when the sound is paused. #### onStop Fires when the sound stops playing. #### onFinish Fires when the sound completes playing. #### onProgress Fires when the sound file's download has made progress. 1. bytesLoaded - (*int*) The number of bytes currently loaded of the sound file. 2. bytesTotal - (*int*) The number of bytes total of the sound file. #### onPosition Fires when the sound's position in its playback timeline changes. 1. currentPosition - (*int*) The current position (in seconds) of the sound file. 2. totalDuration - (*int*) The total duration (in seconds) of the sound file. #### onID3 Fires when a new ID3 tag is ready. 1. tag - (*string*) The tag name of the ID3 information. 2. value - (*string*) The value of the ID3 information. Sound.start ------------------------ ### Syntax: mySound.start([seconds]); ### Arguments: 1. seconds - (*int*, optional) The position offset (in seconds) to begin playback from. ### Returns: * (*Sound*) The current Sound object. ### Example: //Starts sound1.mp3 at 10 seconds: mySounds.start(10); Sound.stop ------------------------ Immediately stops the playback of the target Sound object. The Sound's position will be reset to 0. ### Syntax: mySound.start(); ### Returns: * (*Sound*) The current Sound object. ### Example: mySound.stop(); Sound.jumpTo ------------------------ ### Syntax: mySound.jumpTo(seconds); ### Arguments: 1. seconds - (*int*) The position offset (in seconds) to transfer current position to. ### Returns: * (*Sound*) The current Sound object. ### Example: //Immediately jumps to one minute into the Sound. mySound.jumpTo(60); Sound.pause ------------------------ Immediately halts playback of the Sound and saves its current position. ### Syntax: mySound.pause(); ### Returns: * (*Sound*) The current Sound object. ### Example: //Immediately jumps to one minute into the Sound: mySound.start(25); // [... time passes ... ] mySound.pause(); //Resumes playback from the paused position: mySound.start(); Sound.setVolume ------------------------ Immediately sets the volume of the target Sound to the new value. ### Syntax: mySound.setVolume(percent); ### Arguments: 1. percent - (*int*) The volume percentage to set. ### Returns: * (*Sound*) The current Sound object. ### Example: //Sets the maximum volume for a sound: mySound.setVolume(100); //Mutes the sound: mySound.setVolume(0); Sound.getVolume ------------------------ Returns the current volume of the Sound. ### Syntax: mySound.getVolume(); ### Returns: * (*int*) The current volume of the Sound, from 0 to 100. Sound.setPan ------------------------ Immediately sets the balance of the target Sound to the new value. ### Syntax: mySound.setPan(pan); ### Arguments: 1. pan - (*int*) The balance to set, between -50 (left) to 50 (right). ### Returns: * (*Sound*) The current Sound object. ### Example: //Sets the balance of the Sound to center: mySound.setPan(0); //Sets the balance of the Sound 100% left: mySound.setPan(-50); Sound.getPan ------------------------ Returns the current balance of the Sound. ### Syntax: mySound.getPan(); ### Returns: * (*int*) The current balance of the Sound, from -50 (left) to 50 (right). Sound.getID3 ------------------------ Returns the value of the passed ID3 tag, if found. ### Syntax: mySound.getID3(tag); ### Arguments: 1. tag - (*string*) The name of the tag to retrieve the value of. ### Returns: * (*string*) The value of the requested tag (or nothing). ### Example: var title = mySound.getID3('TIT2'); if (title) alert('My title is: '+ title); ### Note: ID3 tags must be registered before they can be accessed. See the onID3 event for more information. Sound.getBytesLoaded ------------------------ Returns the number of bytes loaded of the sound file. ### Syntax: mySound.getBytesLoaded(); ### Returns: * (*int*) The number of bytes loaded. ### Note: It shouldn't be necessary to call this most cases, as the onProgress event is fired every time this value changes. Sound.getFilesize ------------------------ Returns the total size (in bytes) of the sound file. ### Syntax: mySound.getFilesize(); ### Returns: * (*int*) The total filesize of the sound file (in bytes). ### Note: It shouldn't be necessary to call this most cases, as the onProgress event is fired every time this value changes. Sound.getPosition ------------------------ Returns the current position (in seconds) of the sound file. ### Syntax: mySound.getPosition(); ### Returns: * (*int*) The number of seconds the current Sound is playing at. ### Note: It shouldn't be necessary to call this most cases, as the onPosition event is fired every time this value changes. Sound.getDuration ------------------------ Returns the duration (in seconds) of the sound file. ### Syntax: mySound.getDuration(); ### Returns: * (*int*) The duration of the sound file in seconds. ### Note: It shouldn't be necessary to call this most cases, as the onPosition event is fired every time this value changes.