Class PreciseAudio

An audio player that can seek and provide timestamps with millisecond accuracy. In contrast to the <audio> tag, this class will load an entire track into memory as a raw waveform, as otherwise, with most codecs, it's impossible to seek to accurate locations in songs.

ExampleUsage:

import PreciseAudio from '@synesthesia-project/precise-audio';

const audio = new PreciseAudio();
audio.loadAudioFile(...);

Motivation, more usage instructions, and other details can be found in the project GitHub repository

Package: @synesthesia-project/precise-audio

Properties

adjustPitchWithPlaybackRate

Should this class attempt to adjust the pitch of the audio when changing playback rate to compensate. This is the usual behaviour for HTMLAudioElement

Declaration

boolean adjustPitchWithPlaybackRate

Property Value

Type	Description
boolean

currentTime

The current playback time in seconds If the media is not yet playing, the value of currentTime indicates the time position within the track at which playback will begin once the play(boolean) method is called.

Declaration

number currentTime

Property Value

Type	Description
number	The current playback time in seconds

currentTimeMillis

Similar to currentTime, but returns the time in milliseconds rather than seconds.

Declaration

number currentTimeMillis

Property Value

Type	Description
number	The current playback time in milliseconds

defaultPlaybackRate

The value used as the playbackRate whenever new music is queued.

Declaration

number defaultPlaybackRate

Property Value

Type	Description
number	A number indicating the default playback rate

duration

Declaration

number duration

Property Value

Type	Description
number	The length of the currently loaded audio track in seconds

durationMillis

Declaration

number durationMillis

Property Value

Type	Description
number	The length of the currently loaded audio track in milliseconds

EventTarget

Declaration

static EventTarget: Object

Property Value

Type	Description
Object

muted

Declaration

boolean muted

Property Value

Type	Description
boolean	A Boolean that determines whether audio is muted. true if the audio is muted and false otherwise.

paused

Declaration

boolean paused

Property Value

Type	Description
boolean	a boolean that indicates whether the audio element is paused.

playbackRate

A number indicating the rate at which the media is being played back. This value is reset to be the same as defaultPlaybackRate whenever the queue of tracks is completely replaced (i.e, when the current track is changed).

Declaration

number playbackRate

Property Value

Type	Description
number	The number indicating the rate at which the media is being played back.

src

Declaration

string src

Property Value

Type	Description
string	the URL of the track to play

thresholds

Configuration options for different thresholds for gapless playback, this property can't be reassigned, but the properties of the object it returns can be.

Declaration

Thresholds thresholds

Property Value

Type	Description
Thresholds

volume

Declaration

number volume

Property Value

Type	Description
number	a double indicating the audio volume, from 0.0 (silent) to 1.0 (loudest).

Methods

addEventListener("canplay", Listener)

Fired when the user agent can play the media, and estimates that enough data has been loaded to play the media up to its end without having to stop for further buffering of content. Note: in contrast to HTMLAudioElement, PreciseAudio will always fire this event at the same time as canplaythrough and loadeddata, as all tracks are always fully preloaded.

Declaration

function addEventListener(event: "canplay", listener: Listener)

Parameters

Type	Name	Description
"canplay"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("canplaythrough", Listener)

Fired when the user agent can play the media, and estimates that enough data has been loaded to play the media up to its end without having to stop for further buffering of content. Note: in contrast to HTMLAudioElement, PreciseAudio will always fire this event at the same time as canplay and loadeddata, as all tracks are always fully preloaded.

Declaration

function addEventListener(event: "canplaythrough", listener: Listener)

Parameters

Type	Name	Description
"canplaythrough"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("ended", Listener)

Fired when playback stops when end of the track is reached

Declaration

function addEventListener(event: "ended", listener: Listener)

Parameters

Type	Name	Description
"ended"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("error", ErrorListener)

Fired when the track could not be loaded due to an error.

Declaration

function addEventListener(event: "error", listener: ErrorListener)

Parameters

Type	Name	Description
"error"	event
ErrorListener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("loadeddata", Listener)

Fired when the first frame of the media has finished loading. Note: in contrast to HTMLAudioElement, PreciseAudio will always fire this event at the same time as canplay and canplaythrough, as all tracks are always fully preloaded.

Declaration

function addEventListener(event: "loadeddata", listener: Listener)

Parameters

Type	Name	Description
"loadeddata"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("next", Listener)

Fired when the the next song has started playing (gaplessly).

Declaration

function addEventListener(event: "next", listener: Listener)

Parameters

Type	Name	Description
"next"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("pause", Listener)

Fired when the audio is paused (Notably not fired when the audio is stopped when a new file is being loaded)

Declaration

function addEventListener(event: "pause", listener: Listener)

Parameters

Type	Name	Description
"pause"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("play", Listener)

Fired when the audio starts playing

Declaration

function addEventListener(event: "play", listener: Listener)

Parameters

Type	Name	Description
"play"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("seeked", Listener)

Fired when a seek operation completes

Declaration

function addEventListener(event: "seeked", listener: Listener)

Parameters

Type	Name	Description
"seeked"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("timeupdate", Listener)

Fired when the time indicated by the currentTime attribute has been updated Note: this happens continuously, so instead this class will just call this at the framerate of the browser using requestAnimationFrame.

Declaration

function addEventListener(event: "timeupdate", listener: Listener)

Parameters

Type	Name	Description
"timeupdate"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("trackstateupdate", Listener)

Fired when the state of any of the enqueued tracks has changed. I.E: called whenever the returned value from trackStatuses() will be different.

Declaration

function addEventListener(event: "trackstateupdate", listener: Listener)

Parameters

Type	Name	Description
"trackstateupdate"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

addEventListener("volumechange", Listener)

Fired when the volume has changed.

Declaration

function addEventListener(event: "volumechange", listener: Listener)

Parameters

Type	Name	Description
"volumechange"	event
Listener	listener	an EventListener that expects a PreciseAudioEvent as a parameter

dispatchEvent(Event)

Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

Declaration

function dispatchEvent(event: Event)

Parameters

Type	Name	Description
Event	event

Returns

Type	Description
boolean

getAudioNodes()

Retreive the AudioContext and some of the internal audio nodes that are being used by the class, to allow for modification of the audio-processing graph, for example to add an equalizer or attach an analyser for visualizations. By default, the input returned is directly connected to output.

Declaration

function getAudioNodes()

Returns

Type	Description
AudioNodes

pause(boolean)

Pauses the audio playback.

Declaration

function pause(suppressEvent?: boolean)

Parameters

Type	Name	Description
boolean	suppressEvent

play(boolean)

Begin playback of the audio.

Declaration

function play(suppressEvent?: boolean)

Parameters

Type	Name	Description
boolean	suppressEvent

Returns

Type	Description
Promise<any>

removeEventListener(EventTypes, Listener | ErrorListener)

Declaration

function removeEventListener(event: EventTypes, listener: Listener | ErrorListener)

Parameters

Type	Name	Description
EventTypes	event
Listener | ErrorListener	listener

setSinkId(string)

Sets the ID of the audio device to use for output and returns a Promise. This only works when the application is authorized to use the specified device. Note: this is currently not implemented in PreciseAudio

Declaration

function setSinkId(sinkId: string)

Parameters

Type	Name	Description
string	sinkId	The MediaDeviceInfo.deviceId of the audio output device.

Returns

Type	Description
Promise<void>

skip(number)

Skip a certain number of tracks ahead in the queue

Declaration

function skip(count: number)

Parameters

Type	Name	Description
number	count	how many tracks to skip ahead by, default: 1

tracks()

Get the list of tracks, including the currently playing track and all tracks that are queued up to play afterward.

Declaration

function tracks()

Returns

Type	Description
Array<File | Blob | string>

trackStates()

Get the download and decode status of every track that is to be played, including the current one.

Declaration

function trackStates()

Returns

Type	Description
Object & Object | Object & Object | Object & Object | Object & Object | Object & Object[]

updateTracks(Array<File | Blob | string>)

Change the currently playing track, and the list of tracks that will play afterward.

Declaration

function updateTracks(tracks: Array<File | Blob | string>)

Parameters

Type	Name	Description
Array<File | Blob | string>	tracks

updateUpcomingTracks(Array<File | Blob | string>)

Update the list of songs that will play after the current song.

Declaration

function updateUpcomingTracks(followingSongs: Array<File | Blob | string>)

Parameters

Type	Name	Description
Array<File | Blob | string>	followingSongs