> ## 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.

# JavaScript SDK

The BeyondWords JavaScript player delivers [audio](/docs-and-guides/content/audio) and [video](/docs-and-guides/content/video) on any webpage. Install it with an embed script (quickest) or the NPM package (best for frameworks and build tools).

<Tip>
  Using [Magic Embed](/docs-and-guides/integrations/magic-embed), [WordPress](/docs-and-guides/integrations/publishing-platforms/wordpress), or [Ghost](/docs-and-guides/integrations/publishing-platforms/ghost)? The player may already be installed—check your integration guide before adding the SDK manually.
</Tip>

## 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](/docs-and-guides/distribution/player/developer-guides/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](/docs-and-guides/distribution/player/developer-guides/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](#load-content) below.

## Install with an embed script

<Steps>
  <Step title="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.
  </Step>

  <Step title="Paste the embed script">
    Add the script to your page HTML:

    ```html theme={null}
    <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.
  </Step>

  <Step title="Configure the player">
    Customize appearance in **Distribution → Player → Settings**, or pass [player properties](/docs-and-guides/distribution/player/developer-guides/player-properties) in the `onload` handler to override dashboard defaults.
  </Step>
</Steps>

## Install with NPM

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    npm install @beyondwords/player
    ```
  </Step>

  <Step title="Add a container element">
    ```html theme={null}
    <div id="beyondwords-player"></div>
    ```

    The container must exist in the DOM before you initialize the player.
  </Step>

  <Step title="Initialize the player">
    ```javascript theme={null}
    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.
  </Step>
</Steps>

## 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.

| Identifier   | Use when                                                                                                                      |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `contentId`  | You have the BeyondWords content UUID                                                                                         |
| `sourceId`   | You have your CMS article ID (recommended—more stable than URLs)                                                              |
| `sourceUrl`  | You want to match by page URL (defaults to `window.location.href` if nothing else is set)                                     |
| `playlistId` | Loading a [Standard or Smart playlist](/docs-and-guides/distribution/playlists)                                               |
| `playlist`   | Building a [dynamic playlist](/docs-and-guides/distribution/playlists#create-a-dynamic-playlist) from an array of identifiers |

```javascript theme={null}
// 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](/docs-and-guides/distribution/player/player-settings)**—size, colors, highlighting, continuous playback, downloads
* **[Access tiers](/docs-and-guides/distribution/player/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](/docs-and-guides/distribution/player/developer-guides/programmatic-control#how-overrides-work) for override order.

```html theme={null}
<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](/docs-and-guides/distribution/player/developer-guides/player-events). See [programmatic control](/docs-and-guides/distribution/player/developer-guides/programmatic-control) and the [player API](/docs-and-guides/distribution/player/developer-guides/player-api).

On single-page apps, call `player.destroy()` or `BeyondWords.Player.destroyAll()` when removing the player to free browser resources.

## FAQs

<AccordionGroup>
  <Accordion title="Should I use the embed script or NPM?">
    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.
  </Accordion>

  <Accordion title="Why isn't the player loading?">
    * 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`
  </Accordion>

  <Accordion title="Can I load multiple items in one player?">
    Yes. Pass multiple identifiers, a `playlistId`, or a `playlist` array. The player loads all matching published content and plays them in sequence. See [playlists](/docs-and-guides/distribution/playlists) for curated collections.
  </Accordion>

  <Accordion title="How do I build a custom player UI?">
    Set `showUserInterface: false` to run in headless mode and build your own controls on top of the SDK. See [build your own UI](/docs-and-guides/distribution/player/developer-guides/build-your-own-ui).
  </Accordion>
</AccordionGroup>

## GitHub repository

<Card title="JavaScript SDK repository" icon="js" href="https://github.com/beyondwords-io/player" target="_blank">
  View the source code, releases, and API documentation on GitHub.
</Card>