@djangocfg/ui-tools 2.1.310 → 2.1.313

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

@@ -1,76 +0,0 @@
-'use client';
-
-/**
- * useAudioBus — Global audio exclusivity via Zustand store.
- *
- * Ensures only one audio player plays at a time across the entire page.
- * No provider needed — singleton store, works anywhere in the tree.
- *
- * Also integrates with @djangocfg/ui-tools AudioPlayer automatically
- * (wired into useHybridAudio).
- *
- * @example
- * const { announce } = useAudioBus('my-player-id', () => pause());
- *
- * // When playback starts:
- * announce(); // all other players will pause
- */
-
-import { useEffect, useRef, useCallback } from 'react';
-import { create } from 'zustand';
-
-// =============================================================================
-// Store
-// =============================================================================
-
-interface AudioBusStore {
-  /** ID of the currently active (playing) player, null if none */
-  activeId: string | null;
-  setActiveId: (id: string | null) => void;
-}
-
-export const useAudioBusStore = create<AudioBusStore>((set) => ({
-  activeId: null,
-  setActiveId: (id) => set({ activeId: id }),
-}));
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-export interface UseAudioBusReturn {
-  /** Broadcast: this player is now playing — all others should stop */
-  announce: () => void;
-  /** Release: this player stopped (clears activeId if it was ours) */
-  release: () => void;
-}
-
-/**
- * @param playerId  Stable unique ID for this player instance
- * @param onStop    Called when another player announces — should pause this player
- */
-export function useAudioBus(playerId: string, onStop: () => void): UseAudioBusReturn {
-  const onStopRef = useRef(onStop);
-  onStopRef.current = onStop;
-
-  const setActiveId = useAudioBusStore((s) => s.setActiveId);
-
-  // Subscribe to store changes — if another player becomes active, stop this one
-  useEffect(() => {
-    return useAudioBusStore.subscribe((state) => {
-      if (state.activeId !== null && state.activeId !== playerId) {
-        onStopRef.current();
-      }
-    });
-  }, [playerId]);
-
-  const announce = useCallback(() => {
-    setActiveId(playerId);
-  }, [playerId, setActiveId]);
-
-  const release = useCallback(() => {
-    useAudioBusStore.setState((s) => s.activeId === playerId ? { activeId: null } : s);
-  }, [playerId]);
-
-  return { announce, release };
-}

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

@@ -1,403 +0,0 @@
-'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 { useCallback, useEffect, useId, useRef, useState } from 'react';
-import { useAudioBus } from './useAudioBus';
-
-// =============================================================================
-// TYPES
-// =============================================================================
-
-export interface UseHybridAudioOptions {
-  src: string;
-  autoPlay?: boolean;
-  initialVolume?: number;
-  loop?: boolean;
-  crossOrigin?: 'anonymous' | 'use-credentials';
-  /** Set to true to opt out of global audio bus (player won't stop others and won't be stopped) */
-  excludeFromBus?: boolean;
-  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',
-    excludeFromBus = false,
-    onPlay,
-    onPause,
-    onEnded,
-    onTimeUpdate,
-    onError,
-    onReady,
-  } = options;
-
-  const playerId = useId();
-
-  // 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);
-    }
-  }, []);
-
-  // Audio bus — stop other players when this one plays
-  const { announce: busAnnounce, release: busRelease } = useAudioBus(
-    playerId,
-    useCallback(() => {
-      if (!excludeFromBus) audioRef.current?.pause();
-    }, [excludeFromBus])
-  );
-
-  // 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 {
-      if (!excludeFromBus) busAnnounce();
-      initWebAudio();
-      await resumeAudioContext();
-      await audio.play();
-    } catch (error) {
-      console.error('[useHybridAudio] Play failed:', error);
-      onError?.(error as Error);
-    }
-  }, [excludeFromBus, busAnnounce, 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 = '';
-      busRelease();
-      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

@@ -1,96 +0,0 @@
-'use client';
-
-/**
- * useHybridAudioAnalysis - Audio frequency analysis for hybrid player.
- *
- * Simplified version of useAudioAnalysis that works directly with AnalyserNode
- * instead of SharedWebAudioContext.
- */
-
-import { useCallback, useEffect, useRef, useState } 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;
-}