JavaScript Playlist Player SDK
Embed a custom playlist using our JavaScript Playlist Player SDK.
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({
renderNode: "...",
projectId: "...",
player: "PlaylistPlayer"
}).then((appInst) => {
// Player is initialized
});
To intialize the JavaScript Playlist Player with the SDK, import the package:
import { BeyondWordsSdk } from '@beyondwords/audio-player';
Then use the following:
BeyondWordsSdk.player({
renderNode: "...",
projectId: "...",
player: "PlaylistPlayer"
}).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.
Mandatory parameters
projectId
integer
This is the Project ID.
player
string
To use the Playlist Player you should pass "PlaylistPlayer"
.
Advanced parameters
playlist
array
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 player.
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: '...' }
]
playlistId
integer
This is the Playlist ID.
podcastId
integer
This is the podcast ID.
renderNode
string (optional)
This is the ID of the container element. The default is set to beyondwords-player
.
UIEnabled
boolean (optional)
Set to false to use the playlist player without the UI.
publisherColor
string (optional)
Set the color of the playlist player icons and progress bar, e.g, #000000
.
publisherTextColor
string (optional)
Set the color of the playlist player texts, e.g, #000000
.
publisherBgColor
string (optional)
Set the color of the playlist player background, e.g, #F5F5F5
.
Playlist Player methods
Once the basic Playlist Player is set up, various methods are available to control the audio, set the Playlist Player language, or obtain information about the Playlist Player state.
Playlist 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 using YourApp.paused()
.
Methods
play()
-
This method plays the audio. Also, this method 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);
});
)};
pause()
-
This method pauses the audio.
changeLang(lang)
string
This method changes the text language within the Playlist Player.
paused()
-
This method determines whether or not the Playlist Player is paused.
currentTime()
-
This method gets the current time in seconds, rounded to two decimal places, e.g. 28.05
.
duration()
-
This method gets the total duration of the audio in seconds, rounded to two decimal places, e.g. 28.05
.
remainingTime()
-
This method gets the time remaining of the audio in seconds, rounded to two decimal places, e.g. 28.05
.
changeCurrentTime(seconds)
number
This method sets play position between 0 and total duration in seconds, rounded to two decimal places, e.g. 18.05
.
rewind(seconds)
number
This method rewinds the playback by the specified seek time in seconds e.g. 5.0
.
forward(seconds)
number
This method fast-forwards the playback by the specified seek time in seconds e.g. 5.0
.
getCurrent()
This method returns the current audio index in the playlist.
setCurrent(index)
number
This method sets the audio index in the playlist.
previous()
This method skips to the previous audio in the playlist.
next()
This method skips to the next audio in the playlist.
getPlaylist()
This method returns a list of audios in the playlist.
[
{
id: '...', // podcastId
externalId: '...', // external ID for audio
title: 'Audio title',
author: 'Audio author',
duration: 30.58, // in seconds
publishedAt: '2020-11-04T09:23:29.000Z', // Standard ISO 8601 format is used by your input string.
}
]
getPlaylistItem(index)
number
This method returns the audio by index.
{
id: '...', // podcastId
externalId: '...', // external ID for audio
title: 'Audio title',
author: 'Audio author',
duration: 30.58, // in seconds
publishedAt: '2020-11-04T09:23:29.000Z', // Standard ISO 8601 format is used by your input string.
}
loadPlaylist(arrayIDs)
The method return a promise in 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.
}
]
playbackRate()
This method returns the current playback rate.
changePlaybackRate(number)
number
This method controls the playback rate. It accepts any numeric value from the following list: 0.5, 1, 1.25, 1.5, 2
.
currentMedia()
This method returns the media object being played.
changeColor(object)
-
This method changes the colors within the Player.
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
}
Updated 1 day ago