Skip to main content
After the player loads, you can control it programmatically—play and pause, seek, change tracks, update properties, and react to state changes. This applies to the JavaScript SDK and to native SDKs, which expose the same underlying API.
For a full list of configurable properties, see player properties. For event listeners, see player events.

​
How it works

The new BeyondWords.Player(...) call returns a player instance—a reactive object whose properties you can read and write. Changes take effect immediately (for example, setting player.backgroundColor = "red" updates the UI). You can also retrieve existing instances if the player was initialized elsewhere (for example via an embed script added by a CMS plugin).

​
Get a player instance

At initialization: 
const player = new BeyondWords.Player({
  target: '#beyondwords-player',
  projectId: YOUR_PROJECT_ID,
  contentId: 'YOUR_CONTENT_ID',
});
From an existing embed: 
const player = BeyondWords.Player.instances()[0];
BeyondWords.Player.instances() returns an array of all initialized player instances on the page. BeyondWords is available on the global window object when using the embed script.

​
Control playback and state

Read and write properties on the player instance: 
// Read state
console.log(player.currentTime);
console.log(player.playbackState); // e.g. 'playing', 'paused', 'ended'

// Control playback
player.playbackState = 'playing';
player.playbackState = 'paused';

// Seek
player.currentTime = 30;

// Change track in a playlist
player.contentIndex = 2;

// Update appearance
player.backgroundColor = 'red';
player.callToAction = 'Listen now';
The player is reactive—UI updates automatically when you change supported properties.

​
How overrides work

Settings can come from three places, in this order of precedence for initialization:
  1. Player API—defaults fetched using your projectId and content identifiers
  2. Initialization code—properties passed to new BeyondWords.Player({ ... }) or the embed script onload handler
  3. Runtime SDK calls—property changes made after the player has loaded
At initialization, embed code properties override API defaults. After load, runtime changes override the current state. If content identifiers change and a new API request is made:
  • Runtime changes (step 3) are reset
  • Initialization overrides (step 2) persist
Only include a property in the initializer if you want it to survive content reloads.

​
Top-level methods

Useful static methods and instance helpers: 
BeyondWords.Player.version // e.g. "0.1.23"

BeyondWords.Player.instances() // all initialized instances

BeyondWords.Player.instances()[0].target // root DOM node

BeyondWords.Player.instances()[0].properties() // all properties as a key-value object

BeyondWords.Player.instances()[0].destroy() // remove one instance

BeyondWords.Player.destroyAll() // remove all instances
Call destroy() or destroyAll() on single-page apps when the player is no longer needed—for example when navigating away or unmounting a component.

​
Native SDKs

On iOS and Android, the native PlayerView wraps the same JavaScript player. Use the setter methods on PlayerView (for example setPlayerStyle, setBackgroundColor) or access the underlying player instance for full control. See the iOS and Android SDK guides.

​
FAQs

Use BeyondWords.Player.instances()[0] once the page has loaded. If you have multiple players, filter by checking each instance’s target or content identifiers.
No—runtime property changes are reset when identifiers change and a new API request is made. To persist overrides across reloads, include them in the player initializer.
Register listeners with player.addEventListener(...). See player events for available event types and cleanup patterns.
No—programmatic control runs in the browser or native app. Server-side code can configure content and player settings via the API, but playback control requires the client-side SDK.

​
Getting help

If you encounter issues or have questions, contact support. Include your initialization code and any console errors.