@djangocfg/ui-nextjs 2.1.65 → 2.1.67

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 };
+}