Playlist Player SDK (legacy)

This guide explains how to embed a custom playlist and custom-build a playlist player using our JavaScript Playlist Player SDK. You can choose any combination of audios from a project.

The JavaScript Playlist Player SDK is client-side JavaScript library that is separate from the API. You connect to it differently, and it gives you a different range of options.

Install

You can install the JavaScript Playlist Player and SDK through NPM:

npm install --save @beyondwords/audio-player

Or, you can also reference an up‐to‐date version on our CDN:

<script type="module">
import BeyondWords from 'https://proxy.beyondwords.io/npm/@beyondwords/audio-player@latest/dist/module/index.js';
</script>

Initialize

To initialize the JavaScript Playlist Player, use the following:

BeyondWords.player({
  // required parameters
  player: "PlaylistPlayer"
  projectId: "...", // number
  // One of the following parameters
  playlistId: "...", // number
  playlist: "...", // array of podcastId and/or playlistId
  // optional parameters
  renderNode: "...",
}).then((appInst) => {
  // Player is initialized
  // App instance provides access to methods & events (see below)
});

To intialize the JavaScript Playlist Player with the SDK, import the package:

import { BeyondWordsSdk } from '@beyondwords/audio-player';

Then use the following:

BeyondWordsSdk.player({
  // required parameters
  player: "PlaylistPlayer"
  projectId: "...", // number
  // One of the following parameters
  playlistId: "...", // number
  playlist: "...", // array of podcastId and/or playlistId
  // optional parameters
  renderNode: "...",
}).then((appInst) => {
  // Player is initialized
  // App instance provides access to methods & events (see below)
});

The Playlist Player SDK will now be available, and you will be able to use the JavaScript Playlist Player SDK.

Required parameters

Parameter	Type	Description
player	string	To use the Playlist Player set this to: PlaylistPlayer
projectId	integer (conditional)	Set the ProjectId to get the default Project Playlist with latest audios
playlistId	integer (conditional)	Set the PlaylistId to get a custom playlist
playlist	array (conditional)	Array of objects like { key: value } where key can be one of (podcastId | externalId | playlistId) The array should be sorted in the order that you wish the audios to appear in the playlist

Example for array of playlist with podcast ID's:

[
  { podcastId: '...' },
  { podcastId: '...' },
  ...
  { podcastId: '...' },
]

Example for array of playlist with podcast ID and Playlist ID:

[
  { podcastId: '...' },
  { playlistId: '...' }
]

Optional parameters

Parameter	Type	Description
renderNode	string	This is the ID of the container element. The default is set to beyondwords-player
UIEnabled	boolean	Set to false to use your own UI
publisherColor	string	Set the color of the Player icons and progress bar, e.g, #000000
publisherTextColor	string	Set the color of the Player text, e.g, #000000
publisherBgColor	string	Set the color of the Player background, e.g, #F5F5F5
visibleItems	integer	The number of items to show in the playlist before a scrollbar appears

Player methods

Once the Player is set up, various methods are available to control the audio, set the Player language, or obtain information about the Player state.

Player methods can be called directly, e.g. AppInst.play(), or you can create an new object within the window object and add the methods you want available, as shown here:

BeyondWordsSdk.player(parameters).then(appInst => {
  appInst.play();

  window.YourApp = {
    paused() {
      const result = appInst.paused();
      console.log(`fn_paused() -> ${result}`);
    },
  };
)};

Methods can be called like so: YourApp.paused().

Methods

Method	Type	Description
play()	-	Play the audio

The play() also returns a promise which can be resolved when playback has started, or is rejected if for some reason playback cannot be started.

BeyondWordsSdk.player(parameters).then(appInst => {
  appInst.play().then(() => {
    appInst.changeCurrentTime(6);
  });
)};

Method	Type	Description
pause()	-	Pause the audio
changeLang(lang)	string	Set the text language in the player, e.g. en_GB
currentTime()	-	Get the current time in seconds, rounded to two decimal places, e.g. 28.05
duration()	-	Get the total duration of the audio in seconds, rounded to two decimal places, e.g. 28.05
remainingTime()	-	Get the time remaining of the audio in seconds, rounded to two decimal places, e.g. 28.05
changeCurrentTime(seconds)	number	Set play position between 0 and total duration in seconds, rounded to two decimal places, e.g. 18.05
rewind(seconds)	number	Rewind the playback by the specified seek time in seconds, e.g. 15.0
forward(seconds)	number	Forward the playback by the specified seek time in seconds, e.g. 15.0
getCurrent()	-	Get the current audio index in the playlist
setCurrent(index)	number	Set audio index in the playlist
previous()	-	Skip to the previous audio in the playlist
next()	-	Skip to the next audio in the playlist
getPlaylist()	-	Returns an array with a list of audio objects
getPlaylistItem(index)	number	Returns the audio object in that index
loadPlaylist(arrayIDs)		Returns a promise from which you can get data from the parameter list

Example for parameter arrayIDs:

[
  { podcastId: '...' },
  { podcastId: '...' },
  ...
  { podcastId: '...' },
]

Returns a promise list of audios:

[
  {
    id: '...', // podcastId
    externalId: '...', // external ID for podcast
    title: 'Podcast title',
    author: 'Podcast author',
    duration: 30.58, // in seconds
    publishedAt: '2020-11-04T09:23:29.000Z', // Standard ISO 8601 format is used by your input string.
  }
]

Method	Type	Description
isAudioReady(object)	promise	Checks whether the audio has been processed or not

// Check if audio is available for your params
appInst.isAudioReady({
  projectId: "...",
  // One of the following parameters
  podcastId: "..."
}).then((boolResponse) => {
    if (boolResponse) {
    // If true, the audio has been processed
  }
});

Method	Type	Description
playbackRate()	-	Get the playback rate
changePlaybackRate(number)	number	Set the playback rate. It accepts any numeric value from the following list: 0.5, 1, 1.25, 1.5, 2
currentMedia()	-	Get the media object being played.
changeColor(object)	object	Set the Player colors for light and dark modes.

changeColor({
  dm: true, // use darkmode
  color: '#000000', // colour for icons
  textColor: '#000000', // colour for titles
  bgColor: '#ffffff', // colour for background
  dmColor: '#ffffff', // colour for icons for darkmode
  dmTextColor: '#ffffff', // colour for titles for darkmode
  dmBgColor: '#000000', // colour for background for darkmode
})

Playlist Player events

You can run custom functions based on specific Playlist Player events using the on and off listener to bind your functions to the events:

BeyondWordsSdk.player(parameters).then(appInst => {
  // Bind to the play event:
  appInst.events.on(BeyondWordsSdk.Events.play, dataEvent => {
    console.log(`on -> ${BeyondWordsSdk.Events.play} -> `, dataEvent);
  });
  // on -> play -> { duration: 10.23, progress: 3.12, index: 0 }
});

appInst.events supported a next methods

• on(type, handler): Register an event handler for the given type

• off(type, handler): Remove an event handler for the given type

play

This event fires when playback is initiated.

Event data

duration number

The total duration of the audio in seconds, rounded to two decimal places, e.g. 28.05.

---

progress number

The duration of the audio already played in seconds, rounded to two decimal places, e.g. 28.05.

---

index number

The index of the audio already played.

Sample event data

{
  "duration": 30.04,
  "progress": 10.6,
  "index": 0,
}

pause

This event fires when audio is paused.

Event data

duration number

The total duration of the audio in seconds, rounded to two decimal places, e.g. 28.05.

---

progress number

The duration of the audio played, when the pause was triggered, in seconds, rounded to two decimal places, e.g. 28.05.

---

index number

The index of the audio already played.

Sample event data

{
  "duration": 30.04,
  "progress": 10.6,
  "index": 0,
}

timeUpdate

This event fires every 25ms during playback and indicates, in seconds, the duration of the audio that has been played, e.g. 28.05.

Event data

duration number

The total duration of the audio in seconds, rounded to two decimal places, e.g. 28.05.

---

progress number

The duration of the audio played in seconds, rounded to two decimal places, e.g. 28.05.

---

index number

The index of the audio already played.

Sample event data

{
  "duration": 30.04,
  "progress": 10.6,
  "index": 0,
}

playbackRate

This event fires when the playback rate of the audio in the Playlist Player changes.

Event data

playbackRate number

The new playback rate, e.g. 1.5.

{ 
  "playbackRate": 1.5
}

ended

This event fires when the audio completes playback.

Event data

index number

The index of the audio was ended.

{ 
  "index": 0
}