@djangocfg/ui-nextjs 2.1.81 → 2.1.83

package/src/tools/AudioPlayer/README.md

@@ -1,264 +1,225 @@
 # AudioPlayer
 
-Audio player with waveform visualization, built on WaveSurfer.js.
+Audio player library with multiple player implementations for different use cases.
 
-## Features
+## Player Comparison
 
-- Waveform visualization with interactive seeking
-- Audio-reactive cover effects (glow, orbs, spotlight, mesh)
-- Real-time frequency equalizer
-- Keyboard shortcuts
-- Volume control with mute
-- Skip forward/backward
-- Playback speed control
+| Feature | HybridSimplePlayer | SimpleAudioPlayer | ProgressiveAudioPlayer |
+|---------|-------------------|-------------------|------------------------|
+| **Recommended for** | Streaming, general use | Local files, full waveform | Large streaming files |
+| **Audio Engine** | HTML5 `<audio>` | WaveSurfer.js | HTML5 `<audio>` |
+| **Visualization** | Real-time frequency bars | Static waveform | Progressive waveform |
+| **Reactive Effects** | ✅ Full support | ✅ Full support | ❌ No |
+| **Streaming Support** | ✅ Native | ⚠️ Requires prefetch | ✅ Native |
+| **Seek Any Position** | ✅ Yes | ⚠️ Limited by buffer | ✅ Yes |
+| **No Crackling** | ✅ Guaranteed | ⚠️ Fixed in v2.1.82 | ✅ Yes |
+| **Memory Usage** | Low | High (full file) | Low |
+
+---
 
 ## Quick Start (Recommended)
 
+### HybridSimplePlayer — Best for Most Cases
+
 ```tsx
-import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
+import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
 
 // Minimal
-<SimpleAudioPlayer src="https://example.com/audio.mp3" />
+<HybridSimplePlayer src="https://example.com/audio.mp3" />
 
-// With metadata
-<SimpleAudioPlayer
+// With metadata and reactive cover
+<HybridSimplePlayer
   src={audioUrl}
   title="Track Title"
   artist="Artist Name"
   coverArt="/path/to/cover.jpg"
+  reactiveCover
+  variant="spotlight"
 />
 
 // Full customization
-<SimpleAudioPlayer
+<HybridSimplePlayer
   src={audioUrl}
   title="Track Title"
   coverArt={coverUrl}
   showWaveform
-  showEqualizer={false}
   reactiveCover
   variant="spotlight"
+  intensity="medium"
+  colorScheme="vibrant"
   layout="horizontal"
 />
 ```
 
-### SimpleAudioPlayer Props
+### HybridSimplePlayer Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `src` | `string` | required | Audio URL |
-| `prefetch` | `boolean` | `true` | Pre-fetch audio as blob (required for streaming URLs to enable seek) |
 | `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 waveform |
-| `showEqualizer` | `boolean` | `false` | Show equalizer bars |
+| `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/repeat button |
 | `reactiveCover` | `boolean` | `true` | Enable reactive effects |
-| `variant` | `VisualizationVariant` | - | Effect variant |
-| `intensity` | `EffectIntensity` | - | Effect intensity |
-| `colorScheme` | `EffectColorScheme` | - | Effect colors |
+| `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 |
 
-> **Note:** The `prefetch` option is enabled by default. This fetches the entire audio file as a blob before loading into WaveSurfer, which is required for seeking to work correctly with streaming URLs. For very large files (> 50MB), consider using `prefetch={false}` and the Progressive player mode instead.
-
 ---
 
 ## Advanced Usage
 
-For full control, use `AudioProvider` + `AudioPlayer` directly:
+### Using HybridAudioProvider + HybridAudioPlayer
 
-```tsx
-import { useRef } from 'react';
-import { AudioProvider, AudioPlayer } from '@djangocfg/ui-nextjs';
+For full control over the hybrid player:
 
-function MyAudioPlayer({ audioUrl }: { audioUrl: string }) {
-  const containerRef = useRef<HTMLDivElement>(null);
+```tsx
+import { HybridAudioProvider, HybridAudioPlayer, useHybridAudioContext } from '@djangocfg/ui-nextjs';
 
+function MyPlayer({ audioUrl }: { audioUrl: string }) {
   return (
-    <AudioProvider
-      source={{ uri: audioUrl }}
-      containerRef={containerRef}
-    >
-      <AudioPlayer
-        ref={containerRef}
+    <HybridAudioProvider src={audioUrl}>
+      <HybridAudioPlayer
         showControls
         showWaveform
         showTimer
         showVolume
       />
-    </AudioProvider>
+      <CustomControls />
+    </HybridAudioProvider>
   );
 }
-```
-
-## Components
-
-### AudioProvider
 
-Context provider for audio state. Wraps all audio components.
+function CustomControls() {
+  const { state, controls, audioLevels } = useHybridAudioContext();
 
-```tsx
-<AudioProvider
-  source={{
-    uri: 'https://example.com/audio.mp3',
-    prefetch: true  // Fetch as blob for seek support (default: false)
-  }}
-  containerRef={containerRef}
-  autoPlay={false}
-  waveformOptions={{
-    waveColor: 'hsl(217 91% 60% / 0.3)',
-    progressColor: 'hsl(217 91% 60%)',
-    height: 64,
-    barWidth: 3,
-    barRadius: 3,
-    barGap: 2,
-  }}
->
-  {children}
-</AudioProvider>
+  return (
+    <div>
+      <p>Playing: {state.isPlaying ? 'Yes' : 'No'}</p>
+      <p>Bass level: {(audioLevels.bass * 100).toFixed(0)}%</p>
+      <button onClick={controls.togglePlay}>
+        {state.isPlaying ? 'Pause' : 'Play'}
+      </button>
+    </div>
+  );
+}
 ```
 
-#### AudioSource Options
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `uri` | `string` | required | Audio URL |
-| `prefetch` | `boolean` | `false` | Pre-fetch as blob (enables seek for streaming URLs) |
+### Hybrid Hooks
 
-### AudioPlayer
-
-Main player component with waveform and controls.
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `showControls` | `boolean` | `true` | Show playback controls |
-| `showWaveform` | `boolean` | `true` | Show waveform visualization |
-| `showEqualizer` | `boolean` | `false` | Show equalizer animation |
-| `showTimer` | `boolean` | `true` | Show time display |
-| `showVolume` | `boolean` | `true` | Show volume slider |
-| `className` | `string` | - | Additional CSS class |
-
-### AudioEqualizer
+#### useHybridAudioContext
 
-Real-time frequency visualizer with animated bars.
+Full access to audio state, controls, and Web Audio API:
 
 ```tsx
-<AudioEqualizer
-  barCount={24}
-  height={48}
-  gap={2}
-  showPeaks
-  barColor="hsl(217 91% 60%)"
-  peakColor="hsl(217 91% 70%)"
-/>
+const {
+  state,       // { isReady, isPlaying, currentTime, duration, volume, isMuted, isLooping, buffered }
+  controls,    // { play, pause, togglePlay, seek, seekTo, skip, setVolume, toggleMute, toggleLoop, restart }
+  audioLevels, // { bass, mid, high, overall } - for reactive effects
+  webAudio,    // { context, analyser, sourceNode } - for custom visualizations
+  audioRef,    // React ref to HTMLAudioElement
+} = useHybridAudioContext();
 ```
 
-### AudioReactiveCover
-
-Album art wrapper with audio-reactive effects.
+#### Specialized Hooks
 
 ```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>
-```
+// State only (read-only)
+const { isPlaying, currentTime, duration } = useHybridAudioState();
 
-### VisualizationToggle
+// Controls only (no re-render on time updates)
+const { play, pause, togglePlay, seek } = useHybridAudioControls();
 
-Button to cycle through visualization variants.
+// Audio levels for reactive effects
+const { bass, mid, high, overall } = useHybridAudioLevels();
 
-```tsx
-<VisualizationToggle compact />
+// Web Audio API access
+const { context, analyser, sourceNode } = useHybridWebAudio();
 ```
 
-## Hooks
+---
 
-### useAudio
+## WaveSurfer-based Player (Legacy)
 
-Access full audio state and controls.
+For cases where you need the static waveform visualization:
 
 ```tsx
-const {
-  isReady,
-  isPlaying,
-  currentTime,
-  duration,
-  volume,
-  isMuted,
-  audioLevels,  // { bass, mid, high, overall }
-  play,
-  pause,
-  togglePlay,
-  seek,
-  seekTo,
-  skip,
-  setVolume,
-  toggleMute,
-  restart,
-} = useAudio();
-```
-
-### useAudioControls
-
-Controls only (no re-render on time updates).
+import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
 
-```tsx
-const { play, pause, togglePlay, skip, restart } = useAudioControls();
+<SimpleAudioPlayer
+  src={audioUrl}
+  prefetch={true}  // Required for streaming URLs
+  title="Track Title"
+  showWaveform
+  reactiveCover
+/>
 ```
 
-### useAudioState
+> **Note:** `prefetch={true}` downloads the entire file before playing. For large files or streaming, use `HybridSimplePlayer` instead.
 
-Read-only playback state.
+---
 
-```tsx
-const { isPlaying, currentTime, duration, volume } = useAudioState();
-```
+## Components
 
-### useAudioElement
+### HybridWaveform
 
-Access audio element for custom visualizations.
+Real-time frequency visualization canvas:
 
 ```tsx
-const { audioElement, isPlaying, audioLevels } = useAudioElement();
+<HybridWaveform
+  mode="frequency"           // 'frequency' | 'static'
+  height={64}
+  barWidth={3}
+  barGap={2}
+  barRadius={2}
+  progressColor="hsl(217 91% 60%)"
+  waveColor="hsl(217 91% 60% / 0.3)"
+  bufferedColor="hsl(217 91% 60% / 0.15)"
+  onSeek={(time) => console.log('Seeked to', time)}
+/>
 ```
 
-### useAudioVisualization
+### AudioReactiveCover
 
-Manage visualization settings (persisted in localStorage).
+Album art wrapper with audio-reactive effects:
 
 ```tsx
-const {
-  settings,      // { enabled, variant, intensity, colorScheme }
-  toggle,
-  setSetting,
-  nextVariant,
-  nextIntensity,
-  nextColorScheme,
-  reset,
-} = useAudioVisualization();
+<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>
 ```
 
-### useAudioHotkeys
+### AudioEqualizer
 
-Enable keyboard shortcuts.
+Real-time frequency visualizer with animated bars:
 
 ```tsx
-useAudioHotkeys({
-  enabled: true,
-  skipDuration: 10,
-  volumeStep: 0.1,
-});
+<AudioEqualizer
+  barCount={24}
+  height={48}
+  gap={2}
+  showPeaks
+  barColor="hsl(217 91% 60%)"
+  peakColor="hsl(217 91% 70%)"
+/>
 ```
 
+---
+
 ## Keyboard Shortcuts
 
 | Key | Action |
@@ -271,21 +232,14 @@ useAudioHotkeys({
 | `M` | Mute/Unmute |
 | `0-9` | Jump to 0-90% |
 
-## Waveform Options
-
-```typescript
-interface WaveformOptions {
-  waveColor?: string;      // Unplayed wave color
-  progressColor?: string;  // Played wave color
-  cursorColor?: string;    // Playhead cursor color
-  cursorWidth?: number;    // Cursor width in px
-  height?: number;         // Waveform height in px
-  barWidth?: number;       // Bar width in px
-  barRadius?: number;      // Bar corner radius
-  barGap?: number;         // Gap between bars
-}
+Enable with:
+
+```tsx
+useAudioHotkeys({ enabled: true, skipDuration: 10, volumeStep: 0.1 });
 ```
 
+---
+
 ## Effect Variants
 
 | Variant | Description |
@@ -296,45 +250,63 @@ interface WaveformOptions {
 | `mesh` | Large gradient blobs with movement |
 | `none` | Effects disabled |
 
+---
+
 ## Architecture
 
 ```
 AudioPlayer/
 ├── index.ts                       # Public API exports
-├── types/
-│   ├── index.ts                   # Type re-exports
-│   ├── audio.ts                   # Audio state & source types
-│   ├── components.ts              # Component prop types
-│   └── effects.ts                 # Visualization effect types
+├── types/                         # TypeScript types
 ├── hooks/
-│   ├── index.ts
-│   ├── useAudioSource.ts          # Audio source loading with prefetch
-│   ├── useAudioHotkeys.ts         # Keyboard shortcuts
-│   ├── useVisualization.tsx       # Visualization settings
+│   ├── useHybridAudio.ts          # 🆕 HTML5 audio + Web Audio hook
+│   ├── useHybridAudioAnalysis.ts  # 🆕 Frequency analysis for hybrid
+│   ├── useSharedWebAudio.ts       # Shared AudioContext (WaveSurfer)
 │   ├── useAudioAnalysis.ts        # Web Audio frequency analysis
-│   └── useSharedWebAudio.ts       # Shared AudioContext
-├── utils/
-│   ├── index.ts
-│   └── formatTime.ts              # Time formatting
+│   ├── useAudioHotkeys.ts         # Keyboard shortcuts
+│   └── useVisualization.tsx       # Visualization settings
 ├── context/
-│   ├── index.ts
-│   ├── AudioProvider.tsx          # Audio state provider
-│   └── selectors.ts               # useAudio, useAudioControls hooks
+│   ├── HybridAudioProvider.tsx    # 🆕 Hybrid audio context
+│   ├── AudioProvider.tsx          # WaveSurfer context
+│   └── selectors.ts               # Hook selectors
 ├── components/
-│   ├── index.ts
-│   ├── AudioPlayer.tsx            # Main player component
-│   ├── SimpleAudioPlayer.tsx      # All-in-one wrapper
+│   ├── HybridAudioPlayer.tsx      # 🆕 Main hybrid player
+│   ├── HybridSimplePlayer.tsx     # 🆕 All-in-one hybrid wrapper
+│   ├── HybridWaveform.tsx         # 🆕 Frequency visualization
+│   ├── AudioPlayer.tsx            # WaveSurfer player
+│   ├── SimpleAudioPlayer.tsx      # WaveSurfer wrapper
 │   ├── AudioEqualizer.tsx         # Frequency bars
-│   ├── AudioShortcutsPopover.tsx  # Shortcuts help
-│   ├── VisualizationToggle.tsx    # Effect toggle button
-│   └── ReactiveCover/
-│       ├── index.ts
-│       ├── AudioReactiveCover.tsx # Reactive album art
-│       └── effects/               # Effect components
-│           ├── GlowEffect.tsx
-│           ├── OrbsEffect.tsx
-│           ├── SpotlightEffect.tsx
-│           └── MeshEffect.tsx
-└── effects/
-    └── index.ts                   # Effect calculations
+│   └── ReactiveCover/             # Reactive effects
+├── progressive/                   # Progressive/streaming player
+└── effects/                       # Effect calculations
 ```
+
+---
+
+## Migration Guide
+
+### From SimpleAudioPlayer to HybridSimplePlayer
+
+```tsx
+// Before
+<SimpleAudioPlayer
+  src={url}
+  prefetch={true}
+  showWaveform
+  reactiveCover
+  variant="spotlight"
+/>
+
+// After
+<HybridSimplePlayer
+  src={url}
+  showWaveform
+  reactiveCover
+  variant="spotlight"
+/>
+```
+
+Key differences:
+- No `prefetch` prop needed — streaming works natively
+- `waveformMode="frequency"` shows real-time bars instead of static waveform
+- Same reactive effects support

package/src/tools/AudioPlayer/components/AudioPlayer.tsx

@@ -1,11 +1,16 @@
 'use client';
 
 /**
- * AudioPlayer - Audio playback controls and waveform display
+ * AudioPlayer - WaveSurfer-based player component (Legacy)
  *
- * Uses AudioContext for state management
- * Renders waveform (via container ref), controls, timer, and equalizer
- * Supports keyboard shortcuts for playback control
+ * @deprecated Consider using `HybridAudioPlayer` instead for better streaming
+ * support and guaranteed no audio crackling.
+ *
+ * Uses AudioContext for state management.
+ * Renders waveform (via container ref), controls, timer, and equalizer.
+ * Supports keyboard shortcuts for playback control.
+ *
+ * @see HybridAudioPlayer for the recommended alternative
  */
 
 import { forwardRef } from 'react';