Skip to content

Commit

Permalink
fix/clean audio doc tags
Browse files Browse the repository at this point in the history
  • Loading branch information
@obiot
obiot committed Mar 24, 2024
1 parent 0ab2945 commit 39be2d6
Showing 1 changed file with 34 additions and 33 deletions.
67 changes: 34 additions & 33 deletions src/audio/audio.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,6 @@ let soundLoadError = function (sound_name, onerror_cb) {
* if true, melonJS will throw an exception and stop loading<br>
* if false, melonJS will disable sounds and output a warning message
* in the console<br>
* @name stopOnAudioError
* @type {boolean}
* @default true
* @memberof audio
Expand All @@ -80,7 +79,7 @@ export let stopOnAudioError = true;
* 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.
* @function audio.init
* @memberof audio
* @param {string} [format="mp3"] - audio format to prioritize ("mp3"|"mpeg"|"opus"|"ogg"|"oga"|"wav"|"aac"|"caf"|"m4a"|"m4b"|"mp4"|"weba"|"webm"|"dolby"|"flac")
* @returns {boolean} Indicates whether audio initialization was successful
* @example
Expand All @@ -99,7 +98,7 @@ export function init(format = "mp3") {

/**
* check if the given audio format is supported
* @function audio.hasFormat
* @memberof audio
* @param {"mp3"|"mpeg"|"opus"|"ogg"|"oga"|"wav"|"aac"|"caf"|"m4a"|"m4b"|"mp4"|"weba"|"webm"|"dolby"|"flac"} codec - the audio format to check for support
* @returns {boolean} return true if the given audio format is supported
*/
Expand All @@ -109,7 +108,7 @@ export function hasFormat(codec) {

/**
* check if audio (HTML5 or WebAudio) is supported
* @function audio.hasAudio
* @memberof audio
* @returns {boolean} return true if audio (HTML5 or WebAudio) is supported
*/
export function hasAudio() {
Expand All @@ -119,7 +118,7 @@ export function hasAudio() {
/**
* enable audio output <br>
* only useful if audio supported and previously disabled through
* @function audio.enable
* @memberof audio
* @see audio.disable
*/
export function enable() {
Expand All @@ -128,15 +127,15 @@ export function enable() {

/**
* disable audio output
* @function audio.disable
* @memberof audio
*/
export function disable() {
muteAll();
}

/**
* Load an audio file
* @function audio.load
* @memberof audio
* @param {loader.Asset} sound
* @param {Function} [onloadcb] - function to be called when the resource is loaded
* @param {Function} [onerrorcb] - function to be called in case of error
Expand Down Expand Up @@ -179,7 +178,7 @@ export function load(sound, onloadcb, onerrorcb, settings = {}) {

/**
* play the specified sound
* @function audio.play
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {boolean} [loop=false] - loop audio
* @param {Function} [onend] - Function to call when sound instance ends playing.
Expand Down Expand Up @@ -220,7 +219,7 @@ export function play(sound_name, loop = false, onend, volume) {

/**
* Fade a currently playing sound between two volumee.
* @function audio.fade
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} from - Volume to fade from (0.0 to 1.0).
* @param {number} to - Volume to fade to (0.0 to 1.0).
Expand All @@ -238,7 +237,7 @@ export function fade(sound_name, from, to, duration, id) {

/**
* get/set the position of playback for a sound.
* @function audio.seek
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} [seek] - the position to move current playback to (in seconds).
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will changed.
Expand All @@ -260,7 +259,7 @@ export function seek(sound_name, ...args) {

/**
* get or set the rate of playback for a sound.
* @function audio.rate
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} [rate] - playback rate : 0.5 to 4.0, with 1.0 being normal speed.
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will be changed.
Expand All @@ -282,7 +281,7 @@ export function rate(sound_name, ...args) {

/**
* get or set the stereo panning for the specified sound.
* @function audio.stereo
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} [pan] - the panning value - A value of -1.0 is all the way left and 1.0 is all the way right.
* @return {number} the current panning value
Expand All @@ -299,8 +298,8 @@ export function stereo(sound_name, pan) {
}

/**
* get or set the 3D spatial position or the specified sound.
* @function audio.position
* get or set the 3D spatial position for the specified sound.
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {Number} x - the x-position of the audio source.
* @param {Number} y - the y-position of the audio source.
Expand All @@ -319,7 +318,7 @@ export function position(sound_name, x, y, z) {
/**
* 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.
* @function audio.orientation
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {Number} x - the x-orientation of the audio source.
* @param {Number} y - the y-orientation of the audio source.
Expand All @@ -337,7 +336,8 @@ export function orientation(sound_name, x, y, z) {

/**
* get or set the panner node's attributes for a sound or group of sounds.
* @function audio.panner
* See {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics#creating_a_panner_node}
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {object} [attribute] - the panner attributes to set
* @param {string} [settings.coneInnerAngle=360] - A parameter for directional audio sources, this is an angle, in degrees, inside of which there will be no volume reduction.
Expand All @@ -349,6 +349,7 @@ export function orientation(sound_name, x, y, z) {
* @param {string} [settings.rolloffFactor=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`.
* @param {string} [settings.panningModel="HRTF"] - Determines which spatialization algorithm is used to position audio. Can be `HRTF` or `equalpower`.
* @return {Object} current panner attributes.
* @example
* me.audio.panner("cling", {
* panningModel: 'HRTF',
* refDistance: 0.8,
Expand All @@ -367,7 +368,7 @@ export function panner(sound_name, attributes) {

/**
* stop the specified sound on all channels
* @function audio.stop
* @memberof audio
* @param {string} [sound_name] - audio clip name (case sensitive). If none is passed, all sounds are stopped.
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will stop.
* @example
Expand All @@ -391,7 +392,7 @@ export function stop(sound_name, id) {
/**
* pause the specified sound on all channels<br>
* this function does not reset the currentTime property
* @function audio.pause
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will pause.
* @example
Expand All @@ -408,7 +409,7 @@ export function pause(sound_name, id) {

/**
* resume the specified sound on all channels<br>
* @function audio.resume
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will resume.
* @example
Expand All @@ -434,7 +435,7 @@ export function resume(sound_name, id) {
* play the specified audio track<br>
* this function automatically set the loop property to true<br>
* and keep track of the current sound being played.
* @function audio.playTrack
* @memberof audio
* @param {string} sound_name - audio track name - case sensitive
* @param {number} [volume=default] - Float specifying volume (0.0 - 1.0 values accepted).
* @returns {number} the sound instance ID.
Expand All @@ -453,7 +454,7 @@ export function playTrack(sound_name, volume) {

/**
* stop the current audio track
* @function audio.stopTrack
* @memberof audio
* @see audio.playTrack
* @example
* // play a awesome music
Expand All @@ -470,7 +471,7 @@ export function stopTrack() {

/**
* pause the current audio track
* @function audio.pauseTrack
* @memberof audio
* @example
* me.audio.pauseTrack();
*/
Expand All @@ -482,7 +483,7 @@ export function pauseTrack() {

/**
* resume the previously paused audio track
* @function audio.resumeTrack
* @memberof audio
* @example
* // play an awesome music
* me.audio.playTrack("awesome_music");
Expand All @@ -499,7 +500,7 @@ export function resumeTrack() {

/**
* returns the current track Id
* @function audio.getCurrentTrack
* @memberof audio
* @returns {string} audio track name
*/
export function getCurrentTrack() {
Expand All @@ -508,7 +509,7 @@ export function getCurrentTrack() {

/**
* set the default global volume
* @function audio.setVolume
* @memberof audio
* @param {number} volume - Float specifying volume (0.0 - 1.0 values accepted).
*/
export function setVolume(volume) {
Expand All @@ -517,7 +518,7 @@ export function setVolume(volume) {

/**
* get the default global volume
* @function audio.getVolume
* @memberof audio
* @returns {number} current volume value in Float [0.0 - 1.0] .
*/
export function getVolume() {
Expand All @@ -526,7 +527,7 @@ export function getVolume() {

/**
* mute or unmute the specified sound, but does not pause the playback.
* @function audio.mute
* @memberof audio
* @param {string} sound_name - audio clip name - case sensitive
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will mute.
* @param {boolean} [mute=true] - True to mute and false to unmute
Expand All @@ -545,7 +546,7 @@ export function mute(sound_name, id, mute = true) {

/**
* unmute the specified sound
* @function audio.unmute
* @memberof audio
* @param {string} sound_name - audio clip name
* @param {number} [id] - the sound instance ID. If none is passed, all sounds in group will unmute.
*/
Expand All @@ -555,23 +556,23 @@ export function unmute(sound_name, id) {

/**
* mute all audio
* @function audio.muteAll
* @memberof audio
*/
export function muteAll() {
Howler.mute(true);
}

/**
* unmute all audio
* @function audio.unmuteAll
* @memberof audio
*/
export function unmuteAll() {
Howler.mute(false);
}

/**
* Returns true if audio is muted globally.
* @function audio.muted
* @memberof audio
* @returns {boolean} true if audio is muted globally
*/
export function muted() {
Expand All @@ -580,7 +581,7 @@ export function muted() {

/**
* unload specified audio track to free memory
* @function audio.unload
* @memberof audio
* @param {string} sound_name - audio track name - case sensitive
* @returns {boolean} true if unloaded
* @example
Expand All @@ -599,7 +600,7 @@ export function unload(sound_name) {

/**
* unload all audio to free memory
* @function audio.unloadAll
* @memberof audio
* @example
* me.audio.unloadAll();
*/
Expand Down

0 comments on commit 39be2d6

Please sign in to comment.