`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

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

<head>
  <!-- ... -->
  <script src="../../../scripts/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.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

Name	Type	Required	Description
`track`	`null` or `undefined`	no	Tries to resume the paused track if any
`track`	string	no	Url of an audio file you want to play
`track`	number	no	Tries to find the track index from the playlist
`track`	object	no	`Track` object

`Track`

Name	Type	Required	Description
`title`	string	no	Track title
`url`	string	no	Track url
`image`	string	no	Track cover image
`album`	string	no	Album name
`artist`	string	no	Artist name
`startAt`	number	no	Start playing from certain second
`lastPosition`	number	no	Second 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

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`isPaused`	boolean	Indicates if audio is paused

`skip()`

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

Skips forward provided numbers of seconds

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

`seconds`

Name	Type	Description
`seconds`	number	Number 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();

`isTrackInPlaylist()`

buildfire.services.media.audioPlayer.isTrackInPlaylist(track, callback)

Indicates if the given track is currently added to the app's playlist

const { getCurrentTrack, isTrackInPlaylist } = buildfire.services.media.audioPlayer;

getCurrentTrack((track) => {
  isTrackInPlaylist(track, (err, result) => {
    if (err) return console.error(err);
    console.log(`isTrackInPlaylist -> ${result}`;
  });
});

note

Searching is based on track.url in the first place, this makes the url a mandatory property.

`track`

See track

`callback(err, result)`

Callback function

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`result`	boolean	Indicates if track is currently in playlist

`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

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`playlist`	object	Current playlist object

`playlist`

Name	Type	Description
`lastIndex`	number	Index 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`

Name	Type	Required	Description	Default
`index`	number	yes	Index 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

Name	Type	Description
`track`	object	See `track`

`playlist`

Name	Type	Description
`lastIndex`	number	Index 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`

Name	Type	Required	Description	Default
`seconds`	number	yes	Number 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

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`settings`	object	Settings object

`settings`

Name	Type	Description
`autoJumpToLastPosition`	boolean	If a track has `lastPosition` use it to start playing the audio from there
`autoPlayNext`	boolean	Once a track is finished playing go to the next track in the playlist and play it
`isPlayingCurrentTrack`	boolean	Indicates if any track is currently playing
`loopPlaylist`	boolean	Once the end of the playlist has been reached start over again
`shufflePlaylist`	boolean	Shuffle the playlist
`volume`	number	Current audio volume level `0` - `1` representing percentage
`playbackSpeed`	number	Configures the playback speed of the media. Acceptable values range from 0.5 to 4. A value of 1 represents normal playback speed

`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,
  playbackSpeed: 1,
});

`settings`

Name	Type	Required	Description	Default
`autoJumpToLastPosition`	boolean	no	If a track has `lastPosition` use it to start playing the audio from there	`false`
`autoPlayNext`	boolean	no	Once a track is finished playing go to the next track in the playlist and play it	`false`
`loopPlaylist`	boolean	no	Once the end of the playlist has been reached start over again	`false`
`shufflePlaylist`	boolean	no	Shuffle the playlist	`false`
`playbackSpeed`	number	no	Audio track playback speed rate	`1.0`

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`

Name	Type	Description
`event`	string	Name of event. Can be `play`, `pause`, `resume`, `next`, `previous`, `addToPlaylist`, `removeFromPlaylist`, `audioEnded`, `timeUpdate`
`data`	object	An object with data specific to current event. Some events don't have any so `data`will be `undefined`

`event.data`

Event	Description	Data
`play`	Triggered when a track plays	Object containing current `track` and `index` of playing track
`pause`	Triggered when a track is paused	`undefined`
`resume`	Triggered when a track is un-paused	`undefined`
`next`	Triggered when a next track plays	Object containing next `track`
`previous`	Triggered when a previous track plays	Object containing previous `track`
`addToPlaylist`	Triggered when a track is added to playlist	Object containing `newPlaylist` and the added `track`
`removeFromPlaylist`	Triggered when a track is removed from playlist	Object containing `newPlaylist` and the removed `track` along with its `index`
`audioEnded`	Triggered when a track ends	`undefined`
`timeUpdate`	Triggered when a track time changes	Object containing `currentTime`, `duration` and `buffer`
`error`	Triggered when an error occurs	Object containing `code` -if provided- which is the error code, `message` which is the error message

note

On iOS platforms, error handling is not always guaranteed as errors may be delayed, lack error codes, or fail to be triggered altogether.

buildfire.services.media.audioPlayer

Requirements​

Widget​

Control​

Full Example​

Methods​

play() ​

track​

Track​

pause() ​

isPaused() ​

callback(err, data)​

skip() ​

seconds​

next() ​

previous() ​

loopTrack() ​

isTrackInPlaylist() ​

track​

callback(err, result)​

getPlaylist() ​

callback(err, playlist)​

playlist​

addToPlaylist() ​

track​

removeFromPlaylist() ​

index​

getCurrentTrack() ​

callback(track)​

playlist​

setTime() ​

seconds​

settings.get() ​

callback(err, settings)​

settings​

settings.set() ​

settings​

Handlers​

onEvent()​

callback​

event​

event.data​

`buildfire.services.media.audioPlayer`

Requirements

Widget

Control

Full Example

Methods

`play()`

`track`

`Track`

`pause()`

`isPaused()`

`callback(err, data)`

`skip()`

`seconds`

`next()`

`previous()`

`loopTrack()`

`isTrackInPlaylist()`

`track`

`callback(err, result)`

`getPlaylist()`

`callback(err, playlist)`

`playlist`

`addToPlaylist()`

`track`

`removeFromPlaylist()`

`index`

`getCurrentTrack()`

`callback(track)`

`playlist`

`setTime()`

`seconds`

`settings.get()`

`callback(err, settings)`

`settings`

`settings.set()`

`settings`

Handlers

`onEvent()`

`callback`

`event`

`event.data`