> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic control

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](/docs-and-guides/distribution/player/installation/javascript-sdk) and to native SDKs, which expose the same underlying API.

<Tip>
  For a full list of configurable properties, see [player properties](/docs-and-guides/distribution/player/developer-guides/player-properties). For event listeners, see [player events](/docs-and-guides/distribution/player/developer-guides/player-events).
</Tip>

## 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:**

```javascript theme={null}
const player = new BeyondWords.Player({
  target: '#beyondwords-player',
  projectId: YOUR_PROJECT_ID,
  contentId: 'YOUR_CONTENT_ID',
});
```

**From an existing embed:**

```javascript theme={null}
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:

```javascript theme={null}
// 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:

```javascript theme={null}
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](/docs-and-guides/distribution/player/installation/ios-sdk) and [Android](/docs-and-guides/distribution/player/installation/android-sdk) SDK guides.

## FAQs

<AccordionGroup>
  <Accordion title="How do I control a player installed by my CMS plugin?">
    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.
  </Accordion>

  <Accordion title="Will my runtime changes persist after content reloads?">
    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.
  </Accordion>

  <Accordion title="How do I listen for playback events?">
    Register listeners with `player.addEventListener(...)`. See [player events](/docs-and-guides/distribution/player/developer-guides/player-events) for available event types and cleanup patterns.
  </Accordion>

  <Accordion title="Can I control the player from server-side code?">
    No—programmatic control runs in the browser or native app. Server-side code can configure content and player settings via the [API](/docs-and-guides/integrations/api-overview), but playback control requires the client-side SDK.
  </Accordion>
</AccordionGroup>

## Getting help

If you encounter issues or have questions, [contact support](/docs-and-guides/support/get-support). Include your initialization code and any console errors.