audio
namespace audio
Public Properties
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
enable() → {}
enable audio output
only useful if audio supported and previously disabled through
fade(sound_name: string, from: number, to: number, duration: number, id: number) → {}
Fade a currently playing sound between two volumee.
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() → {string}
returns the current track Id
Type | Description |
---|---|
string |
audio track name |
getVolume() → {number}
get the default global volume
Type | Description |
---|---|
number |
current volume value in Float [0.0 - 1.0] . |
hasAudio() → {boolean}
check if audio (HTML5 or WebAudio) is supported
Type | Description |
---|---|
boolean |
return true if audio (HTML5 or WebAudio) is supported |
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
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 |
Type | Description |
---|---|
boolean |
return true if the given audio format is supported |
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;
}
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") |
Type | Description |
---|---|
boolean |
Indicates whether audio initialization was successful |
load(sound: loader.Asset, onloadcb: Function, onerrorcb: Function, settings: Object) → {number}
Load an audio file
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) |
Type | Description |
---|---|
number |
the amount of asset loaded (always 1 if successfull) |
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");
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 |
muted() → {boolean}
Returns true if audio is muted globally.
Type | Description |
---|---|
boolean |
true if audio is muted globally |
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.
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. |
Type | Description |
---|---|
Array |
the current 3D spatial orientation: [x, y, z] |
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'
});
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 |
settings.coneOuterGain | string |
<optional> |
0 |
A parameter for directional audio sources, this is the gain outside of the |
settings.distanceModel | string |
<optional> |
"inverse" |
Determines algorithm used to reduce volume as audio moves away from listener. Can be |
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 |
settings.panningModel | string |
<optional> |
"HRTF" |
Determines which spatialization algorithm is used to position audio. Can be |
id | number |
<optional> |
the sound instance ID. If none is passed, all sounds in group will be changed. |
Type | Description |
---|---|
Object |
current panner attributes. |
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");
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. |
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);
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). |
Type | Description |
---|---|
number |
the sound instance ID. |
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");
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). |
Type | Description |
---|---|
number |
the sound instance ID. |
position(sound_name: string, x: Number, y: Number, z: Number, id: number) → {Array}
get or set the 3D spatial position for the specified sound.
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. |
Type | Description |
---|---|
Array |
the current 3D spatial position: [x, y, z] |
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);
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. |
Type | Description |
---|---|
number |
return the current playback rate (if no extra parameters were given) |
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);
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() → {}
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(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);
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. |
Type | Description |
---|---|
number |
return the current seek position (if no extra parameters were given) |
setVolume(volume: number) → {}
set the default global volume
Name | Type | Description |
---|---|---|
volume | number |
Float specifying volume (0.0 - 1.0 values accepted). |
stereo(sound_name: string, pan: number, id: number) → {number}
get or set the stereo panning for the specified sound.
me.audio.stereo("cling", -1);
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. |
Type | Description |
---|---|
number |
the current panning value |
stop(sound_name: string, id: number) → {}
stop the specified sound on all channels
me.audio.stop("cling");
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() → {}
stop the current audio track
// play a awesome music
me.audio.playTrack("awesome_music");
// stop the current music
me.audio.stopTrack();
unload(sound_name: string) → {boolean}
unload specified audio track to free memory
me.audio.unload("awesome_music");
Name | Type | Description |
---|---|---|
sound_name | string |
audio track name - case sensitive |
Type | Description |
---|---|
boolean |
true if unloaded |
unmute(sound_name: string, id: number) → {}
unmute the specified sound
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. |