# Waveform player
> Pixel waveform player that fills as it plays, previews ahead of the playhead on hover and ripples from wherever you click.
- Element: `<px-player>`
- React: `import { PxPlayer } from "@/components/lumesec/px-player"`
- Collection: Pixel Lab (https://elements.lumesec.ai/components/pixel-lab)
- Registry item: https://elements.lumesec.ai/r/px-player.json
- Page: https://elements.lumesec.ai/components/pixel-lab/player



Live preview: https://elements.lumesec.ai/view/px-player

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-player.js"></script>

<px-player></px-player>
```

## Installation

```bash
npx shadcn@latest add @lumesec/px-player
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-player.json
```

## Usage

React:

```tsx
import { PxPlayer } from "@/components/lumesec/px-player";

export function Example() {
  return (
    <PxPlayer />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-player.js"></script>

<px-player></px-player>
```

## Behaviour

A pixel waveform that fills as it plays, previews ahead of the playhead on hover and sends a ripple out from wherever you click. The track is silent.

## API reference

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event   | React prop | Detail | Description                                                           |
| ------- | ---------- | ------ | --------------------------------------------------------------------- |
| `play`  | `onPlay`   | `{}`   | Fires when playback starts.                                           |
| `pause` | `onPause`  | `{}`   | Fires when playback pauses, including when the track reaches the end. |

### Methods

Call them on the element, for example through a React ref.

| Method                   | Description                                                |
| ------------------------ | ---------------------------------------------------------- |
| `toggle()`               | Starts or pauses playback and fires `play` or `pause`.     |
| `seek(position: number)` | Moves the playhead to a position from 0 to 1 of the track. |

## Keyboard

| Keys                   | Action                             |
| ---------------------- | ---------------------------------- |
| ArrowRight / ArrowLeft | Seek forward or back by 5 seconds. |
| Space                  | Play or pause.                     |

## Accessibility

* The play button is a native button whose `aria-label` switches between "Play" and "Pause".
* The waveform canvas is focusable with `role="slider"`, `aria-label="Seek"`, `aria-valuemin="0"` and `aria-valuemax="222"` (seconds).
* `aria-valuenow` is the position in seconds and `aria-valuetext` reads like "1:11 / 3:42". The hover time tooltip is pointer-only.
* Reduced motion: the bars around the playhead stop pulsing during playback; click ripples still play.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--card`, `--foreground`, `--lumesec`, `--lumesec-foreground` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg`, `--ui-mono`, `--ui-muted`, `--ui-on-accent` and `--ui-surface`.

## Notes

* The track is demo content: "Night Drive", 3:42 long, with a generated waveform and no audio. There is no attribute for a source. Playback starts at 32%.
* The waveform canvas is 64px tall.