# AudioPlayer

Audio player with native HTML5 streaming and audio-reactive visualizations.

## Features

- Native HTML5 audio playback (no crackling, native streaming support)
- Web Audio API for real-time frequency analysis
- Audio-reactive cover effects (glow, orbs, spotlight, mesh)
- Frequency visualization waveform
- Full playback controls

## Quick Start

```tsx
import { HybridSimplePlayer, HybridCompactPlayer } from '@djangocfg/ui-nextjs';

// Simple usage
<HybridSimplePlayer src="https://example.com/audio.mp3" />

// Compact single-row player (for lists, sidebars)
<HybridCompactPlayer src="https://example.com/audio.mp3" title="Rain & Thunder" />

// With metadata and reactive cover
<HybridSimplePlayer
  src={audioUrl}
  title="Track Title"
  artist="Artist Name"
  coverArt="/path/to/cover.jpg"
  reactiveCover
  variant="spotlight"
/>

// Full customization
<HybridSimplePlayer
  src={audioUrl}
  title="Track Title"
  coverArt={coverUrl}
  showWaveform
  waveformMode="frequency"  // 'frequency' | 'static'
  showLoop
  reactiveCover
  variant="spotlight"       // 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none'
  intensity="medium"        // 'subtle' | 'medium' | 'strong'
  colorScheme="primary"     // 'primary' | 'vibrant' | 'cool' | 'warm'
  layout="horizontal"       // 'vertical' | 'horizontal'
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | required | Audio URL |
| `title` | `string` | - | Track title |
| `artist` | `string` | - | Artist name |
| `coverArt` | `string \| ReactNode` | - | Cover image URL or custom element |
| `coverSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Cover art size |
| `showWaveform` | `boolean` | `true` | Show frequency visualization |
| `waveformMode` | `'frequency' \| 'static'` | `'frequency'` | Visualization mode |
| `waveformHeight` | `number` | `64` | Waveform height in pixels |
| `showTimer` | `boolean` | `true` | Show time display |
| `showVolume` | `boolean` | `true` | Show volume control |
| `showLoop` | `boolean` | `true` | Show loop button |
| `reactiveCover` | `boolean` | `true` | Enable reactive effects |
| `variant` | `VisualizationVariant` | `'spotlight'` | Effect variant |
| `intensity` | `EffectIntensity` | `'medium'` | Effect intensity |
| `colorScheme` | `EffectColorScheme` | `'primary'` | Effect colors |
| `autoPlay` | `boolean` | `false` | Auto-play on load |
| `loop` | `boolean` | `false` | Loop playback |
| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |

## Advanced Usage

### HybridAudioProvider + HybridAudioPlayer

For custom layouts:

```tsx
import {
  HybridAudioProvider,
  HybridAudioPlayer,
  AudioReactiveCover,
  useHybridAudioContext
} from '@djangocfg/ui-nextjs';

function MyPlayer({ audioUrl }: { audioUrl: string }) {
  return (
    <HybridAudioProvider src={audioUrl}>
      <AudioReactiveCover variant="spotlight" onClick={handleClick}>
        <img src={coverUrl} alt="Cover" />
      </AudioReactiveCover>
      <HybridAudioPlayer showWaveform showControls />
      <CustomControls />
    </HybridAudioProvider>
  );
}

function CustomControls() {
  const { state, controls, audioLevels } = useHybridAudioContext();

  return (
    <div>
      <p>Bass level: {(audioLevels.bass * 100).toFixed(0)}%</p>
      <button onClick={controls.togglePlay}>
        {state.isPlaying ? 'Pause' : 'Play'}
      </button>
    </div>
  );
}
```

## Hooks

### useHybridAudioContext

Full context access:

```tsx
const {
  state,       // { isReady, isPlaying, currentTime, duration, volume, isMuted, isLooping }
  controls,    // { play, pause, togglePlay, seek, skip, setVolume, toggleMute, toggleLoop }
  audioLevels, // { bass, mid, high, overall }
  webAudio,    // { context, analyser, sourceNode }
  audioRef,    // React ref to HTMLAudioElement
} = useHybridAudioContext();
```

### Specialized Hooks

```tsx
// State only
const { isPlaying, currentTime, duration } = useHybridAudioState();

// Controls only (no re-render on time updates)
const { play, pause, togglePlay, seek } = useHybridAudioControls();

// Audio levels for reactive effects
const { bass, mid, high, overall } = useHybridAudioLevels();

// Web Audio API access
const { context, analyser, sourceNode } = useHybridWebAudio();
```

## Components

### AudioReactiveCover

Album art wrapper with audio-reactive effects:

```tsx
<AudioReactiveCover
  variant="spotlight"    // 'glow' | 'orbs' | 'spotlight' | 'mesh'
  intensity="medium"     // 'subtle' | 'medium' | 'strong'
  colorScheme="primary"  // 'primary' | 'vibrant' | 'cool' | 'warm'
  onClick={() => nextVariant()}
>
  <img src={coverArt} alt="Album cover" />
</AudioReactiveCover>
```

### HybridCompactPlayer

Single-row player — play/pause + waveform + timer. No cover art, no volume slider.

```tsx
<HybridCompactPlayer
  src={audioUrl}
  title="Track name"     // used as tooltip
  waveformMode="frequency"  // 'frequency' | 'static'
  showTimer={true}
  autoPlay={false}
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | required | Audio URL |
| `title` | `string` | - | Tooltip / aria-label |
| `waveformMode` | `'frequency' \| 'static'` | `'frequency'` | Visualization mode |
| `showTimer` | `boolean` | `true` | Show current/total time |
| `buttonSize` | `'sm' \| 'md'` | `'md'` | Play button size (`sm` = h-6 w-6, `md` = h-8 w-8) |
| `autoPlay` | `boolean` | `false` | Auto-play on load |
| `loop` | `boolean` | `false` | Loop playback |
| `initialVolume` | `number` | `1` | Initial volume 0-1 |

For lazy-loading (preferred in Next.js apps):

```tsx
import { LazyHybridCompactPlayer } from '@djangocfg/ui-tools';

<LazyHybridCompactPlayer src={url} title="Track" autoPlay />
```

### HybridWaveform

Real-time frequency visualization:

```tsx
<HybridWaveform
  mode="frequency"  // 'frequency' | 'static'
  height={64}
  barWidth={3}
  barGap={2}
/>
```

## Effect Variants

| Variant | Description |
|---------|-------------|
| `spotlight` | Rotating conic gradient with bass pulse |
| `glow` | Multi-layered radial glows from edges |
| `orbs` | Floating orbs that react to frequencies |
| `mesh` | Large gradient blobs with movement |
| `none` | Effects disabled |

## Architecture

```
AudioPlayer/
├── index.ts                       # Public API exports
├── types/                         # TypeScript types
├── hooks/
│   ├── useHybridAudio.ts          # HTML5 audio + Web Audio hook
│   ├── useHybridAudioAnalysis.ts  # Frequency analysis
│   └── useVisualization.tsx       # Visualization settings
├── context/
│   └── HybridAudioProvider.tsx    # Audio context provider
├── components/
│   ├── HybridAudioPlayer.tsx      # Main player component
│   ├── HybridSimplePlayer.tsx     # All-in-one wrapper (with cover, volume, effects)
│   ├── HybridCompactPlayer.tsx    # Compact single-row player
│   ├── HybridWaveform.tsx         # Frequency visualization
│   └── ReactiveCover/             # Reactive effects
├── effects/                       # Effect calculations
└── utils/                         # Utilities
```

Key design:
- HTML5 `<audio>` for playback (native streaming, no crackling)
- Web Audio API AnalyserNode for visualization only (not connected to output)
- Audio graph: `source → destination` + `source → analyser` (passive)
