API.md

Classes

Utility

Contains various utility methods.

EventTarget

Provides methods to work with events.

Meant to be extended by other classes.

Audio

Links to the internal AudioContext and related objects.

Track ⇐ EventTarget

Provides audiotrack-specific methods.

Playlist ⇐ EventTarget

Provides playlist-specific methods.

WebAudioPlayer ⇐ EventTarget

The main, public class, providing general methods.

Typedefs

eventListener : function

Callback to execute on events.

The callback context is the object on which the addEventListener() method was called.

markerCallback : function

Callback to execute on time markers.

Utility

Contains various utility methods.

Kind: global class

• Utility
  • .audio ⇒ Audio
  • .player
  • .player ⇒ WebAudioPlayer
  • .getArrayBuffer(url) ⇒ Promise.<ArrayBuffer, Error>
  • .loadUrl(urls) ⇒ Promise.<AudioBuffer, Error>
  • .getUrlPromise(urls) ⇒ Promise.<AudioBuffer, Error> | undefined
  • .removeUrlPromise(urls)
  • .setUrlPromise(urls, promise)
  • .readStorage(key) ⇒ * | null | undefined
  • .updateStorage(key, value)

Utility.audio ⇒ Audio

Returns the Audio object.

Kind: static property of Utility
Returns: Audio - The Audio object.
Read only: true

Utility.player

Saves the WebAudioPlayer instance to a statically cached variable.

Kind: static property of Utility
Throws:

• TypeError If provided parameter is not a WebAudioPlayer instance.

Param	Type	Description
player	WebAudioPlayer	The WebAudioPlayer instance.

Utility.player ⇒ WebAudioPlayer

Returns the WebAudioPlayer instance.

Kind: static property of Utility
Returns: WebAudioPlayer - The WebAudioPlayer instance.

Utility.getArrayBuffer(url) ⇒ Promise.<ArrayBuffer, Error>

Makes an XMLHttpRequest to url to get an array buffer.

Kind: static method of Utility
Returns: Promise.<ArrayBuffer, Error> - The Promise object. Fulfill callback arguments:

• {ArrayBuffer} The ArrayBuffer object. Reject callback arguments:
• {Error} The Error object.

Param	Type	Description
url	string	URL to get.

Utility.loadUrl(urls) ⇒ Promise.<AudioBuffer, Error>

Loads the audio file by URL into buffer.

Kind: static method of Utility
Returns: Promise.<AudioBuffer, Error> - The Promise object. Fulfill callback arguments:

• {AudioBuffer} The AudioBuffer object containing raw audio data. Reject callback arguments:
• {Error} The Error object.

Param	Type	Description
urls	Array.<string>	An array of mirror URLs.

Utility.getUrlPromise(urls) ⇒ Promise.<AudioBuffer, Error> | undefined

Gets a promise about loading URLs.

Kind: static method of Utility
Returns: Promise.<AudioBuffer, Error> | undefined - The Promise object if one exists at least for one of given URLs. Fulfill callback arguments:

• {AudioBuffer} The AudioBuffer object containing raw audio data. Reject callback arguments:
• {Error} The Error object.

Param	Type	Description
urls	Array.<string>	An array of mirror URLs.

Utility.removeUrlPromise(urls)

Removes promises about loading URLs.

Kind: static method of Utility

Param	Type	Description
urls	Array.<string>	An array of mirror URLs.

Utility.setUrlPromise(urls, promise)

Saves the promise about loading URLs in temporary static cache.

Kind: static method of Utility

Param	Type	Description
urls	Array.<string>	An array of mirror URLs.
promise	Promise	The Promise object.

Utility.readStorage(key) ⇒ * | null | undefined

Reads data from the storage.

Kind: static method of Utility
Returns: * | null | undefined - Variable value if it exists in the storage, null if it doesn't, or undefined in case of undefined local storage.

Param	Type	Description
key	string	Variable key.

Utility.updateStorage(key, value)

Updates data in the storage.

Kind: static method of Utility

Param	Type	Description
key	string	Variable key.
value	*	Variable value.

EventTarget

Provides methods to work with events.

Meant to be extended by other classes.

Kind: global class

• EventTarget
  • new EventTarget()
  • .eventListeners : object
  • .addEventListener(type, callback)
  • .removeEventListener(type, callback)
  • .dispatchEvent(type, ...other_arguments)

new EventTarget()

Constructs an EventTarget object.

eventTarget.eventListeners : object

Contains event listeners.

Object keys are event types, and values are arrays of callbacks.

Kind: instance property of EventTarget

eventTarget.addEventListener(type, callback)

Registers an event handler of a specific type.

Kind: instance method of EventTarget

Param	Type	Description
type	string	Event type to listen for.
callback	eventListener	Event handler to call when event occurs.

eventTarget.removeEventListener(type, callback)

Removes an event listener.

Kind: instance method of EventTarget

Param	Type	Description
type	string	Event type.
callback	eventListener	Event handler to remove.

eventTarget.dispatchEvent(type, ...other_arguments)

Dispatches an event.

Kind: instance method of EventTarget

Param	Type	Description
type	string	Event type to dispatch.
...other_arguments	*	Other arguments to supply to event listeners.

Audio

Links to the internal AudioContext and related objects.

Kind: global class

• Audio
  • new Audio()
  • .Context : AudioContext
  • .OfflineContext : OfflineAudioContext
  • .Analyser : AnalyserNode
  • .Gain : GainNode
  • .ScriptProcessor : ScriptProcessorNode
  • .filters : Array.<BiquadFilterNode>

new Audio()

Constructs an Audio object.

audio.Context : AudioContext

The AudioContext object.

Kind: instance property of Audio

audio.OfflineContext : OfflineAudioContext

The OfflineAudioContext object.

Kind: instance property of Audio

audio.Analyser : AnalyserNode

The AnalyserNode object.

Kind: instance property of Audio

audio.Gain : GainNode

The GainNode object.

Kind: instance property of Audio

audio.ScriptProcessor : ScriptProcessorNode

The ScriptProcessorNode object.

Kind: instance property of Audio

audio.filters : Array.<BiquadFilterNode>

Array of BiquadFilterNode objects.

Kind: instance property of Audio

Track ⇐ EventTarget

Provides audiotrack-specific methods.

Kind: global class
Extends: EventTarget

• Track ⇐ EventTarget
  • new Track(urls)
  • .data : object
  • .eventListeners : object
  • .load() ⇒ Promise.<Track, Error>
  • .play() ⇒ Track
  • .stop() ⇒ Track
  • .pause() ⇒ Track
  • .seek(newOffset) ⇒ Track
  • .when(marker, callback) ⇒ Track
  • .getCurrentTime() ⇒ number
  • .getPlayedTime() ⇒ number
  • .getDuration() ⇒ number
  • .isPlaying() ⇒ boolean
  • .addEventListener(type, callback)
  • .removeEventListener(type, callback)
  • .dispatchEvent(type, ...other_arguments)
  • "playing"
  • "finished"
  • "play"

new Track(urls)

Constructs a Track object.

Param	Type	Description
urls	Array.<string>	Track sources - an array of mirror URLs pointing to the same audio piece.

track.data : object

Provides a common place for any custom data associated with the track.

For example, track title, artist, etc.

Kind: instance property of Track

track.eventListeners : object

Contains event listeners.

Object keys are event types, and values are arrays of callbacks.

Kind: instance property of Track

track.load() ⇒ Promise.<Track, Error>

Loads the audio file into buffer.

Multiple calls to this method get the same Promise object.

Kind: instance method of Track
Returns: Promise.<Track, Error> - The Promise object. Fulfill callback arguments:

• {Track} This Track instance, loaded. Reject callback arguments:
• {Error} The Error object.
  

track.play() ⇒ Track

Plays the loaded audio file or resumes the playback from pause.

Kind: instance method of Track
Returns: Track - The Track object.
Throws:

• Error If track is not loaded.

Emits: play

track.stop() ⇒ Track

Stops the playback and resets the track state.

This method resets the current time position and the skipped time counter, which impacts the played time in the way that next play() will count it from 0.

Kind: instance method of Track
Returns: Track - The Track object.

track.pause() ⇒ Track

Pauses the playback.

Kind: instance method of Track
Returns: Track - The Track object.

track.seek(newOffset) ⇒ Track

Seeks on an audio track.

Kind: instance method of Track
Returns: Track - The Track object.
Throws:

• TypeError If provided offset is negative.

Param	Type	Description
newOffset	number	Seconds from the start of an audio file.

track.when(marker, callback) ⇒ Track

Sets the callback to execute on a time marker.

This method uses the actual played time. It means that markers cannot be accidentally skipped if a listener skips track parts.

Kind: instance method of Track
Returns: Track - The Track object.
Throws:

• TypeError If marker is negative.

See: getPlayedTime

Param	Type	Description
marker	number	A time marker in seconds of actual playback.
callback	markerCallback	A callback to execute when marker is reached.

track.getCurrentTime() ⇒ number

Gets the current playback position.

Kind: instance method of Track
Returns: number - Seconds from the start of an audio file.

track.getPlayedTime() ⇒ number

Gets the time the track was actually played.

Kind: instance method of Track
Returns: number - Seconds from the first play() of a track, excluding pauses and skips.

track.getDuration() ⇒ number

Gets the duration of a track.

Kind: instance method of Track
Returns: number - The duration in seconds.
Throws:

• Error If track is not loaded.

track.isPlaying() ⇒ boolean

Indicates whether a track is currently playing.

Kind: instance method of Track
Returns: boolean - True if audio is playing, false otherwise.

track.addEventListener(type, callback)

Registers an event handler of a specific type.

Kind: instance method of Track

Param	Type	Description
type	string	Event type to listen for.
callback	eventListener	Event handler to call when event occurs.

track.removeEventListener(type, callback)

Removes an event listener.

Kind: instance method of Track

Param	Type	Description
type	string	Event type.
callback	eventListener	Event handler to remove.

track.dispatchEvent(type, ...other_arguments)

Dispatches an event.

Kind: instance method of Track

Param	Type	Description
type	string	Event type to dispatch.
...other_arguments	*	Other arguments to supply to event listeners.

"playing"

Indicates that the track is playing.

Unlike the 'play' event, this one is fired constantly during the playback of the Track.

Kind: event emitted by Track
See: play

"finished"

Indicates that the track has finished playing.

Kind: event emitted by Track

"play"

Indicates the playback beginning.

Unlike the 'playing' event, this one is fired only when the track source has started playing, but not necessary from the start of an audio track.

Kind: event emitted by Track
See: playing

Playlist ⇐ EventTarget

Provides playlist-specific methods.

Kind: global class
Extends: EventTarget

• Playlist ⇐ EventTarget
  • new Playlist(list)
  • .list : Array.<Track>
  • .repeat : boolean
  • .length ⇒ number
  • .eventListeners : object
  • .setCurrentByIndex(index) ⇒ Playlist
  • .getCurrent() ⇒ Track | null
  • .getCurrentIndex() ⇒ number
  • .get(index) ⇒ Track | null | undefined
  • .load(index) ⇒ Promise.<Track, Error>
  • .play(index) ⇒ Playlist
  • .pause() ⇒ Playlist
  • .previous() ⇒ Playlist
  • .next() ⇒ Playlist
  • .isPlaying() ⇒ boolean
  • .shuffle() ⇒ Playlist
  • .push(...tracks) ⇒ Playlist
  • .addEventListener(type, callback)
  • .removeEventListener(type, callback)
  • .dispatchEvent(type, ...other_arguments)
  • "trackReady" (track)

new Playlist(list)

Constructs a Playlist object.

Param	Type	Description
list	Array.<Track>	(optional) Array of Track instances.

playlist.list : Array.<Track>

List of tracks to play.

Kind: instance property of Playlist

playlist.repeat : boolean

Indicates whether the list is on repeat.

Kind: instance property of Playlist

playlist.length ⇒ number

Returns the number of tracks in the list.

Kind: instance property of Playlist
Returns: number - Number of tracks in the list.
Read only: true

playlist.eventListeners : object

Contains event listeners.

Object keys are event types, and values are arrays of callbacks.

Kind: instance property of Playlist

playlist.setCurrentByIndex(index) ⇒ Playlist

Sets current track by its list index.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.
Throws:

• Error If current track is playing or if there's no track with given index in the list.

Param	Type	Description
index	number	Index of a track in list.

playlist.getCurrent() ⇒ Track | null

Returns the current track.

Kind: instance method of Playlist
Returns: Track | null - The current track, or null in case of empty list.

playlist.getCurrentIndex() ⇒ number

Returns the list index of current track.

Kind: instance method of Playlist
Returns: number - Current track's index, or -1 in case of empty list or if the current track was removed from the list.

playlist.get(index) ⇒ Track | null | undefined

Returns the track by index or the current one.

Kind: instance method of Playlist
Returns: Track | null | undefined - Either track corresponding to given index, or the current one. Null or undefined, if there's no corresponding track in the list.

Param	Type	Default	Description
index	number | null		(optional) The list index. If omitted, the current track will be looked for. If specified, and playlist is on repeat, then it will be adjusted to the range.

playlist.load(index) ⇒ Promise.<Track, Error>

Loads the track by index or the current one.

If track can't be loaded this method will try next tracks from the list recursively.

Kind: instance method of Playlist
Returns: Promise.<Track, Error> - The Promise object. Fulfill callback arguments:

• {Track} The Track instance, loaded. Reject callback arguments:
• {Error} The Error object.
  Emits: trackReady

Param	Type	Default	Description
index	number | null		(optional) The list index. If omitted, the current track will be loaded.

playlist.play(index) ⇒ Playlist

Plays the loaded track by index or the current one.

If track is on pause this method will resume the playback from track's current position. If track is finished it will play from the start.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.
Throws:

• Error If there's no corresponding track in the list.

Param	Type	Default	Description
index	number | null		(optional) The list index. If omitted, the current track will be played.

playlist.pause() ⇒ Playlist

Pauses the playback of current track.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.

playlist.previous() ⇒ Playlist

Skips to the start of previous track in the list, if one exists.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.
Throws:

• Error If list is empty or if the current track was removed from the list.

playlist.next() ⇒ Playlist

Skips to the start of next track in the list, if one exists.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.
Throws:

• Error If list is empty or if the current track was removed from the list.

playlist.isPlaying() ⇒ boolean

Indicates whether a current track is currently playing.

Kind: instance method of Playlist
Returns: boolean - True if audio is playing, false otherwise.

playlist.shuffle() ⇒ Playlist

Shuffles the list.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.

playlist.push(...tracks) ⇒ Playlist

Adds one or more tracks to the end of the list.

Kind: instance method of Playlist
Returns: Playlist - This Playlist instance.

Param	Type	Description
...tracks	Track	Track instances to add.

playlist.addEventListener(type, callback)

Registers an event handler of a specific type.

Kind: instance method of Playlist

Param	Type	Description
type	string	Event type to listen for.
callback	eventListener	Event handler to call when event occurs.

playlist.removeEventListener(type, callback)

Removes an event listener.

Kind: instance method of Playlist

Param	Type	Description
type	string	Event type.
callback	eventListener	Event handler to remove.

playlist.dispatchEvent(type, ...other_arguments)

Dispatches an event.

Kind: instance method of Playlist

Param	Type	Description
type	string	Event type to dispatch.
...other_arguments	*	Other arguments to supply to event listeners.

"trackReady" (track)

Indicates that the track from the list is loaded.

Kind: event emitted by Playlist

Param	Type	Description
track	Track	Instance of the loaded track.

WebAudioPlayer ⇐ EventTarget

The main, public class, providing general methods.

Kind: global class
Extends: EventTarget

• WebAudioPlayer ⇐ EventTarget
  • new WebAudioPlayer()
  • .eventListeners : object
  • .getAudio() ⇒ Audio
  • .createTrack(urls) ⇒ Track
  • .createPlaylist(list) ⇒ Playlist
  • .setVolume(gain) ⇒ WebAudioPlayer
  • .getVolume() ⇒ number
  • .setEq(bands) ⇒ WebAudioPlayer
  • .getEq() ⇒ Array.<number>
  • .addEventListener(type, callback)
  • .removeEventListener(type, callback)
  • .dispatchEvent(type, ...other_arguments)
  • "audioprocess"

new WebAudioPlayer()

Constructs a WebAudioPlayer object.

webAudioPlayer.eventListeners : object

Contains event listeners.

Object keys are event types, and values are arrays of callbacks.

Kind: instance property of WebAudioPlayer

webAudioPlayer.getAudio() ⇒ Audio

Returns the Audio object.

Kind: instance method of WebAudioPlayer
Returns: Audio - The Audio object.

webAudioPlayer.createTrack(urls) ⇒ Track

Returns the new Track instance.

Kind: instance method of WebAudioPlayer
Returns: Track - The Track instance.

Param	Type	Description
urls	Array.<string>	Track sources - an array of mirror URLs pointing to the same audio piece. Only the first valid URL will be ultimately used.

webAudioPlayer.createPlaylist(list) ⇒ Playlist

Returns the new Playlist instance.

Kind: instance method of WebAudioPlayer
Returns: Playlist - The Playlist instance.

Param	Type	Description
list	Array.<Track>	(optional) Array of Track instances.

webAudioPlayer.setVolume(gain) ⇒ WebAudioPlayer

Sets the playback volume to new level.

Kind: instance method of WebAudioPlayer
Returns: WebAudioPlayer - The WebAudioPlayer object.

Param	Type	Description
gain	number	Number between 0 and 1.

webAudioPlayer.getVolume() ⇒ number

Gets the current value of the playback volume level.

Kind: instance method of WebAudioPlayer
Returns: number - Previously set value.

webAudioPlayer.setEq(bands) ⇒ WebAudioPlayer

Sets the equalizer bands to new levels.

Kind: instance method of WebAudioPlayer
Returns: WebAudioPlayer - The WebAudioPlayer object.

Param	Type	Description
bands	Array.<number> | object	Array or object which keys are indexes from 0 to 9 for each of 10 bands, and values are numbers indicating the new gain of the corresponding band. All elements of the object are optional, so setting less than 10 elements will leave unspecified bands in previous state.

webAudioPlayer.getEq() ⇒ Array.<number>

Gets the current band levels of the equalizer.

Kind: instance method of WebAudioPlayer
Returns: Array.<number> - Array of 10 numbers.

webAudioPlayer.addEventListener(type, callback)

Registers an event handler of a specific type.

Kind: instance method of WebAudioPlayer

Param	Type	Description
type	string	Event type to listen for.
callback	eventListener	Event handler to call when event occurs.

webAudioPlayer.removeEventListener(type, callback)

Removes an event listener.

Kind: instance method of WebAudioPlayer

Param	Type	Description
type	string	Event type.
callback	eventListener	Event handler to remove.

webAudioPlayer.dispatchEvent(type, ...other_arguments)

Dispatches an event.

Kind: instance method of WebAudioPlayer

Param	Type	Description
type	string	Event type to dispatch.
...other_arguments	*	Other arguments to supply to event listeners.

"audioprocess"

Indicates that audio is processing.

This event is fired constantly during the life of an Audio object and should not be generally listened for. Track objects use this event to fire their own 'playing' event to indicate when the corresponding track is actually playing.

Kind: event emitted by WebAudioPlayer
See: playing

eventListener : function

Callback to execute on events.

The callback context is the object on which the addEventListener() method was called.

Kind: global typedef
this: EventTarget
See: dispatchEvent

Param	Type	Description
...arguments	*	Any number of arguments supplied to the dispatchEvent() method (except its first argument - event type).

markerCallback : function

Callback to execute on time markers.

Kind: global typedef
this: Track
See: when