We’re deprecating our legacy Player at the end of Q2 2025.

To support this transition, we’ve created a migration guide to help you update your integration and take advantage of the new features.

This guide will walk you through the migration process, whether by updating the player embed script or using NPM.

​
Whats new?

The updated player comes with several new customization features designed to enhance user engagement and improve the listening experience.

For more details on the new player’s features, visit our player documentation. To explore customization options and test new features in a sandbox environment, check out our player demo page.

​
Update the Embed Script

To start using the new BeyondWords player, you’ll need to replace the legacy embed script with the one below.

<script async defer src="https://proxy.beyondwords.io/npm/@beyondwords/player@latest/dist/umd.js" 
  onload="new BeyondWords.Player({ 
    target: this, 
    projectId: <projectID>,
    contentId: '<ID>'
  })">
</script>;

  • The <script> tag loads the BeyondWords Player and instantiates a new player instance.

  • The async and defer attributes ensure the browser doesn’t stall while downloading the script.

  • Setting target: this places the player immediately after the script tag in the <body>. If you need a different placement, you can specify another target.

  • You must replace the <ID> placeholders in the script with your projectId and contentId to ensure the correct audio is played.

You can use any of the following properties along with projectId to initialise the player.

PropertyDescription
contentIdUnique UUID string for the audio content.
You can also pass the previous integer audio ID as a string for users migrating from the legacy API.
sourceIdThe externally provided source identifier for a content item.
This could be the ID from your CMS, the <guid> from an RSS <item>, or the post ID if generated using the WordPress Plugin.
sourceUrlThe URL containing the source content.
This could be the public URL submitted via the API, the <link> from an RSS <item>, or the post URL from the WordPress Plugin.
playlistIdThe unique ID for a playlist created in the dashboard or through the API.

​
Update via NPM

1

Add the new player NPM package

npm add @beyondwords/player
2

Add a target <div>

This will be where the player is shown in your web application.

<div id='beyondwords-player'></div>
3

Initialize the player

import BeyondWords from '@beyondwords/player';

new BeyondWords.Player({ target: '#beyondwords-player', projectID: <ID>, contentId: '<ID>' });

You must replace the <ID> placeholders in the script with your projectId and contentId to ensure the correct audio is played.

You can use any of the following properties along with projectId to initialise the player.

PropertyDescription
contentIdUnique UUID string for the audio content.
You can also pass the previous integer audio ID as a string for users migrating from the legacy API.
sourceIdThe externally provided source identifier for a content item.
This could be the ID from your CMS, the <guid> from an RSS <item>, or the post ID if generated using the WordPress Plugin.
sourceUrlThe URL containing the source content.
This could be the public URL submitted via the API, the <link> from an RSS <item>, or the post URL from the WordPress Plugin.
playlistIdThe unique ID for a playlist created in the dashboard or through the API.