Skip to main content
The BeyondWords JavaScript player delivers audio and video on any webpage. Install it with an embed script (quickest) or the NPM package (best for frameworks and build tools).
Using Magic Embed, WordPress, or Ghost? The player may already be installed—check your integration guide before adding the SDK manually.

​
How it works

  1. The SDK loads from proxy.beyondwords.io and creates a BeyondWords.Player instance.
  2. You pass a project ID and one or more content identifiers (contentId, sourceId, sourceUrl, or playlistId).
  3. The player fetches content and settings from the player API, then renders the UI at your target element.
  4. Appearance and behavior come from Distribution → Player → Settings in your dashboard, unless overridden via player properties.

​
Before you begin

  • A BeyondWords project with generated content
  • Your numeric project ID (from Settings → Integrations → API)
  • A content identifier—contentId, sourceId, sourceUrl, or playlistId. See load content below.

​
Install with an embed script

1

Add a target element

Place a <div> (or other element) where you want the player to appear, or use target: this in the script tag to insert the player immediately after the tag.
2

Paste the embed script

Add the script to your page HTML:
<script async defer
  src="https://proxy.beyondwords.io/npm/@beyondwords/player@latest/dist/umd.js"
  onload="new BeyondWords.Player({
    target: this,
    projectId: YOUR_PROJECT_ID,
    contentId: 'YOUR_CONTENT_ID',
  })">
</script>
Replace YOUR_PROJECT_ID with your numeric project ID and 'YOUR_CONTENT_ID' with the content UUID.The async and defer attributes let the rest of the page load while the SDK downloads. Setting target: this mounts the player right after the script tag.
3

Configure the player

Customize appearance in Distribution → Player → Settings, or pass player properties in the onload handler to override dashboard defaults.

​
Install with NPM

1

Install the package

npm install @beyondwords/player
2

Add a container element

<div id="beyondwords-player"></div>
The container must exist in the DOM before you initialize the player.
3

Initialize the player

import BeyondWords from '@beyondwords/player';

new BeyondWords.Player({
  target: '#beyondwords-player',
  projectId: YOUR_PROJECT_ID,
  contentId: 'YOUR_CONTENT_ID',
});
Replace YOUR_PROJECT_ID and 'YOUR_CONTENT_ID' with your project ID and content UUID.

​
Load content

The player needs projectId plus at least one identifier. If you pass multiple identifiers, the player loads all matching published content as a playlist.
IdentifierUse when
contentIdYou have the BeyondWords content UUID
sourceIdYou have your CMS article ID (recommended—more stable than URLs)
sourceUrlYou want to match by page URL (defaults to window.location.href if nothing else is set)
playlistIdLoading a Standard or Smart playlist
playlistBuilding a dynamic playlist from an array of identifiers
// Match by CMS source ID (recommended)
new BeyondWords.Player({
  target: '#beyondwords-player',
  projectId: YOUR_PROJECT_ID,
  sourceId: 'article-12345',
});

// Load a dashboard playlist
new BeyondWords.Player({
  target: '#beyondwords-player',
  projectId: YOUR_PROJECT_ID,
  playlistId: YOUR_PLAYLIST_ID,
});

​
Configuration

​
Dashboard settings

Configure the player in Distribution → Player in your project dashboard:
  • Settings—size, colors, highlighting, continuous playback, downloads
  • Access tiers—different experiences by audience

​
Property overrides

Pass properties in your embed code or NPM initialization to override dashboard settings. Values set at initialization take precedence over the API defaults. See programmatic control for override order. 
<script async defer
  src="https://proxy.beyondwords.io/npm/@beyondwords/player@latest/dist/umd.js"
  onload="new BeyondWords.Player({
    target: this,
    projectId: YOUR_PROJECT_ID,
    contentId: 'YOUR_CONTENT_ID',
    playerStyle: 'large',
    callToAction: 'Listen to this article',
    backgroundColor: '#f5f5f5',
  })">
</script>

​
Programmatic control

The new BeyondWords.Player(...) call returns a player instance you can control at runtime—play, pause, seek, change track, update properties, and listen to events. See programmatic control and the player API. On single-page apps, call player.destroy() or BeyondWords.Player.destroyAll() when removing the player to free browser resources.

​
FAQs

Use the embed script for static sites, CMS templates, or quick prototypes. Use NPM when you’re building with React, Vue, Next.js, or another framework where you import modules and manage component lifecycles.
  • Confirm the content has finished generating and is published in the dashboard
  • Check projectId and your content identifier are correct
  • Ensure the target element exists before initialization (NPM)
  • Open the browser console for JavaScript errors
  • If using sourceUrl, verify the page URL matches the content’s source_url
Yes. Pass multiple identifiers, a playlistId, or a playlist array. The player loads all matching published content and plays them in sequence. See playlists for curated collections.
Set showUserInterface: false to run in headless mode and build your own controls on top of the SDK. See build your own UI.

​
GitHub repository

JavaScript SDK repository

View the source code, releases, and API documentation on GitHub.