@djangocfg/ui-nextjs 2.1.81 → 2.1.83

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

@@ -0,0 +1,387 @@
+'use client';
+
+/**
+ * useHybridAudio - Hybrid audio hook combining HTML5 audio + Web Audio API
+ *
+ * Uses native HTML5 <audio> for playback (no crackling, native streaming)
+ * and Web Audio API only for visualization (AnalyserNode).
+ *
+ * Audio routing:
+ *   source -> destination (single path for playback)
+ *   source -> analyser (parallel path for visualization only, no output)
+ */
+
+import { useRef, useState, useCallback, useEffect } from 'react';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface UseHybridAudioOptions {
+  src: string;
+  autoPlay?: boolean;
+  initialVolume?: number;
+  loop?: boolean;
+  crossOrigin?: 'anonymous' | 'use-credentials';
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onTimeUpdate?: (time: number) => void;
+  onError?: (error: Error) => void;
+  onReady?: () => void;
+}
+
+export interface HybridAudioState {
+  isReady: boolean;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  isLooping: boolean;
+  buffered: TimeRanges | null;
+  error: Error | null;
+}
+
+export interface HybridAudioControls {
+  play: () => Promise<void>;
+  pause: () => void;
+  togglePlay: () => void;
+  seek: (time: number) => void;
+  seekTo: (progress: number) => void;
+  skip: (seconds: number) => void;
+  setVolume: (vol: number) => void;
+  toggleMute: () => void;
+  toggleLoop: () => void;
+  setLoop: (enabled: boolean) => void;
+  restart: () => void;
+}
+
+export interface HybridWebAudioAPI {
+  context: AudioContext | null;
+  analyser: AnalyserNode | null;
+  sourceNode: MediaElementAudioSourceNode | null;
+}
+
+export interface UseHybridAudioReturn {
+  audioRef: React.RefObject<HTMLAudioElement | null>;
+  state: HybridAudioState;
+  controls: HybridAudioControls;
+  webAudio: HybridWebAudioAPI;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioReturn {
+  const {
+    src,
+    autoPlay = false,
+    initialVolume = 1,
+    loop = false,
+    crossOrigin = 'anonymous',
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onError,
+    onReady,
+  } = options;
+
+  // Refs
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const sourceNodeRef = useRef<MediaElementAudioSourceNode | null>(null);
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const connectedElementRef = useRef<HTMLMediaElement | null>(null);
+
+  // State
+  const [state, setState] = useState<HybridAudioState>({
+    isReady: false,
+    isPlaying: false,
+    currentTime: 0,
+    duration: 0,
+    volume: initialVolume,
+    isMuted: false,
+    isLooping: loop,
+    buffered: null,
+    error: null,
+  });
+
+  // Initialize Web Audio for visualization (lazy, on first play)
+  const initWebAudio = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    // Already connected to this element
+    if (connectedElementRef.current === audio && audioContextRef.current) {
+      return;
+    }
+
+    try {
+      // Create AudioContext if needed
+      if (!audioContextRef.current) {
+        const AudioContextClass =
+          window.AudioContext ||
+          (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+        audioContextRef.current = new AudioContextClass();
+      }
+
+      const ctx = audioContextRef.current;
+
+      // Disconnect old source if any
+      if (sourceNodeRef.current) {
+        try {
+          sourceNodeRef.current.disconnect();
+        } catch {
+          /* ignore */
+        }
+      }
+
+      // Create source from audio element
+      const source = ctx.createMediaElementSource(audio);
+      sourceNodeRef.current = source;
+
+      // Create analyser for visualization
+      const analyser = ctx.createAnalyser();
+      analyser.fftSize = 256;
+      analyser.smoothingTimeConstant = 0.85;
+      analyserRef.current = analyser;
+
+      // Audio routing:
+      // 1. source -> destination (for playback)
+      // 2. source -> analyser (for visualization only - NO output!)
+      source.connect(ctx.destination);
+      source.connect(analyser);
+      // NOTE: analyser does NOT connect to destination - prevents double audio!
+
+      connectedElementRef.current = audio;
+    } catch (error) {
+      console.warn('[useHybridAudio] Web Audio init failed:', error);
+    }
+  }, []);
+
+  // Resume AudioContext on user interaction
+  const resumeAudioContext = useCallback(async () => {
+    const ctx = audioContextRef.current;
+    if (ctx && ctx.state === 'suspended') {
+      await ctx.resume();
+    }
+  }, []);
+
+  // Controls
+  const play = useCallback(async () => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    try {
+      initWebAudio();
+      await resumeAudioContext();
+      await audio.play();
+    } catch (error) {
+      console.error('[useHybridAudio] Play failed:', error);
+      onError?.(error as Error);
+    }
+  }, [initWebAudio, resumeAudioContext, onError]);
+
+  const pause = useCallback(() => {
+    audioRef.current?.pause();
+  }, []);
+
+  const togglePlay = useCallback(() => {
+    if (state.isPlaying) {
+      pause();
+    } else {
+      play();
+    }
+  }, [state.isPlaying, play, pause]);
+
+  const seek = useCallback(
+    (time: number) => {
+      const audio = audioRef.current;
+      if (audio && isFinite(time)) {
+        audio.currentTime = Math.max(0, Math.min(time, state.duration || audio.duration || 0));
+      }
+    },
+    [state.duration]
+  );
+
+  const seekTo = useCallback(
+    (progress: number) => {
+      const duration = state.duration || audioRef.current?.duration || 0;
+      seek(duration * Math.max(0, Math.min(1, progress)));
+    },
+    [state.duration, seek]
+  );
+
+  const skip = useCallback(
+    (seconds: number) => {
+      seek(state.currentTime + seconds);
+    },
+    [state.currentTime, seek]
+  );
+
+  const setVolume = useCallback((vol: number) => {
+    const audio = audioRef.current;
+    if (audio) {
+      const clampedVol = Math.max(0, Math.min(1, vol));
+      audio.volume = clampedVol;
+      setState((prev) => ({ ...prev, volume: clampedVol }));
+    }
+  }, []);
+
+  const toggleMute = useCallback(() => {
+    const audio = audioRef.current;
+    if (audio) {
+      audio.muted = !audio.muted;
+      setState((prev) => ({ ...prev, isMuted: audio.muted }));
+    }
+  }, []);
+
+  const toggleLoop = useCallback(() => {
+    const audio = audioRef.current;
+    if (audio) {
+      audio.loop = !audio.loop;
+      setState((prev) => ({ ...prev, isLooping: audio.loop }));
+    }
+  }, []);
+
+  const setLoop = useCallback((enabled: boolean) => {
+    const audio = audioRef.current;
+    if (audio) {
+      audio.loop = enabled;
+      setState((prev) => ({ ...prev, isLooping: enabled }));
+    }
+  }, []);
+
+  const restart = useCallback(() => {
+    seek(0);
+    play();
+  }, [seek, play]);
+
+  const controls: HybridAudioControls = {
+    play,
+    pause,
+    togglePlay,
+    seek,
+    seekTo,
+    skip,
+    setVolume,
+    toggleMute,
+    toggleLoop,
+    setLoop,
+    restart,
+  };
+
+  // Create audio element on mount
+  useEffect(() => {
+    const audio = document.createElement('audio');
+    audio.preload = 'metadata';
+    audio.crossOrigin = crossOrigin;
+    audio.volume = initialVolume;
+    audio.loop = loop;
+    audioRef.current = audio;
+
+    return () => {
+      audio.pause();
+      audio.src = '';
+      if (audioContextRef.current) {
+        audioContextRef.current.close().catch(() => {});
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Event handlers
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    const handlers = {
+      loadedmetadata: () => {
+        setState((prev) => ({
+          ...prev,
+          duration: audio.duration,
+          isReady: true,
+        }));
+        onReady?.();
+      },
+      canplay: () => {
+        setState((prev) => ({ ...prev, isReady: true }));
+        if (autoPlay) {
+          play();
+        }
+      },
+      play: () => {
+        setState((prev) => ({ ...prev, isPlaying: true }));
+        onPlay?.();
+      },
+      pause: () => {
+        setState((prev) => ({ ...prev, isPlaying: false }));
+        onPause?.();
+      },
+      ended: () => {
+        setState((prev) => ({ ...prev, isPlaying: false }));
+        onEnded?.();
+      },
+      timeupdate: () => {
+        setState((prev) => ({ ...prev, currentTime: audio.currentTime }));
+        onTimeUpdate?.(audio.currentTime);
+      },
+      progress: () => {
+        setState((prev) => ({ ...prev, buffered: audio.buffered }));
+      },
+      error: () => {
+        const error = new Error(audio.error?.message || 'Audio error');
+        setState((prev) => ({ ...prev, error }));
+        onError?.(error);
+      },
+      volumechange: () => {
+        setState((prev) => ({
+          ...prev,
+          volume: audio.volume,
+          isMuted: audio.muted,
+        }));
+      },
+    };
+
+    Object.entries(handlers).forEach(([event, handler]) => {
+      audio.addEventListener(event, handler);
+    });
+
+    return () => {
+      Object.entries(handlers).forEach(([event, handler]) => {
+        audio.removeEventListener(event, handler);
+      });
+    };
+  }, [autoPlay, onPlay, onPause, onEnded, onTimeUpdate, onError, onReady, play]);
+
+  // Load new source
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio || !src) return;
+
+    setState((prev) => ({
+      ...prev,
+      isReady: false,
+      currentTime: 0,
+      duration: 0,
+      error: null,
+    }));
+
+    audio.src = src;
+    audio.load();
+  }, [src]);
+
+  return {
+    audioRef,
+    state,
+    controls,
+    webAudio: {
+      context: audioContextRef.current,
+      analyser: analyserRef.current,
+      sourceNode: sourceNodeRef.current,
+    },
+  };
+}

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

@@ -0,0 +1,95 @@
+'use client';
+
+/**
+ * useHybridAudioAnalysis - Audio frequency analysis for hybrid player.
+ *
+ * Simplified version of useAudioAnalysis that works directly with AnalyserNode
+ * instead of SharedWebAudioContext.
+ */
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import type { AudioLevels } from '../effects';
+
+export function useHybridAudioAnalysis(
+  analyser: AnalyserNode | null,
+  isPlaying: boolean
+): AudioLevels {
+  const [levels, setLevels] = useState<AudioLevels>({ bass: 0, mid: 0, high: 0, overall: 0 });
+  const animationRef = useRef<number | null>(null);
+  const dataArrayRef = useRef<Uint8Array<ArrayBuffer> | null>(null);
+
+  const cleanup = useCallback(() => {
+    if (animationRef.current) {
+      cancelAnimationFrame(animationRef.current);
+      animationRef.current = null;
+    }
+  }, []);
+
+  // Initialize data array when analyser is available
+  useEffect(() => {
+    if (analyser && !dataArrayRef.current) {
+      dataArrayRef.current = new Uint8Array(analyser.frequencyBinCount) as Uint8Array<ArrayBuffer>;
+    }
+  }, [analyser]);
+
+  // Animation loop
+  useEffect(() => {
+    if (!isPlaying || !analyser || !dataArrayRef.current) {
+      cleanup();
+      // Smooth fade out when stopped
+      setLevels((prev) => ({
+        bass: prev.bass * 0.95 < 0.01 ? 0 : prev.bass * 0.95,
+        mid: prev.mid * 0.95 < 0.01 ? 0 : prev.mid * 0.95,
+        high: prev.high * 0.95 < 0.01 ? 0 : prev.high * 0.95,
+        overall: prev.overall * 0.95 < 0.01 ? 0 : prev.overall * 0.95,
+      }));
+      return;
+    }
+
+    const dataArray = dataArrayRef.current;
+
+    const animate = () => {
+      analyser.getByteFrequencyData(dataArray);
+      const binCount = dataArray.length;
+
+      // Bass (0-15% of frequency range)
+      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% of frequency range)
+      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% of frequency range)
+      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 for natural feel
+      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;
+  }, [analyser, isPlaying, cleanup]);
+
+  return levels;
+}

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

@@ -42,7 +42,8 @@ export function useSharedWebAudio(audioElement: HTMLMediaElement | null): Shared
           }
 
           sourceRef.current = audioContext.createMediaElementSource(audioElement);
-          // Connect directly to destination (analysers will be inserted in between)
+          // Single audio output path: source -> destination
+          // Analysers connect to source in parallel for frequency reading only (no output)
           sourceRef.current.connect(audioContext.destination);
           connectedElementRef.current = audioElement;
         }
@@ -77,9 +78,11 @@ export function useSharedWebAudio(audioElement: HTMLMediaElement | null): Shared
       analyser.fftSize = options?.fftSize ?? 256;
       analyser.smoothingTimeConstant = options?.smoothing ?? 0.85;
 
-      // Connect: source -> analyser -> destination
+      // Connect analyser as passive listener (for frequency analysis only)
+      // Audio path: source -> destination (already connected in initAudio)
+      // Analysis path: source -> analyser (no output connection needed)
+      // NOTE: Do NOT connect analyser to destination - it causes double audio routing and crackling!
       sourceRef.current.connect(analyser);
-      analyser.connect(audioContextRef.current.destination);
 
       analyserNodesRef.current.add(analyser);
       return analyser;

package/src/tools/AudioPlayer/index.ts

@@ -19,6 +19,7 @@
 // =============================================================================
 
 export {
+  // WaveSurfer-based (original)
   AudioPlayer,
   SimpleAudioPlayer,
   AudioEqualizer,
@@ -30,6 +31,10 @@ export {
   OrbsEffect,
   SpotlightEffect,
   MeshEffect,
+  // Hybrid player (HTML5 audio + Web Audio visualization)
+  HybridAudioPlayer,
+  HybridSimplePlayer,
+  HybridWaveform,
 } from './components';
 
 export type {
@@ -37,6 +42,10 @@ export type {
   VisualizationToggleProps,
   AudioReactiveCoverProps,
   GlowEffectData,
+  // Hybrid types
+  HybridAudioPlayerProps,
+  HybridSimplePlayerProps,
+  HybridWaveformProps,
 } from './components';
 
 // =============================================================================
@@ -44,12 +53,25 @@ export type {
 // =============================================================================
 
 export {
+  // WaveSurfer-based provider
   AudioProvider,
   AudioPlayerContext,
   useAudio,
   useAudioControls,
   useAudioState,
   useAudioElement,
+  // Hybrid provider (HTML5 audio + Web Audio visualization)
+  HybridAudioProvider,
+  useHybridAudioContext,
+  useHybridAudioState,
+  useHybridAudioControls,
+  useHybridAudioLevels,
+  useHybridWebAudio,
+} from './context';
+
+export type {
+  HybridAudioContextValue,
+  HybridAudioProviderProps,
 } from './context';
 
 // =============================================================================
@@ -70,6 +92,9 @@ export {
   VARIANT_INFO,
   INTENSITY_INFO,
   COLOR_SCHEME_INFO,
+  // Hybrid hooks
+  useHybridAudio,
+  useHybridAudioAnalysis,
 } from './hooks';
 
 export type {
@@ -83,6 +108,12 @@ export type {
   UseVisualizationReturn,
   UseAudioVisualizationReturn,
   VisualizationProviderProps,
+  // Hybrid types
+  UseHybridAudioOptions,
+  HybridAudioState,
+  HybridAudioControls,
+  HybridWebAudioAPI,
+  UseHybridAudioReturn,
 } from './hooks';
 
 // =============================================================================

package/src/tools/AudioPlayer/progressive/ProgressiveAudioPlayer.tsx

@@ -13,6 +13,14 @@
  * - Keyboard shortcuts
  * - Volume control
  * - Loop mode
+ *
+ * NOTE: This player does NOT support reactive cover effects.
+ * For reactive effects with streaming support, use `HybridSimplePlayer` instead.
+ *
+ * Use this player when you need:
+ * - Progressive waveform that shows the actual audio amplitude shape
+ * - Visualization of buffered/loaded ranges
+ * - Large file streaming without reactive effects
  */
 
 import { useRef, useCallback } from 'react';

package/src/tools/ImageViewer/hooks/useImageLoading.ts

@@ -5,7 +5,7 @@
  */
 
 import { useState, useEffect, useRef } from 'react';
-import { useImageCache, generateContentKey } from '../../../stores/mediaCache';
+import { useMediaCacheStore, generateContentKey } from '../../../stores/mediaCache';
 import { createLQIP, MAX_IMAGE_SIZE, WARNING_IMAGE_SIZE, PROGRESSIVE_LOADING_THRESHOLD, imageDebug } from '../utils';
 
 // =============================================================================
@@ -50,7 +50,9 @@ export interface UseImageLoadingReturn {
 export function useImageLoading(options: UseImageLoadingOptions): UseImageLoadingReturn {
   const { content, mimeType, src: directSrc } = options;
 
-  const { getOrCreateBlobUrl, releaseBlobUrl } = useImageCache();
+  // Get stable function references from store (not from hook to avoid re-renders)
+  const getOrCreateBlobUrl = useMediaCacheStore.getState().getOrCreateBlobUrl;
+  const releaseBlobUrl = useMediaCacheStore.getState().releaseBlobUrl;
 
   const [src, setSrc] = useState<string | null>(null);
   const [lqip, setLqip] = useState<string | null>(null);
@@ -58,6 +60,7 @@ export function useImageLoading(options: UseImageLoadingOptions): UseImageLoadin
   const [error, setError] = useState<string | null>(null);
 
   const contentKeyRef = useRef<string | null>(null);
+  const isMountedRef = useRef(true);
 
   // Calculate size and flags
   const size = content ? (typeof content === 'string' ? content.length : content.byteLength) : 0;
@@ -65,6 +68,19 @@ export function useImageLoading(options: UseImageLoadingOptions): UseImageLoadin
   const hasContent = directSrc ? true : size > 0;
   const useProgressiveLoading = directSrc ? false : size > PROGRESSIVE_LOADING_THRESHOLD;
 
+  // Track unmount for cleanup
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      // Release blob URL only on actual unmount
+      if (contentKeyRef.current) {
+        useMediaCacheStore.getState().releaseBlobUrl(contentKeyRef.current);
+        contentKeyRef.current = null;
+      }
+    };
+  }, []);
+
   // Create blob URL with caching and size validation
   useEffect(() => {
     // Reset error state
@@ -112,6 +128,12 @@ export function useImageLoading(options: UseImageLoadingOptions): UseImageLoadin
       const encoder = new TextEncoder();
       const buffer = encoder.encode(content).buffer;
       const contentKey = generateContentKey(buffer);
+
+      // Release previous blob URL if content changed
+      if (contentKeyRef.current && contentKeyRef.current !== contentKey) {
+        releaseBlobUrl(contentKeyRef.current);
+      }
+
       contentKeyRef.current = contentKey;
       const url = getOrCreateBlobUrl(contentKey, buffer, mimeType || 'image/png');
       imageDebug.load(url, 'blob');
@@ -122,19 +144,21 @@ export function useImageLoading(options: UseImageLoadingOptions): UseImageLoadin
 
     // Handle ArrayBuffer with cached blob URL
     const contentKey = generateContentKey(content);
+
+    // Release previous blob URL if content changed
+    if (contentKeyRef.current && contentKeyRef.current !== contentKey) {
+      releaseBlobUrl(contentKeyRef.current);
+    }
+
     contentKeyRef.current = contentKey;
     const url = getOrCreateBlobUrl(contentKey, content, mimeType || 'image/png');
     imageDebug.load(url, 'blob');
     imageDebug.state('loaded', { size, mimeType, contentKey });
     setSrc(url);
 
-    return () => {
-      if (contentKeyRef.current) {
-        releaseBlobUrl(contentKeyRef.current);
-        contentKeyRef.current = null;
-      }
-    };
-  }, [content, mimeType, hasContent, size, directSrc, getOrCreateBlobUrl, releaseBlobUrl]);
+    // No cleanup here - cleanup happens in unmount effect above
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [content, mimeType, hasContent, size, directSrc]);
 
   // Create LQIP for progressive loading
   useEffect(() => {