@djangocfg/ui-nextjs 2.1.82 → 2.1.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.82",
+  "version": "2.1.84",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -58,8 +58,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.82",
-    "@djangocfg/ui-core": "^2.1.82",
+    "@djangocfg/api": "^2.1.84",
+    "@djangocfg/ui-core": "^2.1.84",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -110,7 +110,7 @@
     "wavesurfer.js": "^7.12.1"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.82",
+    "@djangocfg/typescript-config": "^2.1.84",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

package/src/tools/AudioPlayer/README.md

@@ -1,289 +1,172 @@
 # AudioPlayer
 
-Audio player with waveform visualization, built on WaveSurfer.js.
+Audio player with native HTML5 streaming and audio-reactive visualizations.
 
 ## Features
 
-- Waveform visualization with interactive seeking
+- 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)
-- Real-time frequency equalizer
-- Keyboard shortcuts
-- Volume control with mute
-- Skip forward/backward
-- Playback speed control
+- Frequency visualization waveform
+- Full playback controls
 
-## Quick Start (Recommended)
+## Quick Start
 
 ```tsx
-import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
+import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
 
-// Minimal
-<SimpleAudioPlayer src="https://example.com/audio.mp3" />
+// Simple usage
+<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}
+  waveformMode="frequency"  // 'frequency' | 'static'
+  showLoop
   reactiveCover
-  variant="spotlight"
-  layout="horizontal"
+  variant="spotlight"       // 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none'
+  intensity="medium"        // 'subtle' | 'medium' | 'strong'
+  colorScheme="primary"     // 'primary' | 'vibrant' | 'cool' | 'warm'
+  layout="horizontal"       // 'vertical' | 'horizontal'
 />
 ```
 
-### SimpleAudioPlayer Props
+## 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 |
+| `showLoop` | `boolean` | `true` | Show loop 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:
+### HybridAudioProvider + HybridAudioPlayer
+
+For custom layouts:
 
 ```tsx
-import { useRef } from 'react';
-import { AudioProvider, AudioPlayer } from '@djangocfg/ui-nextjs';
+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 MyAudioPlayer({ audioUrl }: { audioUrl: string }) {
-  const containerRef = useRef<HTMLDivElement>(null);
+function CustomControls() {
+  const { state, controls, audioLevels } = useHybridAudioContext();
 
   return (
-    <AudioProvider
-      source={{ uri: audioUrl }}
-      containerRef={containerRef}
-    >
-      <AudioPlayer
-        ref={containerRef}
-        showControls
-        showWaveform
-        showTimer
-        showVolume
-      />
-    </AudioProvider>
+    <div>
+      <p>Bass level: {(audioLevels.bass * 100).toFixed(0)}%</p>
+      <button onClick={controls.togglePlay}>
+        {state.isPlaying ? 'Pause' : 'Play'}
+      </button>
+    </div>
   );
 }
 ```
 
-## Components
+## Hooks
 
-### AudioProvider
+### useHybridAudioContext
 
-Context provider for audio state. Wraps all audio components.
+Full context access:
 
 ```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>
+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();
 ```
 
-#### AudioSource Options
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `uri` | `string` | required | Audio URL |
-| `prefetch` | `boolean` | `false` | Pre-fetch as blob (enables seek for streaming URLs) |
-
-### AudioPlayer
+### Specialized Hooks
 
-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 |
+```tsx
+// State only
+const { isPlaying, currentTime, duration } = useHybridAudioState();
 
-### AudioEqualizer
+// Controls only (no re-render on time updates)
+const { play, pause, togglePlay, seek } = useHybridAudioControls();
 
-Real-time frequency visualizer with animated bars.
+// Audio levels for reactive effects
+const { bass, mid, high, overall } = useHybridAudioLevels();
 
-```tsx
-<AudioEqualizer
-  barCount={24}
-  height={48}
-  gap={2}
-  showPeaks
-  barColor="hsl(217 91% 60%)"
-  peakColor="hsl(217 91% 70%)"
-/>
+// Web Audio API access
+const { context, analyser, sourceNode } = useHybridWebAudio();
 ```
 
+## Components
+
 ### AudioReactiveCover
 
-Album art wrapper with audio-reactive effects.
+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'
+  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>
 ```
 
-### VisualizationToggle
-
-Button to cycle through visualization variants.
-
-```tsx
-<VisualizationToggle compact />
-```
-
-## Hooks
-
-### useAudio
+### HybridWaveform
 
-Access full audio state and controls.
+Real-time frequency 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).
-
-```tsx
-const { play, pause, togglePlay, skip, restart } = useAudioControls();
-```
-
-### useAudioState
-
-Read-only playback state.
-
-```tsx
-const { isPlaying, currentTime, duration, volume } = useAudioState();
-```
-
-### useAudioElement
-
-Access audio element for custom visualizations.
-
-```tsx
-const { audioElement, isPlaying, audioLevels } = useAudioElement();
-```
-
-### useAudioVisualization
-
-Manage visualization settings (persisted in localStorage).
-
-```tsx
-const {
-  settings,      // { enabled, variant, intensity, colorScheme }
-  toggle,
-  setSetting,
-  nextVariant,
-  nextIntensity,
-  nextColorScheme,
-  reset,
-} = useAudioVisualization();
-```
-
-### useAudioHotkeys
-
-Enable keyboard shortcuts.
-
-```tsx
-useAudioHotkeys({
-  enabled: true,
-  skipDuration: 10,
-  volumeStep: 0.1,
-});
-```
-
-## Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `Space` | Play/Pause |
-| `←` / `J` | Skip 10s backward |
-| `→` / `L` | Skip 10s forward |
-| `↑` | Volume up |
-| `↓` | Volume down |
-| `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
-}
+<HybridWaveform
+  mode="frequency"  // 'frequency' | 'static'
+  height={64}
+  barWidth={3}
+  barGap={2}
+/>
 ```
 
 ## Effect Variants
@@ -301,40 +184,23 @@ interface WaveformOptions {
 ```
 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
-│   ├── useAudioAnalysis.ts        # Web Audio frequency analysis
-│   └── useSharedWebAudio.ts       # Shared AudioContext
-├── utils/
-│   ├── index.ts
-│   └── formatTime.ts              # Time formatting
+│   ├── useHybridAudio.ts          # HTML5 audio + Web Audio hook
+│   ├── useHybridAudioAnalysis.ts  # Frequency analysis
+│   └── useVisualization.tsx       # Visualization settings
 ├── context/
-│   ├── index.ts
-│   ├── AudioProvider.tsx          # Audio state provider
-│   └── selectors.ts               # useAudio, useAudioControls hooks
+│   └── HybridAudioProvider.tsx    # Audio context provider
 ├── components/
-│   ├── index.ts
-│   ├── AudioPlayer.tsx            # Main player component
-│   ├── SimpleAudioPlayer.tsx      # All-in-one 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
+│   ├── HybridAudioPlayer.tsx      # Main player component
+│   ├── HybridSimplePlayer.tsx     # All-in-one wrapper
+│   ├── 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)

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

@@ -0,0 +1,216 @@
+'use client';
+
+/**
+ * HybridAudioPlayer - Audio playback controls with frequency visualization
+ *
+ * Uses HybridAudioContext for state management.
+ * Native HTML5 audio for playback, Web Audio API for visualization only.
+ *
+ * Features:
+ * - Real-time frequency visualization
+ * - Playback controls (play, pause, skip, restart)
+ * - Volume control with mute
+ * - Loop toggle
+ * - Keyboard shortcuts
+ * - Timer display
+ */
+
+import { memo } from 'react';
+import {
+  Play,
+  Pause,
+  RotateCcw,
+  SkipBack,
+  SkipForward,
+  Volume2,
+  VolumeX,
+  Loader2,
+  Repeat,
+} from 'lucide-react';
+import { Button, Slider, cn } from '@djangocfg/ui-nextjs';
+import { useHybridAudioContext } from '../context/HybridAudioProvider';
+import { HybridWaveform } from './HybridWaveform';
+import { formatTime } from '../utils';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridAudioPlayerProps {
+  /** Show playback controls */
+  showControls?: boolean;
+  /** Show frequency waveform */
+  showWaveform?: boolean;
+  /** Waveform visualization mode */
+  waveformMode?: 'frequency' | 'static';
+  /** Waveform height in pixels */
+  waveformHeight?: number;
+  /** Show time display */
+  showTimer?: boolean;
+  /** Show volume control */
+  showVolume?: boolean;
+  /** Show loop button */
+  showLoop?: boolean;
+  /** Additional CSS class */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export const HybridAudioPlayer = memo(function HybridAudioPlayer({
+  showControls = true,
+  showWaveform = true,
+  waveformMode = 'frequency',
+  waveformHeight = 64,
+  showTimer = true,
+  showVolume = true,
+  showLoop = true,
+  className,
+  style,
+}: HybridAudioPlayerProps) {
+  const { state, controls } = useHybridAudioContext();
+
+  const isLoading = !state.isReady;
+
+  const handleVolumeChange = (value: number[]) => {
+    controls.setVolume(value[0] / 100);
+  };
+
+  return (
+    <div
+      className={cn('flex flex-col gap-3 p-4 rounded-lg bg-card border', className)}
+      style={style}
+    >
+      {/* Frequency Waveform */}
+      {showWaveform && (
+        <div className="relative">
+          <HybridWaveform
+            mode={waveformMode}
+            height={waveformHeight}
+            className={cn(isLoading && 'opacity-50')}
+          />
+          {isLoading && (
+            <div className="absolute inset-0 flex items-center justify-center">
+              <Loader2 className="h-6 w-6 animate-spin text-primary" />
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Timer */}
+      {showTimer && (
+        <div className="flex justify-between text-xs text-muted-foreground tabular-nums px-1">
+          <span>{formatTime(state.currentTime)}</span>
+          <span>{formatTime(state.duration)}</span>
+        </div>
+      )}
+
+      {/* Controls */}
+      {showControls && (
+        <div className="flex items-center justify-center gap-1">
+          {/* Restart */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={controls.restart}
+            disabled={!state.isReady}
+            title="Restart"
+          >
+            <RotateCcw className="h-4 w-4" />
+          </Button>
+
+          {/* Skip back 5s */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={() => controls.skip(-5)}
+            disabled={!state.isReady}
+            title="Back 5 seconds"
+          >
+            <SkipBack className="h-4 w-4" />
+          </Button>
+
+          {/* Play/Pause */}
+          <Button
+            variant="default"
+            size="icon"
+            className="h-12 w-12 rounded-full"
+            onClick={controls.togglePlay}
+            disabled={!state.isReady && !isLoading}
+            title={state.isPlaying ? 'Pause' : 'Play'}
+          >
+            {isLoading ? (
+              <Loader2 className="h-5 w-5 animate-spin" />
+            ) : state.isPlaying ? (
+              <Pause className="h-5 w-5" />
+            ) : (
+              <Play className="h-5 w-5 ml-0.5" />
+            )}
+          </Button>
+
+          {/* Skip forward 5s */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={() => controls.skip(5)}
+            disabled={!state.isReady}
+            title="Forward 5 seconds"
+          >
+            <SkipForward className="h-4 w-4" />
+          </Button>
+
+          {/* Volume */}
+          {showVolume && (
+            <>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-9 w-9"
+                onClick={controls.toggleMute}
+                title={state.isMuted ? 'Unmute' : 'Mute'}
+              >
+                {state.isMuted || state.volume === 0 ? (
+                  <VolumeX className="h-4 w-4" />
+                ) : (
+                  <Volume2 className="h-4 w-4" />
+                )}
+              </Button>
+
+              <Slider
+                value={[state.isMuted ? 0 : state.volume * 100]}
+                max={100}
+                step={1}
+                onValueChange={handleVolumeChange}
+                className="w-20"
+                aria-label="Volume"
+              />
+            </>
+          )}
+
+          {/* Loop/Repeat */}
+          {showLoop && (
+            <Button
+              variant="ghost"
+              size="icon"
+              className={cn('h-9 w-9', state.isLooping && 'text-primary')}
+              onClick={controls.toggleLoop}
+              disabled={!state.isReady}
+              title={state.isLooping ? 'Disable loop' : 'Enable loop'}
+            >
+              <Repeat className="h-4 w-4" />
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+});
+
+export default HybridAudioPlayer;