@djangocfg/ui-nextjs 2.1.66 → 2.1.68

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

@@ -0,0 +1,292 @@
+'use client';
+
+/**
+ * AudioProvider - Shared audio state and controls
+ *
+ * Provides centralized audio state management using WaveSurfer.js
+ * All child components can access playback state and controls
+ */
+
+import {
+  createContext,
+  useRef,
+  useMemo,
+  useCallback,
+  useState,
+  useEffect,
+  type ReactNode,
+} from 'react';
+import { useWavesurfer } from '@wavesurfer/react';
+import type { AudioContextState, AudioSource, WaveformOptions } from '../types';
+import { useSharedWebAudio, useAudioAnalysis } from '../hooks';
+import { useAudioCache } from '../../../stores/mediaCache';
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+// Named AudioPlayerContext to avoid conflict with browser's AudioContext
+export const AudioPlayerContext = createContext<AudioContextState | null>(null);
+
+// =============================================================================
+// PROVIDER PROPS
+// =============================================================================
+
+interface AudioProviderProps {
+  /** Audio source */
+  source: AudioSource;
+  /** Auto-play when loaded */
+  autoPlay?: boolean;
+  /** WaveSurfer options */
+  waveformOptions?: WaveformOptions;
+  /** Container ref for waveform rendering */
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  /** Children components */
+  children: ReactNode;
+}
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+export function AudioProvider({
+  source,
+  autoPlay = false,
+  waveformOptions = {},
+  containerRef,
+  children,
+}: AudioProviderProps) {
+  // Cache for playback position persistence
+  const { saveAudioPosition, getAudioPosition } = useAudioCache();
+  const lastSavedTimeRef = useRef<number>(0);
+
+  // Memoize WaveSurfer options with theme-aware colors
+  const options = useMemo(
+    () => ({
+      container: containerRef,
+      url: source.uri,
+      // Theme-aware colors using HSL
+      waveColor: waveformOptions.waveColor || 'hsl(217 91% 60% / 0.3)',
+      progressColor: waveformOptions.progressColor || 'hsl(217 91% 60%)',
+      cursorColor: waveformOptions.cursorColor || 'hsl(217 91% 60%)',
+      cursorWidth: waveformOptions.cursorWidth ?? 2,
+      height: waveformOptions.height ?? 64,
+      barWidth: waveformOptions.barWidth ?? 3,
+      barRadius: waveformOptions.barRadius ?? 3,
+      barGap: waveformOptions.barGap ?? 2,
+      normalize: true,
+      interact: true,
+      hideScrollbar: true,
+      autoplay: autoPlay,
+    }),
+    [source.uri, autoPlay, waveformOptions, containerRef]
+  );
+
+  // Use official wavesurfer-react hook
+  const { wavesurfer, isReady, isPlaying, currentTime } = useWavesurfer(options);
+
+  // Restore cached playback position when ready
+  useEffect(() => {
+    if (isReady && wavesurfer && source.uri) {
+      const cachedPosition = getAudioPosition(source.uri);
+      if (cachedPosition && cachedPosition > 0) {
+        const duration = wavesurfer.getDuration();
+        // Only restore if position is valid (not at the end)
+        if (cachedPosition < duration - 1) {
+          wavesurfer.setTime(cachedPosition);
+        }
+      }
+    }
+  }, [isReady, wavesurfer, source.uri, getAudioPosition]);
+
+  // Save playback position periodically and on pause
+  useEffect(() => {
+    if (!source.uri) return;
+
+    // Save position every 5 seconds during playback
+    if (isPlaying && currentTime > 0) {
+      const timeSinceLastSave = currentTime - lastSavedTimeRef.current;
+      if (timeSinceLastSave >= 5 || timeSinceLastSave < 0) {
+        saveAudioPosition(source.uri, currentTime);
+        lastSavedTimeRef.current = currentTime;
+      }
+    }
+
+    // Save position immediately when paused
+    if (!isPlaying && currentTime > 0) {
+      saveAudioPosition(source.uri, currentTime);
+      lastSavedTimeRef.current = currentTime;
+    }
+  }, [isPlaying, currentTime, source.uri, saveAudioPosition]);
+
+  // Derived state
+  const duration = wavesurfer?.getDuration() ?? 0;
+  const volume = wavesurfer?.getVolume() ?? 1;
+  const isMuted = wavesurfer?.getMuted() ?? false;
+
+  // Loop state
+  const [isLooping, setIsLooping] = useState(false);
+
+  // Handle loop: restart playback when audio finishes
+  useEffect(() => {
+    if (!wavesurfer) return;
+
+    const handleFinish = () => {
+      if (isLooping) {
+        wavesurfer.seekTo(0);
+        wavesurfer.play();
+      }
+    };
+
+    wavesurfer.on('finish', handleFinish);
+    return () => {
+      wavesurfer.un('finish', handleFinish);
+    };
+  }, [wavesurfer, isLooping]);
+
+  // Get audio element for equalizer
+  const audioElement = useMemo(() => {
+    return wavesurfer?.getMediaElement() ?? null;
+  }, [wavesurfer]);
+
+  // Shared Web Audio context for all analyzers (prevents duplicate source nodes)
+  const sharedAudio = useSharedWebAudio(audioElement);
+
+  // Audio analysis for reactive effects (uses shared context)
+  const audioLevels = useAudioAnalysis(sharedAudio, isPlaying);
+
+  // Actions
+  const play = useCallback(async () => {
+    await wavesurfer?.play();
+  }, [wavesurfer]);
+
+  const pause = useCallback(() => {
+    wavesurfer?.pause();
+  }, [wavesurfer]);
+
+  const togglePlay = useCallback(() => {
+    wavesurfer?.playPause();
+  }, [wavesurfer]);
+
+  const seek = useCallback(
+    (time: number) => {
+      if (wavesurfer) {
+        const clampedTime = Math.max(0, Math.min(time, duration));
+        wavesurfer.setTime(clampedTime);
+      }
+    },
+    [wavesurfer, duration]
+  );
+
+  const seekTo = useCallback(
+    (progress: number) => {
+      if (wavesurfer) {
+        const clampedProgress = Math.max(0, Math.min(progress, 1));
+        wavesurfer.seekTo(clampedProgress);
+      }
+    },
+    [wavesurfer]
+  );
+
+  const skip = useCallback(
+    (seconds: number) => {
+      wavesurfer?.skip(seconds);
+    },
+    [wavesurfer]
+  );
+
+  const setVolume = useCallback(
+    (vol: number) => {
+      if (wavesurfer) {
+        wavesurfer.setVolume(Math.max(0, Math.min(vol, 1)));
+      }
+    },
+    [wavesurfer]
+  );
+
+  const toggleMute = useCallback(() => {
+    if (wavesurfer) {
+      wavesurfer.setMuted(!wavesurfer.getMuted());
+    }
+  }, [wavesurfer]);
+
+  const restart = useCallback(() => {
+    if (wavesurfer) {
+      wavesurfer.seekTo(0);
+      wavesurfer.play();
+    }
+  }, [wavesurfer]);
+
+  const toggleLoop = useCallback(() => {
+    setIsLooping((prev) => !prev);
+  }, []);
+
+  const setLoop = useCallback((enabled: boolean) => {
+    setIsLooping(enabled);
+  }, []);
+
+  // Context value
+  const contextValue = useMemo<AudioContextState>(
+    () => ({
+      // Core instances
+      wavesurfer,
+      audioElement,
+      sharedAudio,
+
+      // Playback state
+      isReady,
+      isPlaying,
+      currentTime,
+      duration,
+      volume,
+      isMuted,
+      isLooping,
+
+      // Audio analysis
+      audioLevels,
+
+      // Actions
+      play,
+      pause,
+      togglePlay,
+      seek,
+      seekTo,
+      skip,
+      setVolume,
+      toggleMute,
+      toggleLoop,
+      setLoop,
+      restart,
+    }),
+    [
+      wavesurfer,
+      audioElement,
+      sharedAudio,
+      isReady,
+      isPlaying,
+      currentTime,
+      duration,
+      volume,
+      isMuted,
+      isLooping,
+      audioLevels,
+      play,
+      pause,
+      togglePlay,
+      seek,
+      seekTo,
+      skip,
+      setVolume,
+      toggleMute,
+      toggleLoop,
+      setLoop,
+      restart,
+    ]
+  );
+
+  return (
+    <AudioPlayerContext.Provider value={contextValue}>
+      {children}
+    </AudioPlayerContext.Provider>
+  );
+}

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

@@ -0,0 +1,11 @@
+/**
+ * AudioPlayer context - Public API
+ *
+ * Re-exports provider and selector hooks
+ */
+
+// Provider
+export { AudioProvider, AudioPlayerContext } from './AudioProvider';
+
+// Selector hooks
+export { useAudio, useAudioControls, useAudioState, useAudioElement } from './selectors';

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

@@ -0,0 +1,96 @@
+'use client';
+
+/**
+ * Context selectors - Performance-optimized hooks for accessing audio state
+ *
+ * These hooks provide selective access to context values,
+ * helping to minimize unnecessary re-renders.
+ */
+
+import { useContext } from 'react';
+import { AudioPlayerContext } from './AudioProvider';
+import type { AudioContextState } from '../types';
+
+// =============================================================================
+// MAIN HOOK
+// =============================================================================
+
+/**
+ * Access full audio context state
+ * @throws Error if used outside AudioProvider
+ */
+export function useAudio(): AudioContextState {
+  const context = useContext(AudioPlayerContext);
+  if (!context) {
+    throw new Error('useAudio must be used within an AudioProvider');
+  }
+  return context;
+}
+
+// =============================================================================
+// SELECTIVE HOOKS - for performance optimization
+// =============================================================================
+
+/**
+ * Hook for playback controls only (no re-render on time updates)
+ */
+export function useAudioControls() {
+  const {
+    isReady,
+    play,
+    pause,
+    togglePlay,
+    skip,
+    restart,
+    setVolume,
+    toggleMute,
+    toggleLoop,
+    setLoop,
+  } = useAudio();
+
+  return {
+    isReady,
+    play,
+    pause,
+    togglePlay,
+    skip,
+    restart,
+    setVolume,
+    toggleMute,
+    toggleLoop,
+    setLoop,
+  };
+}
+
+/**
+ * Hook for playback state (read-only)
+ */
+export function useAudioState() {
+  const {
+    isReady,
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    isMuted,
+    isLooping,
+  } = useAudio();
+
+  return {
+    isReady,
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    isMuted,
+    isLooping,
+  };
+}
+
+/**
+ * Hook for audio element access (for equalizer and reactive effects)
+ */
+export function useAudioElement() {
+  const { audioElement, sharedAudio, isPlaying, audioLevels } = useAudio();
+  return { audioElement, sharedAudio, isPlaying, audioLevels };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * AudioPlayer hooks - re-exports all hooks
+ */
+
+// Internal hooks (used by provider)
+export { useSharedWebAudio } from './useSharedWebAudio';
+export { useAudioAnalysis } from './useAudioAnalysis';
+
+// Public hooks
+export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';
+export type { AudioHotkeyOptions, ShortcutItem, ShortcutGroup } from './useAudioHotkeys';
+
+export {
+  useVisualization,
+  useAudioVisualization, // backward compat alias
+  VisualizationProvider,
+  VARIANT_INFO,
+  INTENSITY_INFO,
+  COLOR_SCHEME_INFO,
+} from './useVisualization';
+export type {
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseVisualizationReturn,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './useVisualization';

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

@@ -0,0 +1,110 @@
+'use client';
+
+/**
+ * useAudioAnalysis - Real-time audio frequency analysis for reactive effects.
+ *
+ * Analyzes audio frequencies for bass, mid, high, and overall levels.
+ * Uses shared Web Audio context to prevent duplicate source nodes.
+ */
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import type { SharedWebAudioContext } from '../types';
+import type { AudioLevels } from '../effects';
+
+export function useAudioAnalysis(
+  sharedAudio: SharedWebAudioContext,
+  isPlaying: boolean
+): AudioLevels {
+  const [levels, setLevels] = useState<AudioLevels>({ bass: 0, mid: 0, high: 0, overall: 0 });
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const animationRef = useRef<number | null>(null);
+  const dataArrayRef = useRef<Uint8Array | null>(null);
+
+  const cleanup = useCallback(() => {
+    if (animationRef.current) {
+      cancelAnimationFrame(animationRef.current);
+      animationRef.current = null;
+    }
+  }, []);
+
+  // Create analyser when shared audio is ready
+  useEffect(() => {
+    if (!sharedAudio.sourceNode || analyserRef.current) return;
+
+    const analyser = sharedAudio.createAnalyser({ fftSize: 256, smoothing: 0.85 });
+    if (analyser) {
+      analyserRef.current = analyser;
+      dataArrayRef.current = new Uint8Array(analyser.frequencyBinCount);
+    }
+
+    return () => {
+      if (analyserRef.current) {
+        sharedAudio.disconnectAnalyser(analyserRef.current);
+        analyserRef.current = null;
+        dataArrayRef.current = null;
+      }
+    };
+  }, [sharedAudio.sourceNode, sharedAudio.createAnalyser, sharedAudio.disconnectAnalyser]);
+
+  // Animation loop
+  useEffect(() => {
+    if (!isPlaying || !analyserRef.current || !dataArrayRef.current) {
+      cleanup();
+      // Smooth fade out
+      setLevels(prev => ({
+        bass: prev.bass * 0.95 < 0.01 ? 0 : prev.bass * 0.95,
+        mid: prev.mid * 0.95,
+        high: prev.high * 0.95,
+        overall: prev.overall * 0.95,
+      }));
+      return;
+    }
+
+    const analyser = analyserRef.current;
+    const dataArray = dataArrayRef.current;
+
+    const animate = () => {
+      analyser.getByteFrequencyData(dataArray as Uint8Array<ArrayBuffer>);
+      const binCount = dataArray.length;
+
+      // Bass (0-15%)
+      const bassEnd = Math.floor(binCount * 0.15);
+      let bassSum = 0;
+      for (let i = 0; i < bassEnd; i++) bassSum += dataArray[i];
+      const bass = bassSum / bassEnd / 255;
+
+      // Mids (15-50%)
+      const midStart = bassEnd;
+      const midEnd = Math.floor(binCount * 0.5);
+      let midSum = 0;
+      for (let i = midStart; i < midEnd; i++) midSum += dataArray[i];
+      const mid = midSum / (midEnd - midStart) / 255;
+
+      // Highs (50-100%)
+      const highStart = midEnd;
+      let highSum = 0;
+      for (let i = highStart; i < binCount; i++) highSum += dataArray[i];
+      const high = highSum / (binCount - highStart) / 255;
+
+      // Overall
+      let totalSum = 0;
+      for (let i = 0; i < binCount; i++) totalSum += dataArray[i];
+      const overall = totalSum / binCount / 255;
+
+      // Smooth with lerp
+      setLevels(prev => ({
+        bass: prev.bass * 0.7 + bass * 0.3,
+        mid: prev.mid * 0.7 + mid * 0.3,
+        high: prev.high * 0.7 + high * 0.3,
+        overall: prev.overall * 0.7 + overall * 0.3,
+      }));
+
+      animationRef.current = requestAnimationFrame(animate);
+    };
+
+    animationRef.current = requestAnimationFrame(animate);
+    return cleanup;
+  }, [isPlaying, cleanup]);
+
+  return levels;
+}

package/src/tools/AudioPlayer/{useAudioHotkeys.ts → hooks/useAudioHotkeys.ts}

@@ -1,14 +1,13 @@
 'use client';
 
 /**
- * Audio Player Hotkeys Hook
+ * useAudioHotkeys - Keyboard shortcuts for audio playback control.
  *
- * Provides keyboard shortcuts for audio playback control.
  * Uses useHotkey from @djangocfg/ui-nextjs.
  */
 
 import { useHotkey, useDeviceDetect } from '@djangocfg/ui-nextjs';
-import { useAudioControls, useAudioState } from './context';
+import { useAudioControls, useAudioState } from '../context';
 
 // =============================================================================
 // TYPES
@@ -30,7 +29,7 @@ export interface AudioHotkeyOptions {
 export function useAudioHotkeys(options: AudioHotkeyOptions = {}) {
   const { enabled = true, skipDuration = 10, volumeStep = 0.1 } = options;
 
-  const { togglePlay, skip, setVolume, toggleMute, isReady } = useAudioControls();
+  const { togglePlay, skip, setVolume, toggleMute, toggleLoop, isReady } = useAudioControls();
   const { volume, duration } = useAudioState();
   const device = useDeviceDetect();
 
@@ -85,6 +84,13 @@ export function useAudioHotkeys(options: AudioHotkeyOptions = {}) {
     { enabled: enabled && isReady, description: 'Mute/Unmute' }
   );
 
+  // Loop/Repeat - L key (conflicts with skip forward, using Shift+L)
+  useHotkey(
+    'shift+l',
+    () => toggleLoop(),
+    { enabled: enabled && isReady, description: 'Toggle loop' }
+  );
+
   // Number keys 0-9 to seek to percentage
   useHotkey(
     ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'],
@@ -123,6 +129,7 @@ export const AUDIO_SHORTCUTS: ShortcutGroup[] = [
       { keys: ['Space'], label: 'Play/Pause' },
       { keys: ['←'], label: 'Skip 10s back' },
       { keys: ['→'], label: 'Skip 10s forward' },
+      { keys: ['⇧', 'L'], label: 'Toggle loop' },
     ],
   },
   {

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

@@ -0,0 +1,106 @@
+'use client';
+
+/**
+ * useSharedWebAudio - Manages a shared Web Audio context and source node.
+ *
+ * This prevents the "InvalidStateError" from creating multiple MediaElementSourceNodes
+ * for the same audio element. All analyzers share the same source.
+ */
+
+import { useRef, useEffect, useCallback } from 'react';
+import type { SharedWebAudioContext } from '../types';
+
+export function useSharedWebAudio(audioElement: HTMLMediaElement | null): SharedWebAudioContext {
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const sourceRef = useRef<MediaElementAudioSourceNode | null>(null);
+  const connectedElementRef = useRef<HTMLMediaElement | null>(null);
+  const analyserNodesRef = useRef<Set<AnalyserNode>>(new Set());
+
+  // Initialize Web Audio on first play
+  useEffect(() => {
+    if (!audioElement) return;
+
+    // Already connected to this element
+    if (connectedElementRef.current === audioElement && audioContextRef.current) {
+      return;
+    }
+
+    const initAudio = () => {
+      try {
+        if (!audioContextRef.current) {
+          const AudioContextClass = window.AudioContext ||
+            (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+          audioContextRef.current = new AudioContextClass();
+        }
+
+        const audioContext = audioContextRef.current;
+
+        // Only create source node once per audio element
+        if (connectedElementRef.current !== audioElement) {
+          if (sourceRef.current) {
+            try { sourceRef.current.disconnect(); } catch { /* ignore */ }
+          }
+
+          sourceRef.current = audioContext.createMediaElementSource(audioElement);
+          // Connect directly to destination (analysers will be inserted in between)
+          sourceRef.current.connect(audioContext.destination);
+          connectedElementRef.current = audioElement;
+        }
+      } catch (error) {
+        console.warn('[SharedWebAudio] Could not initialize:', error);
+      }
+    };
+
+    const handlePlay = () => {
+      initAudio();
+      if (audioContextRef.current?.state === 'suspended') {
+        audioContextRef.current.resume();
+      }
+    };
+
+    audioElement.addEventListener('play', handlePlay);
+    if (!audioElement.paused) {
+      handlePlay();
+    }
+
+    return () => {
+      audioElement.removeEventListener('play', handlePlay);
+    };
+  }, [audioElement]);
+
+  // Create an analyser connected to the shared source
+  const createAnalyser = useCallback((options?: { fftSize?: number; smoothing?: number }): AnalyserNode | null => {
+    if (!audioContextRef.current || !sourceRef.current) return null;
+
+    try {
+      const analyser = audioContextRef.current.createAnalyser();
+      analyser.fftSize = options?.fftSize ?? 256;
+      analyser.smoothingTimeConstant = options?.smoothing ?? 0.85;
+
+      // Connect: source -> analyser -> destination
+      sourceRef.current.connect(analyser);
+      analyser.connect(audioContextRef.current.destination);
+
+      analyserNodesRef.current.add(analyser);
+      return analyser;
+    } catch (error) {
+      console.warn('[SharedWebAudio] Could not create analyser:', error);
+      return null;
+    }
+  }, []);
+
+  // Disconnect an analyser
+  const disconnectAnalyser = useCallback((analyser: AnalyserNode) => {
+    try {
+      analyser.disconnect();
+      analyserNodesRef.current.delete(analyser);
+    } catch { /* ignore */ }
+  }, []);
+
+  return {
+    audioContext: audioContextRef.current,
+    sourceNode: sourceRef.current,
+    createAnalyser,
+    disconnectAnalyser,
+  };
+}