@djangocfg/ui-nextjs 2.1.82 → 2.1.83

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

@@ -0,0 +1,279 @@
+'use client';
+
+/**
+ * HybridWaveform - Real-time frequency visualization for hybrid player.
+ *
+ * Two modes:
+ * - 'frequency': Real-time frequency bars (default, requires playing audio)
+ * - 'static': Static progress bar (for when no analyser is available)
+ *
+ * Features:
+ * - Shows buffered regions
+ * - Click to seek
+ * - Responsive width
+ */
+
+import { useRef, useEffect, useCallback, memo } from 'react';
+import { useHybridAudioContext } from '../context/HybridAudioProvider';
+import { cn } from '@djangocfg/ui-core/lib';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridWaveformProps {
+  /** Visualization mode */
+  mode?: 'frequency' | 'static';
+  /** Canvas height in pixels */
+  height?: number;
+  /** Bar width in pixels */
+  barWidth?: number;
+  /** Gap between bars in pixels */
+  barGap?: number;
+  /** Bar border radius */
+  barRadius?: number;
+  /** Color for played portion */
+  progressColor?: string;
+  /** Color for unplayed portion */
+  waveColor?: string;
+  /** Color for buffered regions indicator */
+  bufferedColor?: string;
+  /** Additional CSS class */
+  className?: string;
+  /** Callback when user seeks */
+  onSeek?: (time: number) => void;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export const HybridWaveform = memo(function HybridWaveform({
+  mode = 'frequency',
+  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)',
+  className,
+  onSeek,
+}: HybridWaveformProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const animationRef = useRef<number | null>(null);
+  const { state, controls, webAudio } = useHybridAudioContext();
+
+  // Handle click to seek
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLCanvasElement>) => {
+      const canvas = canvasRef.current;
+      if (!canvas || !state.duration) return;
+
+      const rect = canvas.getBoundingClientRect();
+      const x = e.clientX - rect.left;
+      const progress = x / rect.width;
+      const time = state.duration * progress;
+
+      controls.seek(time);
+      onSeek?.(time);
+    },
+    [state.duration, controls, onSeek]
+  );
+
+  // Render frequency bars (real-time visualization)
+  const renderFrequency = useCallback(() => {
+    const canvas = canvasRef.current;
+    const analyser = webAudio.analyser;
+    if (!canvas) return;
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    const { width, height: canvasHeight } = canvas;
+    const dpr = window.devicePixelRatio || 1;
+    const displayWidth = width / dpr;
+
+    // Get frequency data if analyser is available
+    let dataArray: Uint8Array<ArrayBuffer> | null = null;
+    if (analyser) {
+      dataArray = new Uint8Array(analyser.frequencyBinCount) as Uint8Array<ArrayBuffer>;
+      analyser.getByteFrequencyData(dataArray);
+    }
+
+    ctx.clearRect(0, 0, width, canvasHeight);
+
+    // Draw buffered regions at bottom
+    if (state.buffered && state.duration > 0) {
+      ctx.fillStyle = bufferedColor;
+      for (let i = 0; i < state.buffered.length; i++) {
+        const start = (state.buffered.start(i) / state.duration) * width;
+        const end = (state.buffered.end(i) / state.duration) * width;
+        ctx.fillRect(start, canvasHeight - 3 * dpr, end - start, 3 * dpr);
+      }
+    }
+
+    // Calculate bar count based on available width
+    const barCount = Math.floor(displayWidth / (barWidth + barGap));
+    const progress = state.duration > 0 ? state.currentTime / state.duration : 0;
+    const progressX = width * progress;
+
+    // Draw bars
+    for (let i = 0; i < barCount; i++) {
+      let barHeight: number;
+
+      if (dataArray && state.isPlaying) {
+        // Real-time frequency data
+        const step = Math.floor(dataArray.length / barCount);
+        const value = dataArray[i * step] / 255;
+        barHeight = Math.max(4 * dpr, value * (canvasHeight - 6 * dpr) * 0.9);
+      } else {
+        // Static fallback - small bars
+        barHeight = 8 * dpr;
+      }
+
+      const x = i * (barWidth + barGap) * dpr;
+      const y = (canvasHeight - barHeight) / 2;
+
+      ctx.fillStyle = x < progressX ? progressColor : waveColor;
+
+      // Draw rounded rect
+      const radius = barRadius * dpr;
+      const rectWidth = barWidth * dpr;
+      ctx.beginPath();
+      ctx.roundRect(x, y, rectWidth, barHeight, radius);
+      ctx.fill();
+    }
+
+    // Continue animation if playing
+    if (state.isPlaying) {
+      animationRef.current = requestAnimationFrame(renderFrequency);
+    }
+  }, [
+    webAudio.analyser,
+    state.buffered,
+    state.duration,
+    state.currentTime,
+    state.isPlaying,
+    barWidth,
+    barGap,
+    barRadius,
+    progressColor,
+    waveColor,
+    bufferedColor,
+  ]);
+
+  // Render static progress bar
+  const renderStatic = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    const { width, height: canvasHeight } = canvas;
+    const dpr = window.devicePixelRatio || 1;
+
+    ctx.clearRect(0, 0, width, canvasHeight);
+
+    // Draw buffered regions
+    if (state.buffered && state.duration > 0) {
+      ctx.fillStyle = bufferedColor;
+      for (let i = 0; i < state.buffered.length; i++) {
+        const start = (state.buffered.start(i) / state.duration) * width;
+        const end = (state.buffered.end(i) / state.duration) * width;
+        ctx.fillRect(start, 0, end - start, canvasHeight);
+      }
+    }
+
+    // Draw progress bar
+    const progress = state.duration > 0 ? state.currentTime / state.duration : 0;
+    const progressWidth = width * progress;
+
+    // Background
+    ctx.fillStyle = waveColor;
+    ctx.fillRect(0, canvasHeight / 2 - 2 * dpr, width, 4 * dpr);
+
+    // Progress
+    ctx.fillStyle = progressColor;
+    ctx.fillRect(0, canvasHeight / 2 - 2 * dpr, progressWidth, 4 * dpr);
+
+    // Handle
+    if (progress > 0) {
+      ctx.beginPath();
+      ctx.arc(progressWidth, canvasHeight / 2, 6 * dpr, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }, [state.buffered, state.duration, state.currentTime, progressColor, waveColor, bufferedColor]);
+
+  // Resize canvas to match container
+  useEffect(() => {
+    const container = containerRef.current;
+    const canvas = canvasRef.current;
+    if (!container || !canvas) return;
+
+    const resizeObserver = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+
+      const dpr = window.devicePixelRatio || 1;
+      const displayWidth = entry.contentRect.width;
+      const displayHeight = height;
+
+      canvas.width = displayWidth * dpr;
+      canvas.height = displayHeight * dpr;
+      canvas.style.width = `${displayWidth}px`;
+      canvas.style.height = `${displayHeight}px`;
+
+      // Re-render after resize
+      if (mode === 'frequency') {
+        renderFrequency();
+      } else {
+        renderStatic();
+      }
+    });
+
+    resizeObserver.observe(container);
+    return () => resizeObserver.disconnect();
+  }, [height, mode, renderFrequency, renderStatic]);
+
+  // Animation loop for frequency mode
+  useEffect(() => {
+    if (mode === 'frequency') {
+      renderFrequency();
+    }
+
+    return () => {
+      if (animationRef.current) {
+        cancelAnimationFrame(animationRef.current);
+      }
+    };
+  }, [mode, renderFrequency]);
+
+  // Re-render on time change for static mode
+  useEffect(() => {
+    if (mode === 'static') {
+      renderStatic();
+    }
+  }, [mode, state.currentTime, renderStatic]);
+
+  // Re-render frequency when playback state changes
+  useEffect(() => {
+    if (mode === 'frequency' && !state.isPlaying) {
+      // One final render when stopped
+      renderFrequency();
+    }
+  }, [mode, state.isPlaying, renderFrequency]);
+
+  return (
+    <div ref={containerRef} className={cn('w-full', className)}>
+      <canvas
+        ref={canvasRef}
+        onClick={handleClick}
+        className="cursor-pointer"
+        style={{ width: '100%', height }}
+      />
+    </div>
+  );
+});

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

@@ -1,36 +1,26 @@
 'use client';
 
 /**
- * SimpleAudioPlayer - Easy-to-use audio player wrapper
+ * SimpleAudioPlayer - WaveSurfer-based audio player (Legacy)
  *
- * Combines AudioProvider + AudioPlayer + optional reactive cover
- * in a single component with sensible defaults.
+ * @deprecated Consider using `HybridSimplePlayer` instead for better streaming
+ * support, lower memory usage, and guaranteed no audio crackling.
  *
- * @example
- * // Minimal usage
- * <SimpleAudioPlayer src="https://example.com/audio.mp3" />
+ * Use SimpleAudioPlayer only when you specifically need the static waveform
+ * visualization that shows the full audio amplitude shape.
  *
- * @example
- * // With cover art
- * <SimpleAudioPlayer
- *   src={audioUrl}
- *   title="Track Title"
- *   artist="Artist Name"
- *   coverArt="/path/to/cover.jpg"
- * />
+ * Migration:
+ * ```tsx
+ * // Before
+ * <SimpleAudioPlayer src={url} prefetch reactiveCover />
  *
- * @example
- * // Full customization
- * <SimpleAudioPlayer
- *   src={audioUrl}
- *   title="Track Title"
- *   coverArt={coverUrl}
- *   showWaveform
- *   showEqualizer={false}
- *   reactiveCover
- *   variant="spotlight"
- *   autoPlay={false}
- * />
+ * // After
+ * <HybridSimplePlayer src={url} reactiveCover />
+ * ```
+ *
+ * Key differences:
+ * - HybridSimplePlayer: Real-time frequency bars, native streaming, no prefetch needed
+ * - SimpleAudioPlayer: Static waveform shape, requires prefetch for streaming URLs
  */
 
 import { useRef, type ReactNode } from 'react';

package/src/tools/AudioPlayer/components/index.ts

@@ -2,13 +2,18 @@
  * AudioPlayer components - Public API
  */
 
-// Main components
+// WaveSurfer-based components (original)
 export { AudioPlayer } from './AudioPlayer';
 export { SimpleAudioPlayer, type SimpleAudioPlayerProps } from './SimpleAudioPlayer';
 export { AudioEqualizer } from './AudioEqualizer';
 export { AudioShortcutsPopover } from './AudioShortcutsPopover';
 export { VisualizationToggle, type VisualizationToggleProps } from './VisualizationToggle';
 
+// Hybrid player components (HTML5 audio + Web Audio for visualization)
+export { HybridAudioPlayer, type HybridAudioPlayerProps } from './HybridAudioPlayer';
+export { HybridSimplePlayer, type HybridSimplePlayerProps } from './HybridSimplePlayer';
+export { HybridWaveform, type HybridWaveformProps } from './HybridWaveform';
+
 // ReactiveCover
 export {
   AudioReactiveCover,

package/src/tools/AudioPlayer/context/AudioProvider.tsx

@@ -1,10 +1,15 @@
 'use client';
 
 /**
- * AudioProvider - Shared audio state and controls
+ * AudioProvider - WaveSurfer-based audio context (Legacy)
  *
- * Provides centralized audio state management using WaveSurfer.js
- * All child components can access playback state and controls
+ * @deprecated Consider using `HybridAudioProvider` instead for better streaming
+ * support, lower memory usage, and guaranteed no audio crackling.
+ *
+ * Provides centralized audio state management using WaveSurfer.js.
+ * All child components can access playback state and controls.
+ *
+ * @see HybridAudioProvider for the recommended alternative
  */
 
 import {

package/src/tools/AudioPlayer/context/HybridAudioProvider.tsx

@@ -0,0 +1,121 @@
+'use client';
+
+/**
+ * HybridAudioProvider - Context provider for hybrid audio player.
+ *
+ * Provides audio state, controls, and analysis data to child components.
+ * Uses native HTML5 audio for playback with Web Audio API for visualization only.
+ */
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import {
+  useHybridAudio,
+  type UseHybridAudioOptions,
+  type HybridAudioState,
+  type HybridAudioControls,
+  type HybridWebAudioAPI,
+} from '../hooks/useHybridAudio';
+import { useHybridAudioAnalysis } from '../hooks/useHybridAudioAnalysis';
+import type { AudioLevels } from '../effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridAudioContextValue {
+  // Audio state
+  state: HybridAudioState;
+
+  // Controls
+  controls: HybridAudioControls;
+
+  // Web Audio (for visualizations)
+  webAudio: HybridWebAudioAPI;
+
+  // Audio levels (for reactive effects)
+  audioLevels: AudioLevels;
+
+  // Audio element ref (for custom integrations)
+  audioRef: React.RefObject<HTMLAudioElement | null>;
+}
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const HybridAudioContext = createContext<HybridAudioContextValue | null>(null);
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+export interface HybridAudioProviderProps extends UseHybridAudioOptions {
+  children: ReactNode;
+}
+
+export function HybridAudioProvider({ children, ...options }: HybridAudioProviderProps) {
+  const { audioRef, state, controls, webAudio } = useHybridAudio(options);
+
+  // Audio analysis for reactive effects
+  const audioLevels = useHybridAudioAnalysis(webAudio.analyser, state.isPlaying);
+
+  const value = useMemo<HybridAudioContextValue>(
+    () => ({
+      state,
+      controls,
+      webAudio,
+      audioLevels,
+      audioRef,
+    }),
+    [state, controls, webAudio, audioLevels, audioRef]
+  );
+
+  return <HybridAudioContext.Provider value={value}>{children}</HybridAudioContext.Provider>;
+}
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+/**
+ * Access full hybrid audio context
+ */
+export function useHybridAudioContext(): HybridAudioContextValue {
+  const context = useContext(HybridAudioContext);
+  if (!context) {
+    throw new Error('useHybridAudioContext must be used within HybridAudioProvider');
+  }
+  return context;
+}
+
+/**
+ * Access audio state only (read-only)
+ */
+export function useHybridAudioState(): HybridAudioState {
+  const { state } = useHybridAudioContext();
+  return state;
+}
+
+/**
+ * Access audio controls only (no state re-renders)
+ */
+export function useHybridAudioControls(): HybridAudioControls {
+  const { controls } = useHybridAudioContext();
+  return controls;
+}
+
+/**
+ * Access audio levels for reactive effects
+ */
+export function useHybridAudioLevels(): AudioLevels {
+  const { audioLevels } = useHybridAudioContext();
+  return audioLevels;
+}
+
+/**
+ * Access Web Audio API for custom visualizations
+ */
+export function useHybridWebAudio(): HybridWebAudioAPI {
+  const { webAudio } = useHybridAudioContext();
+  return webAudio;
+}

package/src/tools/AudioPlayer/context/index.ts

@@ -4,8 +4,20 @@
  * Re-exports provider and selector hooks
  */
 
-// Provider
+// WaveSurfer-based provider (original)
 export { AudioProvider, AudioPlayerContext } from './AudioProvider';
 
-// Selector hooks
+// Selector hooks for WaveSurfer provider
 export { useAudio, useAudioControls, useAudioState, useAudioElement } from './selectors';
+
+// Hybrid provider (HTML5 audio + Web Audio for visualization)
+export {
+  HybridAudioProvider,
+  useHybridAudioContext,
+  useHybridAudioState,
+  useHybridAudioControls,
+  useHybridAudioLevels,
+  useHybridWebAudio,
+  type HybridAudioContextValue,
+  type HybridAudioProviderProps,
+} from './HybridAudioProvider';

package/src/tools/AudioPlayer/hooks/index.ts

@@ -8,6 +8,17 @@ export { useAudioAnalysis } from './useAudioAnalysis';
 export { useAudioSource } from './useAudioSource';
 export type { UseAudioSourceResult } from './useAudioSource';
 
+// Hybrid player hooks
+export { useHybridAudio } from './useHybridAudio';
+export type {
+  UseHybridAudioOptions,
+  HybridAudioState,
+  HybridAudioControls,
+  HybridWebAudioAPI,
+  UseHybridAudioReturn,
+} from './useHybridAudio';
+export { useHybridAudioAnalysis } from './useHybridAudioAnalysis';
+
 // Public hooks
 export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';
 export type { AudioHotkeyOptions, ShortcutItem, ShortcutGroup } from './useAudioHotkeys';