Playlist SDK (JavaScript)

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.
🔒 This feature is available on Enterprise plans only. Request a meeting now.
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/[email protected]/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
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
}

Project Playlists

Next - Analytics

Dashboard analytics

Last modified 20d ago

Copy link

Outline

Playlist Player events