@djangocfg/ui-tools 2.1.91

package/src/tools/AudioPlayer/README.md

@@ -0,0 +1,206 @@
+# 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 } from '@djangocfg/ui-nextjs';
+
+// Simple usage
+<HybridSimplePlayer src="https://example.com/audio.mp3" />
+
+// 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>
+```
+
+### 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
+│   ├── 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 '../../_shared';
+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;

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

@@ -0,0 +1,280 @@
+'use client';
+
+/**
+ * HybridSimplePlayer - Easy-to-use hybrid audio player wrapper
+ *
+ * Combines HybridAudioProvider + HybridAudioPlayer + optional reactive cover
+ * in a single component with sensible defaults.
+ *
+ * Uses native HTML5 audio for playback (no crackling) with Web Audio API
+ * for visualization only.
+ *
+ * @example
+ * // Minimal usage
+ * <HybridSimplePlayer src="https://example.com/audio.mp3" />
+ *
+ * @example
+ * // With cover art and reactive effects
+ * <HybridSimplePlayer
+ *   src={audioUrl}
+ *   title="Track Title"
+ *   artist="Artist Name"
+ *   coverArt="/path/to/cover.jpg"
+ *   reactiveCover
+ *   variant="spotlight"
+ * />
+ */
+
+import { type ReactNode } from 'react';
+import { Music } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core';
+
+import { HybridAudioProvider } from '../context/HybridAudioProvider';
+import { HybridAudioPlayer } from './HybridAudioPlayer';
+import { AudioReactiveCover } from './ReactiveCover';
+import { VisualizationProvider, useVisualization } from '../hooks';
+import type { EffectIntensity, EffectColorScheme } from '../effects';
+import type { VisualizationVariant } from '../hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridSimplePlayerProps {
+  /** Audio source URL */
+  src: string;
+
+  /** Track title */
+  title?: string;
+
+  /** Artist name */
+  artist?: string;
+
+  /** Cover art URL or ReactNode */
+  coverArt?: string | ReactNode;
+
+  /** Cover art size */
+  coverSize?: 'sm' | 'md' | 'lg';
+
+  /** Show frequency waveform */
+  showWaveform?: boolean;
+
+  /** Waveform visualization mode */
+  waveformMode?: 'frequency' | 'static';
+
+  /** Waveform height in pixels */
+  waveformHeight?: number;
+
+  /** Show timer */
+  showTimer?: boolean;
+
+  /** Show volume control */
+  showVolume?: boolean;
+
+  /** Show loop/repeat button */
+  showLoop?: boolean;
+
+  /** Enable audio-reactive cover effects */
+  reactiveCover?: boolean;
+
+  /** Reactive effect variant */
+  variant?: VisualizationVariant;
+
+  /** Reactive effect intensity */
+  intensity?: EffectIntensity;
+
+  /** Reactive effect color scheme */
+  colorScheme?: EffectColorScheme;
+
+  /** Auto-play on load */
+  autoPlay?: boolean;
+
+  /** Loop playback */
+  loop?: boolean;
+
+  /** Initial volume (0-1) */
+  initialVolume?: number;
+
+  /** Layout direction */
+  layout?: 'vertical' | 'horizontal';
+
+  /** Additional class name */
+  className?: string;
+
+  /** Callbacks */
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onError?: (error: Error) => void;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const COVER_SIZES = {
+  sm: 'w-24 h-24',
+  md: 'w-32 h-32',
+  lg: 'w-48 h-48',
+};
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function HybridSimplePlayer(props: HybridSimplePlayerProps) {
+  return (
+    <VisualizationProvider>
+      <HybridSimplePlayerContent {...props} />
+    </VisualizationProvider>
+  );
+}
+
+function HybridSimplePlayerContent({
+  src,
+  title,
+  artist,
+  coverArt,
+  coverSize = 'md',
+  showWaveform = true,
+  waveformMode = 'frequency',
+  waveformHeight = 64,
+  showTimer = true,
+  showVolume = true,
+  showLoop = true,
+  reactiveCover = true,
+  variant,
+  intensity,
+  colorScheme,
+  autoPlay = false,
+  loop = false,
+  initialVolume = 1,
+  layout = 'vertical',
+  className,
+  onPlay,
+  onPause,
+  onEnded,
+  onError,
+}: HybridSimplePlayerProps) {
+  const { settings: vizSettings, nextVariant } = useVisualization();
+
+  // Determine effective variant (from props or localStorage settings)
+  const effectiveVariant =
+    variant ?? (vizSettings.variant !== 'none' ? vizSettings.variant : 'spotlight');
+  const effectiveIntensity = intensity ?? vizSettings.intensity;
+  const effectiveColorScheme = colorScheme ?? vizSettings.colorScheme;
+
+  // Show reactive cover if enabled and variant is not 'none'
+  const showReactiveCover = reactiveCover && effectiveVariant !== 'none';
+
+  // Render cover art content
+  const renderCoverContent = () => {
+    if (typeof coverArt === 'string') {
+      return (
+        <img src={coverArt} alt={title || 'Album cover'} className="w-full h-full object-cover" />
+      );
+    }
+
+    if (coverArt) {
+      return coverArt;
+    }
+
+    // Default placeholder
+    return (
+      <div className="w-full h-full bg-muted/30 flex items-center justify-center">
+        <Music className="w-1/3 h-1/3 text-muted-foreground/50" />
+      </div>
+    );
+  };
+
+  const isHorizontal = layout === 'horizontal';
+
+  return (
+    <HybridAudioProvider
+      src={src}
+      autoPlay={autoPlay}
+      loop={loop}
+      initialVolume={initialVolume}
+      onPlay={onPlay}
+      onPause={onPause}
+      onEnded={onEnded}
+      onError={onError}
+    >
+      <div
+        className={cn(
+          'flex gap-4',
+          isHorizontal ? 'flex-row items-center' : 'flex-col items-center',
+          className
+        )}
+      >
+        {/* Cover Art */}
+        {(coverArt || reactiveCover) && (
+          <div className="flex flex-col items-center gap-2 shrink-0">
+            {showReactiveCover ? (
+              <AudioReactiveCover
+                size={coverSize}
+                variant={effectiveVariant as 'glow' | 'orbs' | 'spotlight' | 'mesh'}
+                intensity={effectiveIntensity}
+                colorScheme={effectiveColorScheme}
+                onClick={nextVariant}
+              >
+                <div className={cn('rounded-lg overflow-hidden', COVER_SIZES[coverSize])}>
+                  {renderCoverContent()}
+                </div>
+              </AudioReactiveCover>
+            ) : (
+              <div
+                className={cn(
+                  'rounded-lg overflow-hidden shadow-lg cursor-pointer',
+                  COVER_SIZES[coverSize]
+                )}
+                onClick={nextVariant}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => e.key === 'Enter' && nextVariant()}
+              >
+                {renderCoverContent()}
+              </div>
+            )}
+
+            {/* Effect indicator */}
+            {reactiveCover && (
+              <span className="text-[10px] uppercase tracking-wider text-muted-foreground/50 select-none">
+                {vizSettings.variant === 'none' ? 'off' : vizSettings.variant}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Track Info + Player */}
+        <div
+          className={cn('flex flex-col gap-3', isHorizontal ? 'flex-1 min-w-0' : 'w-full max-w-md')}
+        >
+          {/* Track Info */}
+          {(title || artist) && (
+            <div className={cn('text-center', isHorizontal && 'text-left')}>
+              {title && (
+                <h3 className="text-base font-medium text-foreground truncate">{title}</h3>
+              )}
+              {artist && <p className="text-sm text-muted-foreground truncate">{artist}</p>}
+            </div>
+          )}
+
+          {/* Audio Player */}
+          <HybridAudioPlayer
+            showControls
+            showWaveform={showWaveform}
+            waveformMode={waveformMode}
+            waveformHeight={waveformHeight}
+            showTimer={showTimer}
+            showVolume={showVolume}
+            showLoop={showLoop}
+            className="border-0 bg-transparent"
+          />
+        </div>
+      </div>
+    </HybridAudioProvider>
+  );
+}
+
+export default HybridSimplePlayer;