JavaScript SDK (Player)

Automatically embed audio versions with our JavaScript Player SDK.

Our JavaScript Player SDK allows you to automatically embed audio versions using a custom audio player.

This means that you can build an interface and add functionality to suit your needs. For example, it is possible to display the player interface to the user, but only make it usable to those with a subscription to your publication. If they are not subscribed, a dropdown box prompts them to do so.

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 @speechkit/speechkit-audio-player-v2

Or, you can reference an up‐to‐date version on our CDN:

<script type="module">
  import SpeechKit from 'https://proxy.speechkit.io/npm/@speechkit/[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
SpeechKit.isAudioReady(initParams).then((boolResponse) => {
    if (boolResponse) {
      // If true, the player can be inited
        SpeechKit.player(initParams).then((appInst) => {
            // Player is initialized
        });
    }
});

To intialize the JavaScript Player with the SDK, import the package:

import { SpeechKitSdk } from '@speechkit/speechkit-audio-player-v2';

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
SpeechKitSdk.isAudioReady(initParams).then((boolResponse) => {
    if (boolResponse) {
      // If true, the player can be inited
        SpeechKitSdk.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.

Mandatory parameters


projectId integer

This is the SpeechKit Project ID.


podcastID integer (conditional)

This is the podcast ID from the SpeechKit API response.


externalID integer (conditional)

This is your internal article ID.


articleUrl string (conditional)

This is the article URL.


Advanced parameters


renderNode string (optional)

This is the ID of the container element. The default is set to speechkit-player.


UIenabled boolean (optional)

Set to false to use the Player without the UI.


publisherColor string (optional)

Set the color of the Player icons and progress bar, e.g, #000000.


publisherBgColor string (optional)

Set the color of the player background, e.g, #F5F5F5.


Player methods

Once the basic 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:

SpeechKitSdk.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.

SpeechKitSdk.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 Player.


paused() -

This method determines whether or not the 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.


isAudioReady(object) promise

This method 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: "...",
  articleUrl: "...",
  externalId: "...",
}).then((boolResponse) => {
    if (boolResponse) {
    // If true, the audio has been processed
  }
});

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.


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:

SpeechKitSdk.player(parameters).then(appInst => {
  // Bind to the play event:
  appInst.events.on(SpeechKitSdk.Events.play, dataEvent => {
    console.log(`on -> ${SpeechKitSdk.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
}