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

# Player Provider

> React context and hooks for interacting with the BeyondWords player instance.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npx @beyondwords/cli components add player-provider
  ```

  ```bash pnpm theme={null}
  pnpm dlx @beyondwords/cli components add player-provider
  ```

  ```bash yarn theme={null}
  yarn dlx @beyondwords/cli components add player-provider
  ```

  ```bash bun theme={null}
  bunx --bun @beyondwords/cli components add player-provider
  ```
</CodeGroup>

## Usage

Wrap your UI in `PlayerProvider`, then read player state with the hooks.

```tsx theme={null}
import { PlayerProvider, usePlayer, usePlayerSelector } from '@/registry/react/PlayerProvider';

function Status() {
  // Re-renders only when the selected value changes.
  const state = usePlayerSelector((p) => p.playbackState);
  return <span>{state}</span>;
}

function Controls() {
  const player = usePlayer(); // the raw BeyondWords player instance
  return <button onClick={() => (player.playbackRate = 1.5)}>1.5x</button>;
}

export function App() {
  return (
    <PlayerProvider args={{ projectId: 9504, contentId: "ba00ef51-03ac-4a85-8b98-e45c957e8ef8", showUserInterface: false }}>
      <Status />
      <Controls />
    </PlayerProvider>
  );
}
```

### Video

To use a video player, add `video: true` to the player `args`.

```tsx theme={null}
import { PlayerProvider } from '@/registry/react/PlayerProvider';
import { PlayPauseButton } from '@/registry/react/PlayPauseButton';

export function VideoPlayer() {
  return (
    <PlayerProvider args={{ projectId: 54009, contentId: "5ab6a5e1-689c-4103-962d-e7e68a4258ff", video: true, showUserInterface: false }}>
      <PlayPauseButton />
    </PlayerProvider>
  );
}
```

### API

* **`PlayerProvider`**: creates a `BeyondWords.Player` and provides it via context. `args` is forwarded to the player constructor.
* **`usePlayer()`**: returns the player instance. Throws if used outside a provider.
* **`usePlayerSelector(selector, deps?, options?)`**: subscribes to player events and returns the selected slice of state. It re-renders only when that slice changes (customizable via `options.equalityFn`).