Skip to main content

Audio Player

buildfire.services.media.audioPlayer#

This is a service that lives on the app level. It is meant to allow plugins to play audio on the app without interruption from user navigation. It facilitates common audio controls listed below. Also maintains a playlist for the user to access not depending on a single plugin.

Requirements#

Widget#

Include audioPlayer.js file in widget header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../scripts/buildfire/buildfire.min.js"></script>
<script src="../../../scripts/buildfire/services/media/audioPlayer.js"></script>
</head>

Control#

Include audioPlayer.js file in control header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../../scripts/buildfire/buildfire.min.js"></script>
<script src="../../../../scripts/buildfire/services/media/audioPlayer.js"></script>
</head>

Full Example#

You can check out example implementation for audioPlayer at https://github.com/BuildFire/simpleBuildFireJSExamples/tree/master/exampleAudioPlayer

Methods#

play()
#

buildfire.services.media.audioPlayer.play(track)

Begins playing a track

buildfire.services.media.audioPlayer.play(
"http://free-loops.com/data/mp3/68/dd/35cc9e920eae0ddf7e110d7ce0af.mp3"
);

track#

Track can be multiple one of the types described in a table below

NameTypeRequiredDescriptionDefault
tracknull or undefinednoTries to resume the paused track if any
trackstringnoUrl of an audio file you want to play
tracknumbernoTries to find the track index from the playlist
trackobjectnoTrack object

Track#

NameTypeRequiredDescriptionDefault
titlestringnoTrack title
urlstringnoTrack url
imagestringnoTrack cover image
albumstringnoAlbum name
artiststringnoArtist name
startAtnumbernoStart playing from certain second
lastPositionnumbernoSecond where user was last at on current track. Can be used in combination with autoJumpToLastPosition setting

pause()
#

buildfire.services.media.audioPlayer.pause()

Pauses a current track

buildfire.services.media.audioPlayer.pause();

isPaused()
#

buildfire.services.media.audioPlayer.isPaused(callback)

Checks if audio is playing or not

buildfire.services.media.audioPlayer.isPaused((err, isPaused) => {
if (err) return console.err(err);
if (isPaused) {
console.log("Audio is paused");
} else {
console.log("Audio is playing");
}
});

callback(err, data)#

Callback function after something is done

NameTypeDescription
errstringerror string, null when operation is successfull
isPausedbooleanIndicates if audio is paused

skip()
#

buildfire.services.media.audioPlayer.skip(seconds)

Skips forward provided numbers of seconds

buildfire.services.media.audioPlayer.skip(5);

seconds#

NameTypeDescription
secondsnumberNumber of seconds to skip forward

next()
#

buildfire.services.media.audioPlayer.next()

Plays a next item on playlist

buildfire.services.media.audioPlayer.next();

previous()
#

buildfire.services.media.audioPlayer.previous()

Plays a previous item on playlist

buildfire.services.media.audioPlayer.previous();

loopTrack()
#

buildfire.services.media.audioPlayer.loopTrack()

Keeps playing a current track in loop

buildfire.services.media.audioPlayer.loopTrack();

getPlaylist()
#

buildfire.services.media.audioPlayer.getPlaylist(callback)

Gets the current playlist

buildfire.services.media.audioPlayer.getPlaylist((err, playlist) => {
if (err) return console.error(err);
console.log("Current playlist", playlist);
});

callback(err, playlist)#

Callback function after fetching the playlist

NameTypeDescription
errstringerror string, null when operation is successfull
playlistobjectCurrent playlist object

playlist#

NameTypeDescription
lastIndexnumberIndex of last track played, -1 if no items were played yet
track[object]Array of tracks in playlist. See track

addToPlaylist()
#

buildfire.services.media.audioPlayer.addToPlaylist(track)

Adds a track to playlist

buildfire.services.media.audioPlayer.addToPlaylist({
url: "http://free-loops.com/data/mp3/68/dd/35cc9e920eae0ddf7e110d7ce0af.mp3",
});

track#

See track


removeFromPlaylist()
#

buildfire.services.media.audioPlayer.removeFromPlaylist(index)

Removes a track from playlist

buildfire.services.media.audioPlayer.removeFromPlaylist(0);

index#

NameTypeRequiredDescriptionDefault
indexnumberyesIndex of track to be removed from playlist

getCurrentTrack()
#

buildfire.services.media.audioPlayer.getCurrentTrack(callback)

Gets a current track

buildfire.services.media.audioPlayer.getCurrentTrack((track) => {
console.log("Current track", track);
});

callback(track)#

Callback function after fetching current track

NameTypeDescription
trackobjectSee track

playlist#

NameTypeDescription
lastIndexnumberIndex of last track played, -1 if no items were played yet
track[object]Array of tracks in playlist

setTime()
#

buildfire.services.media.audioPlayer.setTime(seconds)

Sets the time to specific value on current track

buildfire.services.media.audioPlayer.setTime(30);

seconds#

NameTypeRequiredDescriptionDefault
secondsnumberyesNumber of seconds from beginning of track to go to

settings.get()
#

buildfire.services.media.audioPlayer.settings.get(callback)

Gets the audio player settings

buildfire.services.media.audioPlayer.settings.get((err, settings) => {
if (err) return console.err(err);
console.log(settings);
});

callback(err, settings)#

Callback function after settings are fetched

NameTypeDescription
errstringerror string, null when operation is successfull
settingsobjectSettings object

settings#

NameTypeDescription
autoJumpToLastPositionbooleanIf a track has lastPosition use it to start playing the audio from there
autoPlayNextbooleanOnce a track is finished playing go to the next track in the playlist and play it
isPlayingCurrentTrackbooleanIndicates if any track is currently playing
loopPlaylistbooleanOnce the end of the playlist has been reached start over again
shufflePlaylistbooleanShuffle the playlist
volumenumberCurrent audio volume level 0 - 1 representing percentage

settings.set()
#

buildfire.services.media.audioPlayer.settings.set(settings)

Sets the audio player settings

buildfire.services.media.audioPlayer.settings.set({
autoJumpToLastPosition: false,
autoPlayNext: true,
loopPlaylist: true,
shufflePlaylist: true,
});

settings#

NameTypeRequiredDescriptionDefault
autoJumpToLastPositionbooleannoIf a track has lastPosition use it to start playing the audio from therefalse
autoPlayNextbooleannoOnce a track is finished playing go to the next track in the playlist and play itfalse
loopPlaylistbooleannoOnce the end of the playlist has been reached start over againfalse
shufflePlaylistbooleannoShuffle the playlistfalse

Handlers#

onEvent()#

buildfire.services.media.audioPlayer.onEvent(callback)

Calls the callback after event occurs on audio player

buildfire.services.media.audioPlayer.onEvent((event) => {
console.log("Audio event occured", event);
});

callback#

Callback function to be called when event occurs

event#

NameTypeDescription
dataobjectAn object with data specific to current event. Some events don't have any so datawill be undefined
eventstringDescribing the event that occured. Can be play, pause, resume, next, previous, removeFromPlaylist, audioEnded, timeUpdate
event.data#
EventDescriptionData
playTriggered when a track plays.Object containing current track and index
pauseTriggered when a track is paused.undefined
resumeTriggered when a track is un-pausedundefined
nextTriggered when a next track playsObject containing next track
previousTriggered when a previous track playsObject containing previous track
removeFromPlaylistTriggered when track is removed from playlistObject containing newPlaylist which is a playlist without removed item
audioEndedTriggered when a track endsundefined
timeUpdateTriggered when a track time changesObject containing currentTime, duration and buffer