Player SDK (Legacy)

Our JavaScript Player SDK allows you to automatically embed audio versions into their source pages using our player UI or your own UI.

This means that you can build a UI and customize 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/audio-player@latest/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 `beyondwords-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 `beyondwords-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)
        });
    }
});

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