JS Playlist Player and SDK

The JS Player and SDK is client-side JavaScript library that is completely separate from the API. You connect to it differently, and it gives you a different range of options.

Install

You can install the JS Player and SDK through NPM:

npm install --save @speechkit/speechkit-audio-player-v2

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

<script type="module">
  import SpeechKit from 'https://proxy.speechkit.io/npm/@speechkit/speechkit-audio-player-v2@latest/dist/module/index.js';
</script>

Initialize

To initialize the JS Playlist Player use the following:

SpeechKit.player({
  renderNode: "...",
  projectId: "...",
	player: "PlaylistPlayer"
}).then((appInst) => {
	// Player is initialized
});

To intialize the JS Playlist Player with the SDK import the package:

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

Then use the following:

SpeechKitSdk.player({
  renderNode: "...",
  projectId: "...",
	player: "PlaylistPlayer"
}).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 JS Playlist Player SDK.

Mandatory Parameters

projectId integer

This is the Project ID.

player string

To use the Playlist Player you should pass "PlaylistPlayer".

playlist array

Array of objects like { key: value } where key can be one of (podcastId | externalId). The array should be sorted in the order that you wish the audios to appear in the playlist player.

Example for array of playlist:

[
	{ podcastId: '...' },
  { podcastId: '...' },
  ...
  { podcastId: '...' },
]

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 playlist player without the UI.

publisherColor string (optional)

Set the color of the playlist player icons and progress bar, 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 setup, various methods are available to control the audio, set the player language, or obtain information about the playlist player state.

Player methods can be called directly eg. 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.

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, eg 28.05.

duration() -

This method gets the total duration of the audio in seconds, rounded to two decimal places, eg 28.05.

remainingTime() -

This method gets the time remaining of the audio in seconds, rounded to two decimal places, eg 28.05.

changeCurrentTime(seconds) number

This method sets play position between 0 and total duration in seconds, rounded to two decimal places, eg 18.05.

rewind(seconds) number

This method rewinds the playback by the specified seek time in seconds eg 5.0.

forward(seconds) number

This method fast forwards the playback by the specified seek time in seconds eg 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.
  }
]

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:

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, index: 0 }
});
image

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, eg 28.05.

progress number

The duration of the audio already played in seconds, rounded to two decimal places, eg 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, eg 28.05.

progress number

The duration of the audio played, when the pause was triggered, in seconds, rounded to two decimal places, eg 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, eg 28.05.

Event data:

duration number

The total duration of the audio in seconds, rounded to two decimal places, eg 28.05.

progress number

The duration of the audio played in seconds, rounded to two decimal places, eg 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 player changes.

Event data:

playbackRate number

The new playback rate, eg 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
}