Levente Hunyadi

metaudio Player: JavaScript sound player for mp3/m4a audio

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

Peak data visualizationAn 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

Three different spectrogramsAn 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.

Donations in EUR
Donations in USD