audio

namespace audio

Summary


Properties from audio

Public Properties


stopOnAudioError audio.js:64
stopOnAudioError: boolean = true

boolean

Specify either to stop on audio loading error or not
if true, melonJS will throw an exception and stop loading
if false, melonJS will disable sounds and output a warning message in the console

Public Methods


disable audio.js:128
disable() → {}

disable audio output

enable audio.js:118
enable() → {}

enable audio output
only useful if audio supported and previously disabled through

See: audio.disable
fade audio.js:220
fade(sound_name: string, from: number, to: number, duration: number, id: number) → {}

Fade a currently playing sound between two volumee.

Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

from number

Volume to fade from (0.0 to 1.0).

to number

Volume to fade to (0.0 to 1.0).

duration number

Time in milliseconds to fade.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will fade.

getCurrentTrack audio.js:505
getCurrentTrack() → {string}

returns the current track Id

Returns:
Type Description
string

audio track name

getVolume audio.js:523
getVolume() → {number}

get the default global volume

Returns:
Type Description
number

current volume value in Float [0.0 - 1.0] .

hasAudio audio.js:109
hasAudio() → {boolean}

check if audio (HTML5 or WebAudio) is supported

Returns:
Type Description
boolean

return true if audio (HTML5 or WebAudio) is supported

hasFormat audio.js:99
hasFormat(codec: "mp3" | "mpeg" | "opus" | "ogg" | "oga" | "wav" | "aac" | "caf" | "m4a" | "m4b" | "mp4" | "weba" | "webm" | "dolby" | "flac") → {boolean}

check if the given audio format is supported

Parameters:
Name Type Description
codec "mp3" | "mpeg" | "opus" | "ogg" | "oga" | "wav" | "aac" | "caf" | "m4a" | "m4b" | "mp4" | "weba" | "webm" | "dolby" | "flac"

the audio format to check for support

Returns:
Type Description
boolean

return true if the given audio format is supported

init audio.js:75
init(format: string) → {boolean}

Initialize and configure the audio support.
For a maximum browser coverage the recommendation is to use at least two of them, typically default to webm and then fallback to mp3 for the best balance of small filesize and high quality, webm has nearly full browser coverage with a great combination of compression and quality, and mp3 will fallback gracefully for other browsers. It is important to remember that melonJS selects the first compatible sound based on the list of extensions and given order passed here. So if you want webm to be used before mp3, you need to put the audio format in that order.

// initialize the "sound engine", giving "webm" as default desired audio format, and "mp3" as a fallback
if (!me.audio.init("webm,mp3")) {
    alert("Sorry but your browser does not support html 5 audio !");
    return;
}
Parameters:
Name Type Attributes Default Description
format string

<optional>

"mp3"

audio format to prioritize ("mp3"|"mpeg"|"opus"|"ogg"|"oga"|"wav"|"aac"|"caf"|"m4a"|"m4b"|"mp4"|"weba"|"webm"|"dolby"|"flac")

Returns:
Type Description
boolean

Indicates whether audio initialization was successful

load audio.js:136
load(sound: loader.Asset, onloadcb: Function, onerrorcb: Function, settings: Object) → {number}

Load an audio file

Parameters:
Name Type Attributes Description
sound loader.Asset
onloadcb Function

<optional>

function to be called when the resource is loaded

onerrorcb Function

<optional>

function to be called in case of error

settings Object

<optional>

custom settings to apply to the request (@link https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)

Returns:
Type Description
number

the amount of asset loaded (always 1 if successfull)

mute audio.js:532
mute(sound_name: string, id: number, mute: boolean) → {}

mute or unmute the specified sound, but does not pause the playback.

// mute the background music
me.audio.mute("awesome_music");
Parameters:
Name Type Attributes Default Description
sound_name string

audio clip name - case sensitive

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will mute.

mute boolean

<optional>

true

True to mute and false to unmute

muteAll audio.js:561
muteAll() → {}

mute all audio

muted audio.js:577
muted() → {boolean}

Returns true if audio is muted globally.

Returns:
Type Description
boolean

true if audio is muted globally

orientation audio.js:320
orientation(sound_name: string, x: Number, y: Number, z: Number, id: number) → {Array}

Get/set the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on how direction the sound is, based on the cone attributes, a sound pointing away from the listener can be quiet or silent.

Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

x Number

the x-orientation of the audio source.

y Number

the y-orientation of the audio source.

z Number

the z-orientation of the audio source.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will be changed.

Returns:
Type Description
Array

the current 3D spatial orientation: [x, y, z]

panner audio.js:340
panner(sound_name: string, attribute: object, id: number) → {Object}

get or set the panner node's attributes for a sound or group of sounds. See https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics#creating_a_panner_node

me.audio.panner("cling", {
   panningModel: 'HRTF',
   refDistance: 0.8,
   rolloffFactor: 2.5,
   distanceModel: 'exponential'
});
Parameters:
Name Type Attributes Default Description
sound_name string

audio clip name - case sensitive

attribute object

<optional>

the panner attributes to set

settings.coneInnerAngle string

<optional>

360

A parameter for directional audio sources, this is an angle, in degrees, inside of which there will be no volume reduction.

settings.coneOuterAngle string

<optional>

360

A parameter for directional audio sources, this is an angle, in degrees, outside of which the volume will be reduced to a constant value of coneOuterGain.

settings.coneOuterGain string

<optional>

0

A parameter for directional audio sources, this is the gain outside of the coneOuterAngle. It is a linear value in the range [0, 1].

settings.distanceModel string

<optional>

"inverse"

Determines algorithm used to reduce volume as audio moves away from listener. Can be linear, inverse or `exponential.

settings.maxDistance string

<optional>

10000

The maximum distance between source and listener, after which the volume will not be reduced any further.

settings.refDistance string

<optional>

1

A reference distance for reducing volume as source moves further from the listener. This is simply a variable of the distance model and has a different effect depending on which model is used and the scale of your coordinates. Generally, volume will be equal to 1 at this distance.

settings.rolloffFactor string

<optional>

1

How quickly the volume reduces as source moves from listener. This is simply a variable of the distance model and can be in the range of [0, 1] with linear and [0, ∞] with inverse and exponential.

settings.panningModel string

<optional>

"HRTF"

Determines which spatialization algorithm is used to position audio. Can be HRTF or equalpower.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will be changed.

Returns:
Type Description
Object

current panner attributes.

pause audio.js:396
pause(sound_name: string, id: number) → {}

pause the specified sound on all channels
this function does not reset the currentTime property

me.audio.pause("cling");
Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will pause.

pauseTrack audio.js:476
pauseTrack() → {}

pause the current audio track

me.audio.pauseTrack();
play audio.js:179
play(sound_name: string, loop: boolean, onend: Function, volume: number) → {number}

play the specified sound

// play the "cling" audio clip
me.audio.play("cling");
// play & repeat the "engine" audio clip
me.audio.play("engine", true);
// play the "gameover_sfx" audio clip and call myFunc when finished
me.audio.play("gameover_sfx", false, myFunc);
// play the "gameover_sfx" audio clip with a lower volume level
me.audio.play("gameover_sfx", false, null, 0.5);
Parameters:
Name Type Attributes Default Description
sound_name string

audio clip name - case sensitive

loop boolean

<optional>

false

loop audio

onend Function

<optional>

Function to call when sound instance ends playing.

volume number

<optional>

default

Float specifying volume (0.0 - 1.0 values accepted).

Returns:
Type Description
number

the sound instance ID.

playTrack audio.js:438
playTrack(sound_name: string, volume: number) → {number}

play the specified audio track
this function automatically set the loop property to true
and keep track of the current sound being played.

me.audio.playTrack("awesome_music");
Parameters:
Name Type Attributes Default Description
sound_name string

audio track name - case sensitive

volume number

<optional>

default

Float specifying volume (0.0 - 1.0 values accepted).

Returns:
Type Description
number

the sound instance ID.

position audio.js:301
position(sound_name: string, x: Number, y: Number, z: Number, id: number) → {Array}

get or set the 3D spatial position for the specified sound.

Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

x Number

the x-position of the audio source.

y Number

the y-position of the audio source.

z Number

the z-position of the audio source.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will be changed.

Returns:
Type Description
Array

the current 3D spatial position: [x, y, z]

rate audio.js:260
rate(sound_name: string, rate: number, id: number) → {number}

get or set the rate of playback for a sound.

// get the playback rate of the background music
let rate = me.audio.rate("dst-gameforest");
// speed up the playback of the background music
me.audio.rate("dst-gameforest", 2.0);
Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

rate number

<optional>

playback rate : 0.5 to 4.0, with 1.0 being normal speed.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will be changed.

Returns:
Type Description
number

return the current playback rate (if no extra parameters were given)

resume audio.js:414
resume(sound_name: string, id: number) → {}

resume the specified sound on all channels

// play a audio clip
let id = me.audio.play("myClip");
...
// pause it
me.audio.pause("myClip", id);
...
// resume
me.audio.resume("myClip", id);
Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will resume.

resumeTrack audio.js:488
resumeTrack() → {}

resume the previously paused audio track

// play an awesome music
me.audio.playTrack("awesome_music");
// pause the audio track
me.audio.pauseTrack();
// resume the music
me.audio.resumeTrack();
seek audio.js:238
seek(sound_name: string, seek: number, id: number) → {number}

get/set the position of playback for a sound.

// return the current position of the background music
let current_pos = me.audio.seek("dst-gameforest");
// set back the position of the background music to the beginning
me.audio.seek("dst-gameforest", 0);
Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

seek number

<optional>

the position to move current playback to (in seconds).

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will changed.

Returns:
Type Description
number

return the current seek position (if no extra parameters were given)

setVolume audio.js:514
setVolume(volume: number) → {}

set the default global volume

Parameters:
Name Type Description
volume number

Float specifying volume (0.0 - 1.0 values accepted).

stereo audio.js:282
stereo(sound_name: string, pan: number, id: number) → {number}

get or set the stereo panning for the specified sound.

me.audio.stereo("cling", -1);
Parameters:
Name Type Attributes Description
sound_name string

audio clip name - case sensitive

pan number

<optional>

the panning value - A value of -1.0 is all the way left and 1.0 is all the way right.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will be changed.

Returns:
Type Description
number

the current panning value

stop audio.js:373
stop(sound_name: string, id: number) → {}

stop the specified sound on all channels

me.audio.stop("cling");
Parameters:
Name Type Attributes Description
sound_name string

<optional>

audio clip name (case sensitive). If none is passed, all sounds are stopped.

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will stop.

stopTrack audio.js:459
stopTrack() → {}

stop the current audio track

// play a awesome music
me.audio.playTrack("awesome_music");
// stop the current music
me.audio.stopTrack();
See: audio.playTrack
unload audio.js:586
unload(sound_name: string) → {boolean}

unload specified audio track to free memory

me.audio.unload("awesome_music");
Parameters:
Name Type Description
sound_name string

audio track name - case sensitive

Returns:
Type Description
boolean

true if unloaded

unloadAll audio.js:605
unloadAll() → {}

unload all audio to free memory

me.audio.unloadAll();
unmute audio.js:551
unmute(sound_name: string, id: number) → {}

unmute the specified sound

Parameters:
Name Type Attributes Description
sound_name string

audio clip name

id number

<optional>

the sound instance ID. If none is passed, all sounds in group will unmute.

unmuteAll audio.js:569
unmuteAll() → {}

unmute all audio


Powered by webdoc!