@djangocfg/ui-nextjs 2.1.81 → 2.1.83

package/src/tools/AudioPlayer/@refactoring3/00-IMPLEMENTATION-ROADMAP.md

@@ -0,0 +1,1146 @@
+# Audio Player Implementation Roadmap
+
+**Date:** 2025-12-30
+**Status:** In Progress
+**Goal:** Create a robust audio player with streaming support and reactive visualizations without crackling
+
+---
+
+## Progress Summary
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| Phase 0 | ✅ **DONE** | Quick Fix for Crackling |
+| Phase 1 | ✅ **DONE** | Core Infrastructure |
+| Phase 2 | ✅ **DONE** | Visualization Integration |
+| Phase 3 | ✅ **DONE** | Player Components |
+| Phase 4 | ⏳ Pending | Integration & Testing |
+| Phase 5 | ✅ **DONE** | Cleanup |
+
+### Completed Files (2025-12-30)
+
+**Phase 0:**
+- `hooks/useSharedWebAudio.ts` - Fixed double audio routing
+
+**Phase 1:**
+- `hooks/useHybridAudio.ts` - Core hybrid audio hook
+- `hooks/useHybridAudioAnalysis.ts` - Audio frequency analysis for hybrid player
+- `context/HybridAudioProvider.tsx` - Context provider with state and controls
+
+**Phase 2:**
+- `components/HybridWaveform.tsx` - Real-time frequency visualization
+
+**Phase 3:**
+- `components/HybridAudioPlayer.tsx` - Main player with controls
+- `components/HybridSimplePlayer.tsx` - All-in-one wrapper with reactive cover
+
+**Phase 5 (Cleanup):**
+- Added `@deprecated` notices to legacy components (SimpleAudioPlayer, AudioPlayer, AudioProvider)
+- Added documentation notes to ProgressiveAudioPlayer
+- Removed old `@refactoring/` and `@refactoring2/` folders
+- Updated README.md with player comparison and migration guide
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Key Findings from Analysis](#key-findings-from-analysis)
+3. [Proposed Solution: Hybrid Audio Player](#proposed-solution-hybrid-audio-player)
+4. [Implementation Phases](#implementation-phases)
+5. [Files to Modify/Create](#files-to-modifycreate)
+6. [Code Examples](#code-examples)
+7. [Migration Guide](#migration-guide)
+8. [Testing Strategy](#testing-strategy)
+9. [Risk Assessment](#risk-assessment)
+10. [Timeline Estimate](#timeline-estimate)
+
+---
+
+## Executive Summary
+
+### Current Problems
+
+1. **Seek Limitation (>2 minutes):** Backend enforces 2MB chunk limit, preventing seek beyond buffered content
+2. **Audio Crackling:** Web Audio API double-routing causes audio artifacts when reactive effects are enabled
+3. **WaveSurfer Streaming:** WaveSurfer.js requires full file download for waveform - no true streaming support
+4. **Dual Player Complexity:** Maintaining both WaveSurfer and Progressive players creates duplication
+
+### Proposed Solution
+
+Implement a **Hybrid Audio Player** that:
+- Uses native HTML5 `<audio>` for playback (no crackling, native streaming)
+- Connects Web Audio API only for visualization (AnalyserNode)
+- Preserves all reactive cover effects (glow, orbs, spotlight, mesh)
+- Supports chunked/streaming audio with proper Range request handling
+
+---
+
+## Key Findings from Analysis
+
+### From WaveSurfer Streaming Analysis (01)
+
+| Feature | Support | Notes |
+|---------|---------|-------|
+| True streaming (MediaSource API) | **NO** | Not implemented |
+| Chunked fetch with progressive rendering | **NO** | Full download required |
+| Partial audio playback | **LIMITED** | Only with pre-decoded peaks |
+| Pre-computed peaks + streaming URL | **YES** | Recommended approach |
+
+**Key Insight:** WaveSurfer requires the **entire audio file** to be downloaded and decoded before rendering the waveform. For streaming, pre-computed peaks are required.
+
+### From Media Viewer Analysis (02)
+
+| Feature | SimpleAudioPlayer (WaveSurfer) | ProgressiveAudioPlayer |
+|---------|------------------------------|----------------------|
+| Audio Routing | Web Audio API | Native Browser |
+| Waveform | Pre-computed (needs full file) | Progressive (chunks) |
+| Seek | Limited by buffered data | Any position |
+| Reactive Effects | Yes | No |
+| Crackling Risk | High (Web Audio routing) | Low (direct playback) |
+| Streaming | Requires prefetch | Native support |
+
+### From Hybrid Architecture Proposal (03)
+
+The hybrid approach combines the best of both:
+
+```
+HTML5 <audio>     -->    MediaElementSource    -->    AnalyserNode    -->    Destination
+(native playback)        (bridge)                     (visualization)        (speakers)
+```
+
+- Native audio handles all playback concerns (buffering, seeking, streaming)
+- Web Audio only used for frequency analysis
+- Reactive effects continue to work unchanged
+
+### From Crackling Issue Diagnosis (04)
+
+**Root Cause:** Double audio routing in `useSharedWebAudio.ts`:
+
+```typescript
+// PROBLEM: Audio routed TWICE to destination
+sourceRef.current.connect(audioContext.destination);  // First connection
+// ...
+sourceRef.current.connect(analyser);
+analyser.connect(audioContext.destination);  // DUPLICATE path!
+```
+
+**Fix:** Analyser only needs connection to source for `getByteFrequencyData()` - it does NOT need to connect to destination:
+
+```typescript
+// CORRECT: Analyser as passive listener
+sourceRef.current.connect(analyser);
+// analyser.connect(destination) - NOT NEEDED!
+sourceRef.current.connect(audioContext.destination);  // Single path
+```
+
+### From Problem Analysis (01-cmdop)
+
+Backend chunk size limitation causes seek issues:
+
+| Bitrate | 2 MB Duration | Seek Limit |
+|---------|---------------|------------|
+| 128 kbps | 125 sec | ~2 min |
+| 192 kbps | 87 sec | ~1.5 min |
+| 256 kbps | 65 sec | ~1 min |
+
+### From Solution Options (02-cmdop)
+
+Recommended priority:
+1. **Option A** - Backend limit increase (Low effort, High impact)
+2. **Option B** - Progressive player (Done)
+3. **Option E** - Blob for small files (Low effort, Medium impact)
+4. **Option C** - MSE (High effort, High impact)
+5. **Option D** - HLS/DASH (High effort, High impact)
+
+---
+
+## Proposed Solution: Hybrid Audio Player
+
+### Architecture Overview
+
+```
+                              HYBRID AUDIO PLAYER ARCHITECTURE
++===============================================================================+
+|                                                                               |
+|  +-------------------------------------------------------------------------+  |
+|  |                          HybridAudioProvider                            |  |
+|  |  (React Context - manages all state and coordinates components)         |  |
+|  +-------------------------------------------------------------------------+  |
+|                                      |                                        |
+|          +---------------------------+---------------------------+            |
+|          |                           |                           |            |
+|          v                           v                           v            |
+|  +---------------+          +----------------+          +------------------+  |
+|  |    PLAYBACK   |          |  VISUALIZATION |          |  REACTIVE FX     |  |
+|  |    LAYER      |          |     LAYER      |          |     LAYER        |  |
+|  +---------------+          +----------------+          +------------------+  |
+|  |               |          |                |          |                  |  |
+|  | HTML5 <audio> |   --->   | MediaElement   |   --->   | useAudioAnalysis |  |
+|  | (native)      |          | SourceNode     |          | (bass/mid/high)  |  |
+|  |               |          |       |        |          |        |         |  |
+|  | - Range req   |          |       v        |          |        v         |  |
+|  | - Buffering   |          | AnalyserNode   |          | AudioReactive    |  |
+|  | - Seek        |          |       |        |          | Cover            |  |
+|  | - No crackling|          |       v        |          | - GlowEffect     |  |
+|  +-------+-------+          | Destination    |          | - OrbsEffect     |  |
+|          |                  +-------+--------+          | - SpotlightEffect|  |
+|          |                          |                   | - MeshEffect     |  |
+|          v                          v                   +------------------+  |
+|  +-------+-------+          +-------+--------+                                |
+|  | useAudioState |          | useSharedWeb   |                                |
+|  | - currentTime |          | Audio (fixed)  |                                |
+|  | - duration    |          +----------------+                                |
+|  | - buffered    |                                                            |
+|  | - isPlaying   |                                                            |
+|  +---------------+                                                            |
+|                                                                               |
++===============================================================================+
+```
+
+### Key Benefits
+
+1. **No Crackling:** HTML5 audio handles playback natively
+2. **Streaming Support:** Browser handles Range requests automatically
+3. **Reactive Effects Preserved:** AnalyserNode provides frequency data
+4. **Simpler Codebase:** Single player architecture instead of two
+5. **Better Memory Usage:** No full-file blob needed for playback
+
+---
+
+## Implementation Phases
+
+### Phase 0: Quick Fix for Crackling ✅ DONE
+
+**Goal:** Fix the crackling issue in existing WaveSurfer player without full refactoring
+
+**Changes:**
+- ✅ Modified `useSharedWebAudio.ts` to fix double-routing
+- ✅ Analyser connects only to source, not to destination
+
+**Completed:** 2025-12-30
+**File Changed:** `hooks/useSharedWebAudio.ts` (lines 80-84)
+**Impact:** Eliminates crackling immediately
+
+### Phase 1: Core Infrastructure ✅ DONE
+
+**Goal:** Create the core hybrid audio hooks and context
+
+**Deliverables:**
+- ✅ `useHybridAudio.ts` - Combined HTML5 audio + Web Audio hook
+- ✅ `useHybridAudioAnalysis.ts` - Frequency analysis for hybrid context
+- ✅ `HybridAudioProvider.tsx` - Context provider
+
+**Completed:** 2025-12-30
+
+### Phase 2: Visualization Integration ✅ DONE
+
+**Goal:** Connect visualization components to hybrid system
+
+**Deliverables:**
+- ✅ `HybridWaveform.tsx` - Real-time frequency visualization with seek support
+- ✅ Integrated with existing canvas rendering patterns
+
+**Completed:** 2025-12-30
+
+### Phase 3: Player Components ✅ DONE
+
+**Goal:** Build the new player components
+
+**Deliverables:**
+- ✅ `HybridAudioPlayer.tsx` - Main player with controls (play, pause, seek, volume, loop)
+- ✅ `HybridSimplePlayer.tsx` - All-in-one wrapper with reactive cover support
+
+**Completed:** 2025-12-30
+
+### Phase 4: Integration & Testing (Days 7-8)
+
+**Goal:** Integrate with existing application and test thoroughly
+
+**Deliverables:**
+- Update `AudioViewer.tsx` to use hybrid player
+- Migration guide for consumers
+- Comprehensive testing
+
+### Phase 5: Cleanup (Day 9-10)
+
+**Goal:** Remove deprecated code and finalize
+
+**Deliverables:**
+- Deprecate/remove WaveSurfer-based player
+- Update documentation
+- Performance optimization
+
+---
+
+## Files to Modify/Create
+
+### Files to Create
+
+| File | Purpose |
+|------|---------|
+| `hooks/useHybridAudio.ts` | Core hook combining HTML5 audio + Web Audio |
+| `context/HybridAudioProvider.tsx` | Context provider for hybrid player |
+| `components/HybridAudioPlayer.tsx` | Main hybrid player component |
+| `components/HybridSimplePlayer.tsx` | Simplified wrapper |
+| `components/HybridWaveform.tsx` | Real-time frequency visualization |
+
+### Files to Modify
+
+| File | Changes |
+|------|---------|
+| `hooks/useSharedWebAudio.ts` | **CRITICAL:** Fix double-routing issue |
+| `hooks/useAudioAnalysis.ts` | Minor updates for hybrid context |
+| `context/index.ts` | Export new HybridAudioProvider |
+| `components/index.ts` | Export new components |
+| `types/audio.ts` | Add hybrid types |
+
+### Files in cmdop to Modify
+
+| File | Changes |
+|------|---------|
+| `viewers/media/AudioViewer.tsx` | Use HybridSimplePlayer instead of mode toggle |
+
+### Backend Files to Consider
+
+| File | Changes |
+|------|---------|
+| `django/apps/terminal/views/api/media_stream/viewsets.py` | Increase audio chunk limit to 50MB |
+
+---
+
+## Code Examples
+
+### Fix 1: useSharedWebAudio.ts (Critical - Immediate)
+
+```typescript
+// hooks/useSharedWebAudio.ts
+
+// BEFORE (problematic):
+const initAudio = () => {
+  // ...
+  sourceRef.current = audioContext.createMediaElementSource(audioElement);
+  sourceRef.current.connect(audioContext.destination);  // First connection
+  // ...
+};
+
+const createAnalyser = useCallback(() => {
+  // ...
+  sourceRef.current.connect(analyser);
+  analyser.connect(audioContextRef.current.destination);  // DUPLICATE!
+  // ...
+});
+
+// AFTER (fixed):
+const initAudio = () => {
+  // ...
+  sourceRef.current = audioContext.createMediaElementSource(audioElement);
+  sourceRef.current.connect(audioContext.destination);  // Single path to destination
+  // ...
+};
+
+const createAnalyser = useCallback(() => {
+  // ...
+  // Analyser only needs connection to source for getByteFrequencyData()
+  // It does NOT need to connect to destination
+  sourceRef.current.connect(analyser);
+  // NO: analyser.connect(destination) - causes double routing!
+
+  analyserNodesRef.current.add(analyser);
+  return analyser;
+});
+```
+
+### Fix 2: useHybridAudio.ts (New)
+
+```typescript
+// hooks/useHybridAudio.ts
+import { useRef, useState, useCallback, useEffect } from 'react';
+
+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;
+}
+
+export interface AudioState {
+  isReady: boolean;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  isLooping: boolean;
+  buffered: TimeRanges | null;
+  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: (vol: number) => void;
+  toggleMute: () => void;
+  toggleLoop: () => void;
+}
+
+export interface WebAudioAPI {
+  context: AudioContext | null;
+  analyser: AnalyserNode | null;
+  sourceNode: MediaElementAudioSourceNode | null;
+}
+
+export function useHybridAudio(options: UseHybridAudioOptions) {
+  const {
+    src,
+    autoPlay = false,
+    initialVolume = 1,
+    loop = false,
+    crossOrigin = 'anonymous',
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onError,
+  } = 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);
+
+  // State
+  const [state, setState] = useState<AudioState>({
+    isReady: false,
+    isPlaying: false,
+    currentTime: 0,
+    duration: 0,
+    volume: initialVolume,
+    isMuted: false,
+    isLooping: loop,
+    buffered: null,
+    error: null,
+  });
+
+  // Initialize Web Audio for visualization
+  const initWebAudio = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio || audioContextRef.current) return;
+
+    try {
+      const AudioContextClass = window.AudioContext ||
+        (window as any).webkitAudioContext;
+      const ctx = new AudioContextClass();
+      audioContextRef.current = ctx;
+
+      // 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.8;
+      analyserRef.current = analyser;
+
+      // Connect: source -> analyser (for visualization)
+      source.connect(analyser);
+
+      // Connect: source -> destination (for playback)
+      // Note: analyser does NOT connect to destination - this prevents double audio
+      source.connect(ctx.destination);
+
+    } 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 controls: AudioControls = {
+    play: useCallback(async () => {
+      const audio = audioRef.current;
+      if (!audio) return;
+
+      try {
+        await resumeAudioContext();
+        await audio.play();
+      } catch (error) {
+        console.error('[useHybridAudio] Play failed:', error);
+        onError?.(error as Error);
+      }
+    }, [resumeAudioContext, onError]),
+
+    pause: useCallback(() => {
+      audioRef.current?.pause();
+    }, []),
+
+    togglePlay: useCallback(() => {
+      if (state.isPlaying) {
+        controls.pause();
+      } else {
+        controls.play();
+      }
+    }, [state.isPlaying]),
+
+    seek: useCallback((time: number) => {
+      const audio = audioRef.current;
+      if (audio && isFinite(time)) {
+        audio.currentTime = Math.max(0, Math.min(time, state.duration));
+      }
+    }, [state.duration]),
+
+    seekTo: useCallback((progress: number) => {
+      controls.seek(state.duration * progress);
+    }, [state.duration]),
+
+    skip: useCallback((seconds: number) => {
+      controls.seek(state.currentTime + seconds);
+    }, [state.currentTime]),
+
+    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 }));
+      }
+    }, []),
+
+    toggleMute: useCallback(() => {
+      const audio = audioRef.current;
+      if (audio) {
+        audio.muted = !audio.muted;
+        setState(prev => ({ ...prev, isMuted: audio.muted }));
+      }
+    }, []),
+
+    toggleLoop: useCallback(() => {
+      const audio = audioRef.current;
+      if (audio) {
+        audio.loop = !audio.loop;
+        setState(prev => ({ ...prev, isLooping: audio.loop }));
+      }
+    }, []),
+  };
+
+  // Event handlers
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    const handlers = {
+      loadedmetadata: () => {
+        setState(prev => ({
+          ...prev,
+          duration: audio.duration,
+          isReady: true,
+        }));
+      },
+      canplay: () => {
+        setState(prev => ({ ...prev, isReady: true }));
+        if (autoPlay) controls.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);
+      },
+    };
+
+    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]);
+
+  // Load new source
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+
+    setState(prev => ({
+      ...prev,
+      isReady: false,
+      currentTime: 0,
+      duration: 0,
+      error: null,
+    }));
+
+    audio.src = src;
+    audio.load();
+    initWebAudio();
+  }, [src, initWebAudio]);
+
+  // Create audio element
+  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 = '';
+      audioContextRef.current?.close();
+    };
+  }, []);
+
+  return {
+    audioRef,
+    state,
+    controls,
+    webAudio: {
+      context: audioContextRef.current,
+      analyser: analyserRef.current,
+      sourceNode: sourceNodeRef.current,
+    },
+  };
+}
+```
+
+### Fix 3: HybridAudioProvider.tsx (New)
+
+```typescript
+// context/HybridAudioProvider.tsx
+import React, { createContext, useContext, useRef, useMemo } from 'react';
+import { useHybridAudio, UseHybridAudioOptions, AudioState, AudioControls, WebAudioAPI } from '../hooks/useHybridAudio';
+import { useAudioAnalysis, AudioLevels } from '../hooks/useAudioAnalysis';
+
+interface HybridAudioContextValue {
+  // Audio state
+  state: AudioState;
+
+  // Controls
+  controls: AudioControls;
+
+  // Web Audio (for visualizations)
+  webAudio: WebAudioAPI;
+
+  // Audio levels (for reactive effects)
+  audioLevels: AudioLevels;
+
+  // Audio element ref (for custom integrations)
+  audioRef: React.RefObject<HTMLAudioElement | null>;
+}
+
+const HybridAudioContext = createContext<HybridAudioContextValue | null>(null);
+
+export interface HybridAudioProviderProps extends UseHybridAudioOptions {
+  children: React.ReactNode;
+}
+
+export function HybridAudioProvider({ children, ...options }: HybridAudioProviderProps) {
+  const { audioRef, state, controls, webAudio } = useHybridAudio(options);
+
+  // Audio analysis for reactive effects
+  const audioLevels = useAudioAnalysis(webAudio.analyser, state.isPlaying);
+
+  const value = useMemo<HybridAudioContextValue>(() => ({
+    state,
+    controls,
+    webAudio,
+    audioLevels,
+    audioRef,
+  }), [state, controls, webAudio, audioLevels, audioRef]);
+
+  return (
+    <HybridAudioContext.Provider value={value}>
+      {children}
+    </HybridAudioContext.Provider>
+  );
+}
+
+export function useHybridAudioContext() {
+  const context = useContext(HybridAudioContext);
+  if (!context) {
+    throw new Error('useHybridAudioContext must be used within HybridAudioProvider');
+  }
+  return context;
+}
+```
+
+### Fix 4: HybridWaveform.tsx (New)
+
+```typescript
+// components/HybridWaveform.tsx
+import React, { useRef, useEffect, useCallback } from 'react';
+import { useHybridAudioContext } from '../context/HybridAudioProvider';
+
+interface HybridWaveformProps {
+  mode?: 'frequency' | 'waveform';
+  peaks?: number[];
+  height?: number;
+  barWidth?: number;
+  barGap?: number;
+  progressColor?: string;
+  waveColor?: string;
+  bufferedColor?: string;
+  className?: string;
+  onSeek?: (time: number) => void;
+}
+
+export function HybridWaveform({
+  mode = 'frequency',
+  peaks,
+  height = 64,
+  barWidth = 3,
+  barGap = 1,
+  progressColor = 'rgba(59, 130, 246, 1)',
+  waveColor = 'rgba(59, 130, 246, 0.4)',
+  bufferedColor = 'rgba(255, 255, 255, 0.1)',
+  className,
+  onSeek,
+}: HybridWaveformProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const { state, controls, webAudio } = useHybridAudioContext();
+  const animationRef = useRef<number>();
+
+  // Handle seek on click
+  const handleClick = useCallback((e: React.MouseEvent<HTMLCanvasElement>) => {
+    const canvas = canvasRef.current;
+    if (!canvas || !state.duration) return;
+
+    const rect = canvas.getBoundingClientRect();
+    const x = e.clientX - rect.left;
+    const progress = x / rect.width;
+    const time = state.duration * progress;
+
+    controls.seek(time);
+    onSeek?.(time);
+  }, [state.duration, controls, onSeek]);
+
+  // Render frequency bars (real-time)
+  const renderFrequency = useCallback(() => {
+    const canvas = canvasRef.current;
+    const analyser = webAudio.analyser;
+    if (!canvas || !analyser) return;
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    const { width, height: canvasHeight } = canvas;
+    const bufferLength = analyser.frequencyBinCount;
+    const dataArray = new Uint8Array(bufferLength);
+    analyser.getByteFrequencyData(dataArray);
+
+    ctx.clearRect(0, 0, width, canvasHeight);
+
+    // Draw buffered regions
+    if (state.buffered && state.duration > 0) {
+      ctx.fillStyle = bufferedColor;
+      for (let i = 0; i < state.buffered.length; i++) {
+        const start = (state.buffered.start(i) / state.duration) * width;
+        const end = (state.buffered.end(i) / state.duration) * width;
+        ctx.fillRect(start, canvasHeight - 2, end - start, 2);
+      }
+    }
+
+    // Draw frequency bars
+    const barCount = Math.floor(width / (barWidth + barGap));
+    const step = Math.floor(bufferLength / barCount);
+    const progress = state.duration > 0 ? state.currentTime / state.duration : 0;
+    const progressX = width * progress;
+
+    for (let i = 0; i < barCount; i++) {
+      const value = dataArray[i * step] / 255;
+      const barHeight = value * canvasHeight * 0.9;
+      const x = i * (barWidth + barGap);
+      const y = canvasHeight - barHeight;
+
+      ctx.fillStyle = x < progressX ? progressColor : waveColor;
+      ctx.fillRect(x, y, barWidth, barHeight);
+    }
+
+    // Continue animation if playing
+    if (state.isPlaying) {
+      animationRef.current = requestAnimationFrame(renderFrequency);
+    }
+  }, [webAudio.analyser, state, barWidth, barGap, progressColor, waveColor, bufferedColor]);
+
+  // Render pre-computed waveform
+  const renderWaveform = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !peaks?.length) return;
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    const { width, height: canvasHeight } = canvas;
+
+    ctx.clearRect(0, 0, width, canvasHeight);
+
+    // Draw buffered regions
+    if (state.buffered && state.duration > 0) {
+      ctx.fillStyle = bufferedColor;
+      for (let i = 0; i < state.buffered.length; i++) {
+        const start = (state.buffered.start(i) / state.duration) * width;
+        const end = (state.buffered.end(i) / state.duration) * width;
+        ctx.fillRect(start, canvasHeight - 2, end - start, 2);
+      }
+    }
+
+    // Draw waveform
+    const barCount = Math.floor(width / (barWidth + barGap));
+    const peaksPerBar = Math.ceil(peaks.length / barCount);
+    const progress = state.duration > 0 ? state.currentTime / state.duration : 0;
+    const progressX = width * progress;
+
+    for (let i = 0; i < barCount; i++) {
+      // Average peaks for this bar
+      const startPeak = i * peaksPerBar;
+      const endPeak = Math.min(startPeak + peaksPerBar, peaks.length);
+      let sum = 0;
+      for (let j = startPeak; j < endPeak; j++) {
+        sum += Math.abs(peaks[j]);
+      }
+      const avg = sum / (endPeak - startPeak);
+
+      const barHeight = avg * canvasHeight * 0.9;
+      const x = i * (barWidth + barGap);
+      const y = (canvasHeight - barHeight) / 2;
+
+      ctx.fillStyle = x < progressX ? progressColor : waveColor;
+      ctx.fillRect(x, y, barWidth, barHeight);
+    }
+  }, [peaks, state, barWidth, barGap, progressColor, waveColor, bufferedColor]);
+
+  // Animation loop
+  useEffect(() => {
+    if (mode === 'frequency') {
+      renderFrequency();
+    } else {
+      renderWaveform();
+    }
+
+    return () => {
+      if (animationRef.current) {
+        cancelAnimationFrame(animationRef.current);
+      }
+    };
+  }, [mode, renderFrequency, renderWaveform, state.isPlaying]);
+
+  // Re-render waveform on time change (for static waveform mode)
+  useEffect(() => {
+    if (mode === 'waveform') {
+      renderWaveform();
+    }
+  }, [mode, state.currentTime, renderWaveform]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      height={height}
+      className={className}
+      onClick={handleClick}
+      style={{ width: '100%', cursor: 'pointer' }}
+    />
+  );
+}
+```
+
+### Fix 5: HybridSimplePlayer.tsx (New)
+
+```typescript
+// components/HybridSimplePlayer.tsx
+import React from 'react';
+import { HybridAudioProvider, HybridAudioProviderProps } from '../context/HybridAudioProvider';
+import { HybridAudioPlayer, HybridAudioPlayerProps } from './HybridAudioPlayer';
+import { AudioReactiveCover } from './ReactiveCover/AudioReactiveCover';
+import { VisualizationProvider } from '../context/VisualizationProvider';
+
+export interface HybridSimplePlayerProps extends Omit<HybridAudioProviderProps, 'children'> {
+  // Display options
+  title?: string;
+  artist?: string;
+  coverArt?: string;
+
+  // Features
+  showWaveform?: boolean;
+  showControls?: boolean;
+  showTimer?: boolean;
+  showVolume?: boolean;
+  showLoop?: boolean;
+
+  // Reactive cover
+  reactiveCover?: boolean;
+  variant?: 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none';
+
+  // Waveform mode
+  waveformMode?: 'frequency' | 'waveform';
+
+  // Styling
+  className?: string;
+}
+
+export function HybridSimplePlayer({
+  src,
+  title,
+  artist,
+  coverArt,
+  showWaveform = true,
+  showControls = true,
+  showTimer = true,
+  showVolume = true,
+  showLoop = true,
+  reactiveCover = false,
+  variant = 'spotlight',
+  waveformMode = 'frequency',
+  className,
+  ...audioOptions
+}: HybridSimplePlayerProps) {
+  return (
+    <VisualizationProvider>
+      <HybridAudioProvider src={src} {...audioOptions}>
+        <div className={className}>
+          {/* Reactive Cover Art */}
+          {coverArt && reactiveCover && variant !== 'none' && (
+            <AudioReactiveCover variant={variant}>
+              <img src={coverArt} alt={title || 'Cover'} />
+            </AudioReactiveCover>
+          )}
+
+          {/* Non-reactive Cover Art */}
+          {coverArt && (!reactiveCover || variant === 'none') && (
+            <img src={coverArt} alt={title || 'Cover'} />
+          )}
+
+          {/* Title and Artist */}
+          {(title || artist) && (
+            <div className="mb-2">
+              {title && <div className="font-medium">{title}</div>}
+              {artist && <div className="text-sm text-muted-foreground">{artist}</div>}
+            </div>
+          )}
+
+          {/* Player */}
+          <HybridAudioPlayer
+            showWaveform={showWaveform}
+            showControls={showControls}
+            showTimer={showTimer}
+            showVolume={showVolume}
+            showLoop={showLoop}
+            waveformMode={waveformMode}
+          />
+        </div>
+      </HybridAudioProvider>
+    </VisualizationProvider>
+  );
+}
+```
+
+---
+
+## Migration Guide
+
+### From WaveSurfer-based Player
+
+```tsx
+// BEFORE
+import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs/tools/AudioPlayer';
+
+<SimpleAudioPlayer
+  src={url}
+  showWaveform
+  reactiveCover
+  variant="spotlight"
+/>
+
+// AFTER
+import { HybridSimplePlayer } from '@djangocfg/ui-nextjs/tools/AudioPlayer';
+
+<HybridSimplePlayer
+  src={url}
+  showWaveform
+  reactiveCover
+  variant="spotlight"
+/>
+```
+
+### From Progressive Player
+
+```tsx
+// BEFORE
+import { ProgressiveAudioPlayer } from '@djangocfg/ui-nextjs/tools/AudioPlayer';
+
+<ProgressiveAudioPlayer
+  src={streamUrl}
+  showWaveform
+/>
+
+// AFTER
+import { HybridSimplePlayer } from '@djangocfg/ui-nextjs/tools/AudioPlayer';
+
+<HybridSimplePlayer
+  src={streamUrl}
+  showWaveform
+  waveformMode="frequency"  // Real-time visualization
+/>
+```
+
+### AudioViewer Migration
+
+```tsx
+// BEFORE (AudioViewer.tsx)
+{useProgressivePlayer ? (
+  <ProgressiveAudioPlayer src={src} ... />
+) : (
+  <SimpleAudioPlayer src={src} ... />
+)}
+
+// AFTER (AudioViewer.tsx)
+<HybridSimplePlayer
+  src={src}
+  reactiveCover
+  variant="spotlight"
+  ...
+/>
+// No mode toggle needed - hybrid player handles everything
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+1. `useHybridAudio` hook behavior
+   - State transitions (loading -> ready -> playing -> paused)
+   - Control functions (play, pause, seek, volume)
+   - Web Audio initialization
+
+2. Audio routing
+   - Source connects to destination once
+   - Analyser connects to source only
+   - No double routing
+
+### Integration Tests
+
+1. Full player rendering
+2. Reactive effects with audio levels
+3. Waveform visualization modes
+4. Buffered region display
+
+### Manual Testing Checklist
+
+- [ ] No crackling during normal playback
+- [ ] No crackling when seeking
+- [ ] No crackling with reactive effects enabled
+- [ ] Seek works beyond 2 minutes (with backend fix)
+- [ ] Volume control works correctly
+- [ ] Loop toggle works
+- [ ] Keyboard shortcuts work
+- [ ] Mobile touch controls work
+- [ ] Cross-browser: Chrome, Firefox, Safari, Edge
+
+### Test Files
+
+Test with various audio scenarios:
+- Small files (< 5MB)
+- Large files (> 50MB)
+- Streaming URLs
+- Different bitrates (128, 192, 256, 320 kbps)
+- Different formats (MP3, AAC, OGG)
+
+---
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Safari AudioContext issues | Medium | High | Test webkit prefix, add fallbacks |
+| CORS with streaming | Medium | Medium | Ensure crossOrigin="anonymous" |
+| Breaking existing code | Medium | High | Keep old components, provide migration guide |
+| Performance on mobile | Medium | Medium | Lower fftSize, reduce frame rate |
+| Memory leaks | Low | Medium | Proper cleanup in useEffect |
+
+---
+
+## Timeline Estimate
+
+| Phase | Duration | Dependencies |
+|-------|----------|--------------|
+| Phase 0: Quick Fix | 1 hour | None |
+| Phase 1: Core Infrastructure | 2 days | Phase 0 |
+| Phase 2: Visualization | 2 days | Phase 1 |
+| Phase 3: Player Components | 2 days | Phase 2 |
+| Phase 4: Integration & Testing | 2 days | Phase 3 |
+| Phase 5: Cleanup | 2 days | Phase 4 |
+
+**Total: ~10 days** (can be parallelized)
+
+### Recommended Approach
+
+1. **Immediately:** Apply Phase 0 fix to eliminate crackling
+2. **Short-term:** Implement Phases 1-3 for hybrid player
+3. **Medium-term:** Phase 4 integration and testing
+4. **Long-term:** Phase 5 cleanup and deprecation
+
+---
+
+## Appendix: Related Files Reference
+
+### Analysis Documents
+- `01-WAVESURFER-STREAMING-ANALYSIS.md` - WaveSurfer.js streaming limitations
+- `02-MEDIA-VIEWER-ANALYSIS.md` - Current player architecture comparison
+- `03-HYBRID-ARCHITECTURE-PROPOSAL.md` - Detailed hybrid design
+- `04-CRACKLING-ISSUE-DIAGNOSIS.md` - Root cause and fixes
+
+### External References
+- `cmdop/.../01-PROBLEM-ANALYSIS.md` - Backend chunk limit issue
+- `cmdop/.../02-SOLUTION-OPTIONS.md` - Solution comparison
+
+### Source Files to Reference
+- `hooks/useSharedWebAudio.ts` - Current Web Audio routing
+- `hooks/useAudioAnalysis.ts` - Audio level calculation
+- `progressive/useAudioElement.ts` - Native audio hook reference
+- `progressive/WaveformCanvas.tsx` - Canvas rendering reference
+- `context/AudioProvider.tsx` - Current WaveSurfer context
+
+---
+
+**End of Implementation Roadmap**