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.
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>
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.
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: '...' }
]
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 |
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()
.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: '...' },
]
[
{
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
})
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 methodson(type, handler)
: Register an event handler for the given typeoff(type, handler)
: Remove an event handler for the given type
This event fires when playback is initiated.
Event data
duration
numberThe total duration of the audio in seconds, rounded to two decimal places, e.g.
28.05
.---
progress
numberThe duration of the audio already played in seconds, rounded to two decimal places, e.g.
28.05
.---
index
numberThe index of the audio already played.
Sample event data
{
"duration": 30.04,
"progress": 10.6,
"index": 0,
}
This event fires when audio is paused.
Event data
duration
numberThe total duration of the audio in seconds, rounded to two decimal places, e.g.
28.05
.---
progress
numberThe duration of the audio played, when the pause was triggered, in seconds, rounded to two decimal places, e.g.
28.05
.---
index
numberThe index of the audio already played.
Sample event data
{
"duration": 30.04,
"progress": 10.6,
"index": 0,
}
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
numberThe total duration of the audio in seconds, rounded to two decimal places, e.g.
28.05
.---
progress
numberThe duration of the audio played in seconds, rounded to two decimal places, e.g.
28.05
.---
index
numberThe index of the audio already played.
Sample event data
{
"duration": 30.04,
"progress": 10.6,
"index": 0,
}
This event fires when the playback rate of the audio in the Playlist Player changes.
Event data
playbackRate
numberThe new playback rate, e.g.
1.5
.{
"playbackRate": 1.5
}
This event fires when the audio completes playback.
Event data
index
numberThe index of the audio was ended.
{
"index": 0
}
Last modified 2mo ago