metaudio Player is a stand-alone sound and music player for JavaScript integrated into the Joomla extension metaudio. It comprises of an open-source built-in Flash player without a visual interface and a set of JavaScript methods to interact with it. It allows you play MP3 and M4A/AAC audio files. metaudio Player comes with a reference GUI implementation that illustrates its features but you can easily build you own user interface with CSS/JavaScript.
metaudio Player is licensed under GPLv3 and source code is available for both JavaScript and Flash (i.e. ActionScript 3). metaudio Player requires Flash 10.1 or later.
metaudio Player interacts with its integrated simple Flash player with various external interface methods, and provides native JavaScript objects and methods to play, pause, resume, stop and seek within recordings and help visualize sound playback. The reference implementation for the graphical interface is available for both the MooTools framework and the jQuery library.
Intended audience: developers who wish to use the stand-alone metaudio Player on their website or customize the player included with the metaudio Joomla component.
metaudio Player API methods, properties and events
Properties and methods fall into two categories. Global object properties and methods are accessed using the global object metaudio and they can be thought of as static methods in the metaudio namespace. In contrast, Sound object properties and methods apply to a specific Sound object.
As JavaScript is not a strongly-typed language, types are only included for reference. Some pseudo-types (all of which are instances of Object) are introduced to improve readability. The syntax is as follows: methodname(parametername : ParameterType) : ReturnType.
Pseudo-types
Sound
The metaudio Sound object is the primary object a metaudio Player programmer wants to interact with.
PeakData
An object with attributes left and right, which are floating point numbers in between 0.0 and 1.0, indicating the peak volume over all frequencies for the left and right channel, respectively. The peak volume is calculated as the maximum value of the amplitudes in the FFT frequency spectrum per channel. When multiple sounds are playing simultaneously, the values apply to the mixed sound. The figure shows a possible visualization of peak data showing volume for left and right channels.
WaveformData
An object with attributes left and right, which are 256-element arrays of waveform data sampled at 44.1 kHz. The data are floating point numbers between -1.0 and 1.0 inclusive, indicating sound amplitude at each point in time in a 256-element wide window. The figure illustrates a possible visualization of waveform data for a standard sound sine wave and music. The vertical middle of the diagrams corresponds to the value 0.0. The bottom two diagrams show the exact same sample but left and right channels (shown in black and blue) swapped.
Global object metaudio
Global object methods
init(swfurl : String) : void
Initializes the Flash player underlying metaudio Player and makes all other global methods available. init uses swfobject's embedSWF function to construct the HTML DOM object or embed element. Should the initialization fail, methods such as create, pauseAll or getWaveform will not be available. A typical usage is as follows:
<!-- include swfobject --> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script> <!-- include jQuery library for graphical user interface --> <script type="text/javascript" src="http://code.jquery.com/jquery-1.4.4.min.js"></script> <!-- include metaudio Player javascript file --> <script type="text/javascript" src="/assets/js/metaudio.js"></script> <!-- call metaudio Player's global init method passing path to SWF file --> <script type="text/javascript">metaudio.init("/assets/swf/metaudio.swf");</script>
create(attrs : Object) : Sound
Creates a new metaudio Sound object that has the specified attributes. The only mandatory attribute is url, which corresponds to the absolute or relative URL of the sound. Optional attributes include onload, onplay, onstop, onresume, onpause, onfinish, onseek, whileplaying and whileloading, all of which are function callbacks that take zero or one argument. The following example illustrates how to call this function:
var sound = metaudio.create({
url: 'demo.m4a',
usePeakData: true,
useWaveformData: false,
onplay: function () {
listitem.addClass('mp_playing');
},
onstop: function () {
listitem.removeClass('mp_playing mp_paused');
},
onpause: function () {
listitem.removeClass('mp_playing');
listitem.addClass('mp_paused');
},
onresume: function () {
listitem.removeClass('mp_paused');
listitem.addClass('mp_playing');
},
onfinish: function () {
listitem.removeClass('mp_playing mp_paused');
}
});
pauseAllBut(url : String) : void
Pauses all sounds playing except the one specified
getPeak() : PeakData
Retrieves peak data for all sounds currently playing.
getWaveform() : WaveformData
Retrieves waveform data for all sounds currently playing.
savePeak() : void
Sets the peakData property of the global metaudio object.
saveWaveform() : void
Sets the waveformData property of the global metaudio object.
Global object private methods
poll() : void
Called periodically by the browser to update loading and playhead position status, and fire events whileloading and whileplaying.
Global object properties
Typically, these properties are updated by various global object methods and should not be manipulated directly.
player : Object
The HTML DOM object or embed element that constitutes the player implemented in Flash. The player has no visual interface but exposes several callback methods.
sounds : Object
An object container of metaudio Sound objects, indexed by URL.
peakData : PeakData
Set by the global method savePeakData.
waveformData : WaveformData
Set by the global method saveWaveformData.
Global object events
These events are called by the Flash player and are used internally by metaudio Player to trigger events specific to individual metaudio Sound objects. Instead of overwriting the callbacks for these events, pass user-defined callbacks to the metaudio Sound object when you create it.
- onload(url : String) : void
- onplay(url : String) : void
- onstop(url : String) : void
- onresume(url : String) : void
- onpause(url : String) : void
- onfinish(url : String) : void
- onseek(url : String, pos : int) : void
Sound object
Methods, properties and events associated with an instance of the metaudio Sound object type.
Sound object methods
play() : void
Starts playing the sound.
stop() : void
Stops playing the sound. Even though the buffer is cleared, data that has been retrieved could remain in the browser cache.
resume() : void
Resumes playing the sound provided it has been paused.
pause() : void
Pauses playing the sound provided it has been started.
getBytesTotal() : int
Returns the number of bytes the sound file consists of.
getBytesLoaded() : int
Returns the number of bytes that have been buffered, which is at most the number of bytes the sound file consists of.
getDuration() : int
Returns the total play time of the sound in milliseconds.
getPosition() : int
Returns the current playhead position within the sound in milliseconds.
setPosition(int) : void
Sets the current playhead position within the sound in milliseconds.
Sound object properties
url : String
The absolute or relative URL the object was initialized with.
loading : boolean
True if the sound is currently being buffered,
playing : boolean
True if the sound is currently playing (i.e. it has been started but not stopped or paused and has not finished yet).
Sound object events
By default, all these events are initialized to the JavaScript empty function:
function () { }
onload() : void
Fired when sufficient part of a sound has been loaded by the browser such that it can begin playing.
onplay() : void
Fired when the sound starts playing.
onstop(url : String) : void
Fired when the sound stops playing (usually in response to user interaction).
onresume(url : String) : void
Fired when a sound that has been paused resumes playing.
onpause(url : String) : void
Fired when a sound that has started playing is paused.
onfinish(url : String) : void
Fired when a sound that has been playing ends.
onseek(url : String, pos : int) : void
Fired when the playhead in re-positioned in a sound (usually in response to user interaction). The parameter pos contains the new position in milliseconds to seek to. (When seeking, the value returned by the method getPosition is not updated immediately in all cases, especially if playback is paused, the parameter pos helps tackle this situation.)
whileloading() : void
Fired periodically while the sound is loading. Useful to update a visual progress indicator.
whileplaying() : void
Fired periodically while the sound is playing. Useful to update a playhead position indicator.
Flash external interface callbacks
These callback methods are used in the communication between JavaScript and ActionScript 3 code. Normally, you do not need to call any of these methods directly. The prefix mp helps avoid clashes with various ActiveX methods like play when run within IE.
- mpCreate(url : String) : void
- mpPlay(url : String) : void
- mpPause(url : String) : void
- mpResume(url : String) : void
- mpStop(url : String) : void
- mpGetBytesTotal(url : String) : int
- mpGetBytesLoaded(url : String) : int
- mpGetDuration(url : String) : int
- mpGetPosition(url : String) : int
- mpSetPosition(url : String, pos : int) : void
- mpGetPeak() : PeakData
- mpGetWaveform() : WaveformData
Debug output
When debugging is enabled, the embedded Flash player triggers external interface calls to print status, informational, warning and error messages. The Flash player makes the following JavaScript calls for status report purposes:
- console.log
- console.info
- console.warn
- console.error
These methods cause various messages to appear in the browser error console (or Firebug's console), possibly accompanied by an icon (for info, warn and error).
Acknowledgement
metaudio player has been inspired by SoundManager2. Differences include ActionScript code rewritten to exploit new features available in Flash 10.1, a new ActionScript-to-JavaScript data transfer model, improved co-existence with the MooTools framework and the jQuery library, and a reference GUI implementation built with the jQuery library. In accordance, the CPU usage and network footprint of metaudio Player is less than that of SoundManager2.
Download
For the latest version of the player, check out the web folder for metaudio developer releases.