# `<PremiumPlayer>`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`<PremiumPlayer>` is the full-featured media-player surface — a
composition of `<AudioPlayer>`, `<AudioVisualizer>`, and
`<MasterMeter>` arranged as a single instrument panel. It is intended
for hero player surfaces (landing pages, profile pages, demo apps)
that want the whole monitoring suite without forcing consumers to
wire three components by hand.

Every behavioural guarantee of the underlying components applies:
the player polls plugin state, the visualiser reads block samples
from the named bus, and the meter computes peak / RMS / hold envelope
on every UI tick. None of the three sub-components share state; they
compose by sitting in the same DOM section.

## Features

- Bundles `<AudioPlayer>` + `<AudioVisualizer>` + `<MasterMeter>`.
- Routes a single `busName` to both the visualiser and the meter so
  they show the same source.
- Forwards `src` to the player for auto-load on mount.
- Adds the `.rax-premium-player` class for theming.

## Usage: Basic Example

```tsx
import { AudioPlayerPlugin } from "@suaveplan/audio-fx-plugin-audio-player";
import { AudioProvider, PremiumPlayer } from "@suaveplan/react-audio";

const plugin = new AudioPlayerPlugin({});

export function Hero() {
    return (
        <AudioProvider>
            <PremiumPlayer plugin={plugin} src="https://cdn/hero.wav" />
        </AudioProvider>
    );
}
```

## Usage: Advanced Example

```tsx
import { AudioPlayerPlugin } from "@suaveplan/audio-fx-plugin-audio-player";
import { AudioProvider, PremiumPlayer } from "@suaveplan/react-audio";

const plugin = new AudioPlayerPlugin({});

export function AuxBusPlayer() {
    return (
        <AudioProvider>
            <PremiumPlayer
                plugin={plugin}
                src="https://cdn/aux.wav"
                busName="auxA"
                className="aux-hero"
            />
        </AudioProvider>
    );
}
```

## API Reference

| Prop        | Type                | Default     | Notes                                              |
| ----------- | ------------------- | ----------- | -------------------------------------------------- |
| `plugin`    | `AudioPlayerPlugin` | —           | Required.                                          |
| `src`       | `string \| undef`   | —           | Forwarded to `<AudioPlayer>` for auto-load.        |
| `busName`   | `string \| undef`   | `"master"`  | Routed to the visualiser and meter.                |
| `className` | `string \| undef`   | —           | Forwarded; merged with `rax-premium-player`.       |

## Implementation Notes

The composition only forwards the `busName` to the visualiser + meter
when one is supplied — otherwise the sub-components fall back to
their own `"master"` defaults, which keeps the API surface honest
about what we are choosing for the user. The player sub-component
also receives the `src` only when it is defined, so the auto-load
effect inside `<AudioPlayer>` doesn't run with `undefined` and trip a
guard. There is no separate state in this component; it is pure
composition. New monitoring sub-components (e.g. spectrum analysers,
oscilloscope) can be added inline without changing the prop signature.