Player SDK (JavaScript)
Automatically embed audio versions using the JavaScript Player SDK.
Our JavaScript Player SDK allows you to automatically embed audio versions into their source pages using the small player UI or your own.

🔒 This feature is available on Enterprise plans only. Request a meeting now.

This means that you can build a UI and customise player controls to suit your needs. For example, it is possible to render the player to all users, but only make it usable to those with a subscription.
The JavaScript Player and 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 the JavaScript Player

You can install the JavaScript Player and SDK through NPM:
npm install --save @beyondwords/audio-player
Or, you can 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 the JavaScript Player

To initialize the JavaScript Player, use the following:
const initParams = {
// Mandatory Parameters
projectId: "...",
// One of the following parameters
podcastId: "...",
articleUrl: "...",
externalId: "...",
// Advanced Parameter
renderNode: "...", // The default is set to `speechkit-player`
};
// Check if audio is available for your init params
BeyondWords.isAudioReady(initParams).then((boolResponse) => {
if (boolResponse) {
// If true, the player can be inited
BeyondWords.player(initParams).then((appInst) => {
// Player is initialized
});
}
});
Or, intialize the JavaScript Player with the SDK, import the package:
import { BeyondWordsSdk } from '@beyondwords/audio-player';
Then use the following:
const initParams = {
// Mandatory Parameters
projectId: "...",
// One of the following parameters
podcastId: "...",
articleUrl: "...",
externalId: "...",
// Advanced Parameter
renderNode: "...", // The default is set to `speechkit-player`
};
// Check if audio is available for your init params
BeyondWordsSdk.isAudioReady(initParams).then((boolResponse) => {
if (boolResponse) {
// If true, the player can be inited
BeyondWordsSdk.player(initParams).then((appInst) => {
// Player is initialized
// App instance provides access to methods & events (see below)
});
}
});
The Player SDK will now be available, and you will be able to use the JavaScript Player SDK.

Required parameters

Parameter
Type
Description
projectId
integer
This is the BeyondWords Project ID
podcastID
integer (conditional)
This is the Podcast ID assigned to the audio
externalID
integer (conditional)
This is the ID that you assigned to the audio when making creating audio via the API e.g. the ID of the article in your CMS
articleUrl
string (conditional)
This is the URL assigned to the audio when creating the audio via the API or the URL in the <link> element for each <item> (for those using the RSS Feed Importer)

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
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
})

Player events

You can run custom functions based on specific 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 }
});
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.
Sample event data
{
"duration": 30.04,
"progress": 10.6,
}

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.
Sample event data
{
"duration": 30.04,
"progress": 10.6,
}

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.
Sample event data
{
"duration": 30.04,
"progress": 10.6,
}

playbackRate

This event fires when the playback rate of the audio in the 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
playbackRate number
The new playback rate, e.g. 1.5.
{
"playbackRate": 1.5
}
Copy link
Outline
Install the JavaScript Player
Initialize the JavaScript Player
Required parameters
Optional parameters
Player methods
Player events