@djangocfg/ui-nextjs 2.1.69 → 2.1.71

package/src/tools/AudioPlayer/progressive/peaks.ts

@@ -0,0 +1,234 @@
+/**
+ * Audio Peaks Extraction Utilities
+ *
+ * Extracts waveform peaks from AudioBuffer for visualization.
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface ExtractPeaksOptions {
+  /** Number of peaks to extract */
+  length: number;
+  /** Channel to use (0 = left, 1 = right, -1 = mix) */
+  channel?: number;
+  /** Normalize peaks to 0-1 range */
+  normalize?: boolean;
+}
+
+// =============================================================================
+// PEAK EXTRACTION
+// =============================================================================
+
+/**
+ * Extract peaks from an AudioBuffer
+ *
+ * @param audioBuffer - Decoded audio buffer
+ * @param options - Extraction options
+ * @returns Array of normalized peak values (0-1)
+ */
+export function extractPeaks(
+  audioBuffer: AudioBuffer,
+  options: ExtractPeaksOptions
+): number[] {
+  const { length, channel = -1, normalize = true } = options;
+
+  // Get channel data
+  let data: Float32Array;
+  if (channel === -1) {
+    // Mix all channels
+    data = mixChannels(audioBuffer);
+  } else {
+    data = audioBuffer.getChannelData(Math.min(channel, audioBuffer.numberOfChannels - 1));
+  }
+
+  const peaks = new Array<number>(length);
+  const samplesPerPeak = Math.floor(data.length / length);
+
+  let maxPeak = 0;
+
+  for (let i = 0; i < length; i++) {
+    const start = i * samplesPerPeak;
+    const end = Math.min(start + samplesPerPeak, data.length);
+
+    let max = 0;
+    for (let j = start; j < end; j++) {
+      const abs = Math.abs(data[j]);
+      if (abs > max) max = abs;
+    }
+
+    peaks[i] = max;
+    if (max > maxPeak) maxPeak = max;
+  }
+
+  // Normalize to 0-1
+  if (normalize && maxPeak > 0) {
+    for (let i = 0; i < length; i++) {
+      peaks[i] = peaks[i] / maxPeak;
+    }
+  }
+
+  return peaks;
+}
+
+/**
+ * Mix all channels into mono
+ */
+function mixChannels(audioBuffer: AudioBuffer): Float32Array {
+  const numChannels = audioBuffer.numberOfChannels;
+  const length = audioBuffer.length;
+  const mixed = new Float32Array(length);
+
+  for (let ch = 0; ch < numChannels; ch++) {
+    const channelData = audioBuffer.getChannelData(ch);
+    for (let i = 0; i < length; i++) {
+      mixed[i] += channelData[i];
+    }
+  }
+
+  // Average
+  const divisor = numChannels;
+  for (let i = 0; i < length; i++) {
+    mixed[i] /= divisor;
+  }
+
+  return mixed;
+}
+
+// =============================================================================
+// PEAK MERGING
+// =============================================================================
+
+/**
+ * Merge two peaks arrays (for progressive loading)
+ *
+ * @param existing - Existing peaks array
+ * @param newPeaks - New peaks to merge
+ * @param startIndex - Start index for new peaks
+ * @returns Merged peaks array
+ */
+export function mergePeaks(
+  existing: number[],
+  newPeaks: number[],
+  startIndex: number
+): number[] {
+  const result = [...existing];
+
+  // Extend if needed
+  const neededLength = startIndex + newPeaks.length;
+  while (result.length < neededLength) {
+    result.push(0);
+  }
+
+  // Merge
+  for (let i = 0; i < newPeaks.length; i++) {
+    result[startIndex + i] = newPeaks[i];
+  }
+
+  return result;
+}
+
+// =============================================================================
+// PEAK RESAMPLING
+// =============================================================================
+
+/**
+ * Resample peaks to a different length
+ *
+ * @param peaks - Source peaks
+ * @param targetLength - Target number of peaks
+ * @returns Resampled peaks
+ */
+export function resamplePeaks(peaks: number[], targetLength: number): number[] {
+  if (peaks.length === 0) return new Array(targetLength).fill(0);
+  if (peaks.length === targetLength) return [...peaks];
+
+  const result = new Array<number>(targetLength);
+  const ratio = peaks.length / targetLength;
+
+  for (let i = 0; i < targetLength; i++) {
+    const start = Math.floor(i * ratio);
+    const end = Math.min(Math.ceil((i + 1) * ratio), peaks.length);
+
+    let max = 0;
+    for (let j = start; j < end; j++) {
+      if (peaks[j] > max) max = peaks[j];
+    }
+    result[i] = max;
+  }
+
+  return result;
+}
+
+// =============================================================================
+// PEAK SMOOTHING
+// =============================================================================
+
+/**
+ * Smooth peaks using moving average
+ *
+ * @param peaks - Source peaks
+ * @param windowSize - Smoothing window size
+ * @returns Smoothed peaks
+ */
+export function smoothPeaks(peaks: number[], windowSize: number = 3): number[] {
+  if (windowSize < 2 || peaks.length < windowSize) return [...peaks];
+
+  const result = new Array<number>(peaks.length);
+  const halfWindow = Math.floor(windowSize / 2);
+
+  for (let i = 0; i < peaks.length; i++) {
+    const start = Math.max(0, i - halfWindow);
+    const end = Math.min(peaks.length, i + halfWindow + 1);
+
+    let sum = 0;
+    for (let j = start; j < end; j++) {
+      sum += peaks[j];
+    }
+    result[i] = sum / (end - start);
+  }
+
+  return result;
+}
+
+// =============================================================================
+// PEAK CALCULATIONS
+// =============================================================================
+
+/**
+ * Calculate peaks per second based on width and duration
+ */
+export function calculatePeaksCount(
+  width: number,
+  barWidth: number,
+  barGap: number
+): number {
+  const totalBarSpace = barWidth + barGap;
+  return Math.floor(width / totalBarSpace);
+}
+
+/**
+ * Calculate which peak index corresponds to a time
+ */
+export function timeToIndex(
+  time: number,
+  duration: number,
+  peaksCount: number
+): number {
+  if (duration <= 0) return 0;
+  const progress = time / duration;
+  return Math.floor(progress * peaksCount);
+}
+
+/**
+ * Calculate time from peak index
+ */
+export function indexToTime(
+  index: number,
+  peaksCount: number,
+  duration: number
+): number {
+  if (peaksCount <= 0) return 0;
+  return (index / peaksCount) * duration;
+}

package/src/tools/AudioPlayer/progressive/types.ts

@@ -0,0 +1,179 @@
+/**
+ * Progressive Audio Player Types
+ */
+
+// =============================================================================
+// WAVEFORM TYPES
+// =============================================================================
+
+export interface WaveformData {
+  /** Normalized peaks array (values 0-1) */
+  peaks: number[];
+  /** Duration in seconds */
+  duration: number;
+  /** Sample rate of source audio */
+  sampleRate: number;
+}
+
+export interface LoadedRange {
+  /** Start position (0-1) */
+  start: number;
+  /** End position (0-1) */
+  end: number;
+}
+
+export interface WaveformLoadingState {
+  /** Loading progress (0-100) */
+  percent: number;
+  /** Loaded byte ranges */
+  loadedRanges: LoadedRange[];
+  /** Is currently loading */
+  isLoading: boolean;
+  /** Error if any */
+  error: Error | null;
+}
+
+// =============================================================================
+// AUDIO ELEMENT TYPES
+// =============================================================================
+
+export interface AudioState {
+  /** Is audio playing */
+  isPlaying: boolean;
+  /** Current playback time in seconds */
+  currentTime: number;
+  /** Total duration in seconds */
+  duration: number;
+  /** Volume level (0-1) */
+  volume: number;
+  /** Is muted */
+  isMuted: boolean;
+  /** Is looping */
+  isLooping: boolean;
+  /** Is audio ready to play */
+  isReady: boolean;
+  /** Buffered time ranges */
+  buffered: TimeRanges | null;
+  /** Error if any */
+  error: Error | null;
+}
+
+export interface AudioControls {
+  play: () => Promise<void>;
+  pause: () => void;
+  togglePlay: () => void;
+  seek: (time: number) => void;
+  seekTo: (progress: number) => void;
+  skip: (seconds: number) => void;
+  setVolume: (volume: number) => void;
+  toggleMute: () => void;
+  setLoop: (enabled: boolean) => void;
+  toggleLoop: () => void;
+}
+
+// =============================================================================
+// CANVAS TYPES
+// =============================================================================
+
+export interface WaveformStyle {
+  /** Color for waveform bars */
+  waveColor?: string;
+  /** Color for played portion */
+  progressColor?: string;
+  /** Color for loading/unloaded area */
+  loadingColor?: string;
+  /** Cursor color */
+  cursorColor?: string;
+  /** Bar width in pixels */
+  barWidth?: number;
+  /** Gap between bars in pixels */
+  barGap?: number;
+  /** Bar border radius */
+  barRadius?: number;
+  /** Canvas height */
+  height?: number;
+}
+
+export interface WaveformInteraction {
+  /** Called when user seeks */
+  onSeek?: (time: number) => void;
+  /** Called on hover (preview) */
+  onHover?: (time: number | null) => void;
+  /** Is interaction enabled */
+  interactive?: boolean;
+}
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ProgressiveAudioPlayerProps {
+  /** Audio source URL */
+  src: string;
+  /** Track title */
+  title?: string;
+  /** Artist name */
+  artist?: string;
+  /** Cover art URL */
+  coverArt?: string;
+
+  /** Show waveform visualization */
+  showWaveform?: boolean;
+  /** Show playback controls */
+  showControls?: boolean;
+  /** Show time display */
+  showTimer?: boolean;
+  /** Show volume control */
+  showVolume?: boolean;
+  /** Show loop button */
+  showLoop?: boolean;
+
+  /** Auto-play on load */
+  autoPlay?: boolean;
+
+  /** Waveform styling */
+  waveformStyle?: WaveformStyle;
+
+  /** Additional class name */
+  className?: string;
+
+  /** Callbacks */
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onTimeUpdate?: (time: number) => void;
+  onError?: (error: Error) => void;
+}
+
+// =============================================================================
+// DECODER TYPES
+// =============================================================================
+
+export interface ChunkInfo {
+  /** Chunk index */
+  index: number;
+  /** Start byte */
+  start: number;
+  /** End byte */
+  end: number;
+  /** Chunk data */
+  data: ArrayBuffer;
+}
+
+export interface DecodeResult {
+  /** Extracted peaks for this chunk */
+  peaks: number[];
+  /** Chunk duration in seconds */
+  duration: number;
+  /** Sample rate */
+  sampleRate: number;
+}
+
+export interface DecoderOptions {
+  /** Target number of peaks per second of audio */
+  peaksPerSecond?: number;
+  /** Chunk size for fetching (bytes) */
+  chunkSize?: number;
+  /** Number of parallel fetches */
+  parallelFetches?: number;
+}

package/src/tools/AudioPlayer/progressive/useAudioElement.ts

@@ -0,0 +1,289 @@
+'use client';
+
+/**
+ * useAudioElement - Hook for managing HTML5 Audio element
+ *
+ * Provides reactive state and controls for audio playback.
+ * Uses native browser Range request handling for streaming.
+ */
+
+import { useRef, useState, useCallback, useEffect } from 'react';
+import type { AudioState, AudioControls } from './types';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface UseAudioElementOptions {
+  /** Audio source URL */
+  src: string;
+  /** Auto-play when loaded */
+  autoPlay?: boolean;
+  /** Initial volume (0-1) */
+  initialVolume?: number;
+  /** Loop playback */
+  loop?: boolean;
+  /** Callbacks */
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onTimeUpdate?: (time: number) => void;
+  onDurationChange?: (duration: number) => void;
+  onError?: (error: Error) => void;
+}
+
+interface UseAudioElementReturn extends AudioState, AudioControls {
+  /** Ref to audio element */
+  audioRef: React.RefObject<HTMLAudioElement>;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useAudioElement(options: UseAudioElementOptions): UseAudioElementReturn {
+  const {
+    src,
+    autoPlay = false,
+    initialVolume = 1,
+    loop = false,
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onDurationChange,
+    onError,
+  } = options;
+
+  const audioRef = useRef<HTMLAudioElement>(null);
+
+  // State
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [volume, setVolumeState] = useState(initialVolume);
+  const [isMuted, setIsMuted] = useState(false);
+  const [isLooping, setIsLooping] = useState(loop);
+  const [isReady, setIsReady] = useState(false);
+  const [buffered, setBuffered] = useState<TimeRanges | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  // ==========================================================================
+  // CONTROLS
+  // ==========================================================================
+
+  const play = useCallback(async () => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    try {
+      await audio.play();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Playback failed');
+      setError(error);
+      onError?.(error);
+    }
+  }, [onError]);
+
+  const pause = useCallback(() => {
+    audioRef.current?.pause();
+  }, []);
+
+  const togglePlay = useCallback(() => {
+    if (isPlaying) {
+      pause();
+    } else {
+      play();
+    }
+  }, [isPlaying, play, pause]);
+
+  const seek = useCallback((time: number) => {
+    const audio = audioRef.current;
+    if (!audio || !isFinite(time)) return;
+
+    const clampedTime = Math.max(0, Math.min(time, duration));
+    audio.currentTime = clampedTime;
+    setCurrentTime(clampedTime);
+  }, [duration]);
+
+  const seekTo = useCallback((progress: number) => {
+    const clampedProgress = Math.max(0, Math.min(progress, 1));
+    seek(duration * clampedProgress);
+  }, [duration, seek]);
+
+  const skip = useCallback((seconds: number) => {
+    seek(currentTime + seconds);
+  }, [currentTime, seek]);
+
+  const setVolume = useCallback((vol: number) => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    const clampedVol = Math.max(0, Math.min(vol, 1));
+    audio.volume = clampedVol;
+    setVolumeState(clampedVol);
+
+    if (clampedVol > 0 && isMuted) {
+      audio.muted = false;
+      setIsMuted(false);
+    }
+  }, [isMuted]);
+
+  const toggleMute = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    audio.muted = !audio.muted;
+    setIsMuted(audio.muted);
+  }, []);
+
+  const setLoop = useCallback((enabled: boolean) => {
+    const audio = audioRef.current;
+    if (audio) {
+      audio.loop = enabled;
+    }
+    setIsLooping(enabled);
+  }, []);
+
+  const toggleLoop = useCallback(() => {
+    setLoop(!isLooping);
+  }, [isLooping, setLoop]);
+
+  // ==========================================================================
+  // EVENT HANDLERS
+  // ==========================================================================
+
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    // Set initial properties
+    audio.volume = initialVolume;
+    audio.loop = loop;
+
+    const handleLoadedMetadata = () => {
+      setDuration(audio.duration);
+      setIsReady(true);
+      onDurationChange?.(audio.duration);
+    };
+
+    const handleCanPlay = () => {
+      setIsReady(true);
+      if (autoPlay) {
+        audio.play().catch(() => {});
+      }
+    };
+
+    const handlePlay = () => {
+      setIsPlaying(true);
+      onPlay?.();
+    };
+
+    const handlePause = () => {
+      setIsPlaying(false);
+      onPause?.();
+    };
+
+    const handleEnded = () => {
+      setIsPlaying(false);
+      if (!isLooping) {
+        onEnded?.();
+      }
+    };
+
+    const handleTimeUpdate = () => {
+      setCurrentTime(audio.currentTime);
+      onTimeUpdate?.(audio.currentTime);
+    };
+
+    const handleProgress = () => {
+      setBuffered(audio.buffered);
+    };
+
+    const handleError = () => {
+      const err = new Error(
+        audio.error?.message || 'Audio loading failed'
+      );
+      setError(err);
+      setIsReady(false);
+      onError?.(err);
+    };
+
+    const handleVolumeChange = () => {
+      setVolumeState(audio.volume);
+      setIsMuted(audio.muted);
+    };
+
+    // Add listeners
+    audio.addEventListener('loadedmetadata', handleLoadedMetadata);
+    audio.addEventListener('canplay', handleCanPlay);
+    audio.addEventListener('play', handlePlay);
+    audio.addEventListener('pause', handlePause);
+    audio.addEventListener('ended', handleEnded);
+    audio.addEventListener('timeupdate', handleTimeUpdate);
+    audio.addEventListener('progress', handleProgress);
+    audio.addEventListener('error', handleError);
+    audio.addEventListener('volumechange', handleVolumeChange);
+
+    return () => {
+      audio.removeEventListener('loadedmetadata', handleLoadedMetadata);
+      audio.removeEventListener('canplay', handleCanPlay);
+      audio.removeEventListener('play', handlePlay);
+      audio.removeEventListener('pause', handlePause);
+      audio.removeEventListener('ended', handleEnded);
+      audio.removeEventListener('timeupdate', handleTimeUpdate);
+      audio.removeEventListener('progress', handleProgress);
+      audio.removeEventListener('error', handleError);
+      audio.removeEventListener('volumechange', handleVolumeChange);
+    };
+  }, [
+    autoPlay,
+    initialVolume,
+    loop,
+    isLooping,
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onDurationChange,
+    onError,
+  ]);
+
+  // Update src
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    setIsReady(false);
+    setError(null);
+    setCurrentTime(0);
+    setDuration(0);
+    audio.src = src;
+    audio.load();
+  }, [src]);
+
+  return {
+    audioRef,
+    // State
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    isMuted,
+    isLooping,
+    isReady,
+    buffered,
+    error,
+    // Controls
+    play,
+    pause,
+    togglePlay,
+    seek,
+    seekTo,
+    skip,
+    setVolume,
+    toggleMute,
+    setLoop,
+    toggleLoop,
+  };
+}