@djangocfg/ui-nextjs 2.1.70 → 2.1.72

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

@@ -0,0 +1,267 @@
+'use client';
+
+/**
+ * useProgressiveWaveform - Hook for progressive audio waveform loading
+ *
+ * Fetches audio in chunks, decodes progressively, and extracts peaks.
+ * Provides loading state and partial waveform data as it loads.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { extractPeaks, mergePeaks } from './peaks';
+import type { LoadedRange, DecoderOptions } from './types';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DEFAULT_CHUNK_SIZE = 512 * 1024; // 512KB
+const DEFAULT_PEAKS_PER_SECOND = 50;
+const MAX_PARALLEL_FETCHES = 2;
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface UseProgressiveWaveformOptions extends DecoderOptions {
+  /** Audio source URL */
+  url: string;
+  /** Known duration (from metadata) - improves initial render */
+  duration?: number;
+  /** Enabled */
+  enabled?: boolean;
+}
+
+interface UseProgressiveWaveformReturn {
+  /** Accumulated peaks (0-1 normalized) */
+  peaks: number[];
+  /** Loading progress (0-100) */
+  loadedPercent: number;
+  /** Is currently loading */
+  isLoading: boolean;
+  /** Is complete */
+  isComplete: boolean;
+  /** Error if any */
+  error: Error | null;
+  /** Loaded ranges (for visual indication) */
+  loadedRanges: LoadedRange[];
+  /** Detected duration */
+  detectedDuration: number;
+  /** Retry loading */
+  retry: () => void;
+}
+
+// =============================================================================
+// AUDIO CONTEXT SINGLETON
+// =============================================================================
+
+let audioContextInstance: AudioContext | null = null;
+
+function getAudioContext(): AudioContext {
+  if (!audioContextInstance) {
+    audioContextInstance = new (window.AudioContext || (window as any).webkitAudioContext)();
+  }
+  return audioContextInstance;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useProgressiveWaveform(
+  options: UseProgressiveWaveformOptions
+): UseProgressiveWaveformReturn {
+  const {
+    url,
+    duration: knownDuration,
+    enabled = true,
+    chunkSize = DEFAULT_CHUNK_SIZE,
+    peaksPerSecond = DEFAULT_PEAKS_PER_SECOND,
+    parallelFetches = MAX_PARALLEL_FETCHES,
+  } = options;
+
+  // State
+  const [peaks, setPeaks] = useState<number[]>([]);
+  const [loadedPercent, setLoadedPercent] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isComplete, setIsComplete] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [loadedRanges, setLoadedRanges] = useState<LoadedRange[]>([]);
+  const [detectedDuration, setDetectedDuration] = useState(knownDuration || 0);
+
+  // Refs
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const accumulatedDataRef = useRef<ArrayBuffer[]>([]);
+  const totalSizeRef = useRef(0);
+  const loadedSizeRef = useRef(0);
+  const retryCountRef = useRef(0);
+
+  // ==========================================================================
+  // DECODE ACCUMULATED DATA
+  // ==========================================================================
+
+  const decodeAccumulated = useCallback(async () => {
+    const chunks = accumulatedDataRef.current;
+    if (chunks.length === 0) return;
+
+    try {
+      // Combine all chunks
+      const totalLength = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+      const combined = new Uint8Array(totalLength);
+      let offset = 0;
+      for (const chunk of chunks) {
+        combined.set(new Uint8Array(chunk), offset);
+        offset += chunk.byteLength;
+      }
+
+      // Decode
+      const audioContext = getAudioContext();
+      const audioBuffer = await audioContext.decodeAudioData(combined.buffer.slice(0));
+
+      // Extract peaks
+      const targetPeaks = Math.ceil(audioBuffer.duration * peaksPerSecond);
+      const newPeaks = extractPeaks(audioBuffer, { length: targetPeaks });
+
+      setPeaks(newPeaks);
+      setDetectedDuration(audioBuffer.duration);
+    } catch (err) {
+      // Decoding failed - might need more data
+      // This is expected for partial MP3 data
+      console.debug('Decode attempt failed, waiting for more data');
+    }
+  }, [peaksPerSecond]);
+
+  // ==========================================================================
+  // FETCH LOGIC
+  // ==========================================================================
+
+  const loadWaveform = useCallback(async () => {
+    if (!url || !enabled) return;
+
+    // Abort previous
+    abortControllerRef.current?.abort();
+    abortControllerRef.current = new AbortController();
+    const { signal } = abortControllerRef.current;
+
+    // Reset state
+    setIsLoading(true);
+    setIsComplete(false);
+    setError(null);
+    setPeaks([]);
+    setLoadedRanges([]);
+    setLoadedPercent(0);
+    accumulatedDataRef.current = [];
+    loadedSizeRef.current = 0;
+
+    try {
+      // Get file size with HEAD request
+      const headResponse = await fetch(url, { method: 'HEAD', signal });
+      const contentLength = headResponse.headers.get('content-length');
+      const totalSize = contentLength ? parseInt(contentLength, 10) : 0;
+      totalSizeRef.current = totalSize;
+
+      if (totalSize === 0) {
+        // Fallback: fetch entire file
+        const response = await fetch(url, { signal });
+        const data = await response.arrayBuffer();
+        accumulatedDataRef.current = [data];
+        await decodeAccumulated();
+        setIsComplete(true);
+        setLoadedPercent(100);
+        setIsLoading(false);
+        return;
+      }
+
+      // Fetch in chunks
+      let offset = 0;
+      const ranges: LoadedRange[] = [];
+
+      while (offset < totalSize) {
+        if (signal.aborted) return;
+
+        const end = Math.min(offset + chunkSize - 1, totalSize - 1);
+
+        const response = await fetch(url, {
+          headers: { Range: `bytes=${offset}-${end}` },
+          signal,
+        });
+
+        if (!response.ok && response.status !== 206) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const chunk = await response.arrayBuffer();
+        accumulatedDataRef.current.push(chunk);
+        loadedSizeRef.current += chunk.byteLength;
+
+        // Update progress
+        const progress = (loadedSizeRef.current / totalSize) * 100;
+        setLoadedPercent(progress);
+
+        // Update ranges
+        const rangeStart = offset / totalSize;
+        const rangeEnd = (offset + chunk.byteLength) / totalSize;
+        ranges.push({ start: rangeStart, end: rangeEnd });
+        setLoadedRanges([...ranges]);
+
+        // Try to decode periodically
+        if (accumulatedDataRef.current.length % 2 === 0 || offset + chunkSize >= totalSize) {
+          await decodeAccumulated();
+        }
+
+        offset += chunkSize;
+      }
+
+      // Final decode
+      await decodeAccumulated();
+      setIsComplete(true);
+    } catch (err) {
+      if ((err as Error).name === 'AbortError') return;
+
+      const error = err instanceof Error ? err : new Error('Loading failed');
+      setError(error);
+      console.error('Waveform loading error:', error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [url, enabled, chunkSize, decodeAccumulated]);
+
+  // ==========================================================================
+  // RETRY
+  // ==========================================================================
+
+  const retry = useCallback(() => {
+    retryCountRef.current += 1;
+    loadWaveform();
+  }, [loadWaveform]);
+
+  // ==========================================================================
+  // EFFECTS
+  // ==========================================================================
+
+  useEffect(() => {
+    loadWaveform();
+
+    return () => {
+      abortControllerRef.current?.abort();
+    };
+  }, [loadWaveform]);
+
+  // Update duration from prop
+  useEffect(() => {
+    if (knownDuration && knownDuration > 0 && detectedDuration === 0) {
+      setDetectedDuration(knownDuration);
+    }
+  }, [knownDuration, detectedDuration]);
+
+  return {
+    peaks,
+    loadedPercent,
+    isLoading,
+    isComplete,
+    error,
+    loadedRanges,
+    detectedDuration,
+    retry,
+  };
+}

package/src/tools/VideoPlayer/providers/VidstackProvider.tsx

@@ -17,19 +17,14 @@ import { MediaPlayer, MediaProvider, Poster } from '@vidstack/react';
 import { defaultLayoutIcons, DefaultVideoLayout } from '@vidstack/react/player/layouts/default';
 import { useVideoCache } from '../../../stores/mediaCache';
 
-import type { MediaPlayerInstance } from '@vidstack/react';
+import type { MediaPlayerInstance, PlayerSrc } from '@vidstack/react';
 import type { VidstackProviderProps, VideoPlayerRef, ErrorFallbackProps } from '../types';
 
-/**
- * Vidstack source type (string or object with type hint)
- */
-type VidstackSrc = string | { src: string; type: string };
-
 /**
  * Convert source to Vidstack-compatible format
  * Returns object with explicit type for HLS/DASH to ensure proper loader selection
  */
-function getVidstackSrc(source: VidstackProviderProps['source']): VidstackSrc {
+function getVidstackSrc(source: VidstackProviderProps['source']): PlayerSrc {
   switch (source.type) {
     case 'youtube':
       return `youtube/${source.id}`;
@@ -37,9 +32,9 @@ function getVidstackSrc(source: VidstackProviderProps['source']): VidstackSrc {
       return `vimeo/${source.id}`;
     case 'hls':
       // Explicit type needed because URL may have query params that hide .m3u8 extension
-      return { src: source.url, type: 'application/x-mpegurl' };
+      return { src: source.url, type: 'application/x-mpegurl' } as PlayerSrc;
     case 'dash':
-      return { src: source.url, type: 'application/dash+xml' };
+      return { src: source.url, type: 'application/dash+xml' } as PlayerSrc;
     case 'url':
       return source.url;
     default:

package/src/tools/index.ts

@@ -101,6 +101,15 @@ export {
   VARIANT_INFO,
   INTENSITY_INFO,
   COLOR_SCHEME_INFO,
+  // Progressive Audio Player (streaming-friendly)
+  ProgressiveAudioPlayer,
+  WaveformCanvas,
+  useProgressiveAudioElement,
+  useProgressiveWaveform,
+  extractPeaks,
+  mergePeaks,
+  resamplePeaks,
+  smoothPeaks,
 } from './AudioPlayer';
 export type {
   SimpleAudioPlayerProps,
@@ -120,6 +129,13 @@ export type {
   AudioHotkeyOptions,
   ShortcutItem,
   ShortcutGroup,
+  // Progressive types
+  ProgressiveAudioPlayerProps,
+  WaveformStyle,
+  WaveformData,
+  LoadedRange,
+  ProgressiveAudioState,
+  ProgressiveAudioControls,
 } from './AudioPlayer';
 
 // Export ImageViewer