@djangocfg/ui-nextjs 2.1.82 → 2.1.83

package/src/tools/AudioPlayer/@refactoring2/PLAN.md

@@ -1,372 +0,0 @@
-# Progressive Audio Player - План рефакторинга
-
-## Проблема
-
-WaveSurfer.js требует полной загрузки аудиофайла для рендеринга waveform. При HTTP Range streaming backend возвращает только 2MB chunks, что приводит к:
-- Seek на позицию > 2 минут не работает
-- После неудачного seek плеер "зависает"
-
-## Решение
-
-Создать собственный `ProgressiveAudioPlayer` который:
-1. Использует HTML5 `<audio>` для воспроизведения (нативные Range requests)
-2. Рисует waveform прогрессивно по мере загрузки
-3. Визуально показывает загруженную/незагруженную область
-4. Полный контроль над seek поведением
-
----
-
-## Архитектура
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  ProgressiveAudioPlayer                                      │
-├──────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │  WaveformCanvas                                        │  │
-│  │  ┌──────────────────┬─────────────────────────────────┐│  │
-│  │  │ ████████████████ │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ││  │
-│  │  │ (загружено)      │ (placeholder/loading)           ││  │
-│  │  └──────────────────┴─────────────────────────────────┘│  │
-│  │  ▲ cursor                                              │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                              │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │  <audio> (hidden) - нативный HTML5 player              │  │
-│  │  - src={streamingUrl}                                  │  │
-│  │  - браузер сам делает Range requests                   │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                              │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │  Controls                                              │  │
-│  │  [⏮] [▶/⏸] [⏭] [🔊━━━━] [🔁]  00:00 / 03:45          │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Компоненты
-
-### 1. `useProgressiveWaveform` - хук для загрузки и декодирования
-
-```typescript
-interface UseProgressiveWaveformOptions {
-  url: string;
-  chunkSize?: number;      // размер chunk для загрузки (default: 512KB)
-  samplesPerChunk?: number; // сколько peaks на chunk (default: 100)
-}
-
-interface UseProgressiveWaveformReturn {
-  peaks: number[];           // массив peaks [0-1]
-  loadedPercent: number;     // сколько загружено (0-100)
-  isLoading: boolean;
-  error: Error | null;
-  loadedRanges: [number, number][]; // загруженные диапазоны
-}
-```
-
-**Алгоритм:**
-1. Получить Content-Length через HEAD запрос
-2. Разбить на chunks
-3. Загружать chunks последовательно или параллельно
-4. Декодировать через AudioContext.decodeAudioData()
-5. Извлечь peaks из decoded buffer
-6. Обновлять состояние по мере загрузки
-
-### 2. `WaveformCanvas` - canvas компонент
-
-```typescript
-interface WaveformCanvasProps {
-  peaks: number[];
-  loadedPercent: number;
-  currentTime: number;
-  duration: number;
-  buffered: TimeRanges;      // из audio.buffered
-  onSeek: (time: number) => void;
-
-  // Стилизация
-  waveColor?: string;
-  progressColor?: string;
-  loadingColor?: string;     // цвет незагруженной области
-  cursorColor?: string;
-  barWidth?: number;
-  barGap?: number;
-  height?: number;
-}
-```
-
-**Отрисовка:**
-1. Фон - незагруженная область (полупрозрачная или placeholder pattern)
-2. Загруженные peaks - основной цвет
-3. Проигранная часть - progressColor
-4. Курсор текущей позиции
-5. Buffered ranges индикатор (тонкая полоса снизу)
-
-### 3. `useAudioElement` - хук для управления audio
-
-```typescript
-interface UseAudioElementOptions {
-  src: string;
-  autoPlay?: boolean;
-  onTimeUpdate?: (time: number) => void;
-  onDurationChange?: (duration: number) => void;
-  onBufferUpdate?: (buffered: TimeRanges) => void;
-  onEnded?: () => void;
-  onError?: (error: Error) => void;
-}
-
-interface UseAudioElementReturn {
-  audioRef: RefObject<HTMLAudioElement>;
-  isPlaying: boolean;
-  currentTime: number;
-  duration: number;
-  volume: number;
-  isMuted: boolean;
-  buffered: TimeRanges;
-
-  // Actions
-  play: () => Promise<void>;
-  pause: () => void;
-  seek: (time: number) => void;
-  setVolume: (vol: number) => void;
-  toggleMute: () => void;
-}
-```
-
-### 4. `ProgressiveAudioPlayer` - главный компонент
-
-```typescript
-interface ProgressiveAudioPlayerProps {
-  src: string;
-  title?: string;
-  artist?: string;
-  coverArt?: string;
-
-  // Features
-  showWaveform?: boolean;
-  showControls?: boolean;
-  showTimer?: boolean;
-  showVolume?: boolean;
-  showLoop?: boolean;
-
-  // Callbacks
-  onPlay?: () => void;
-  onPause?: () => void;
-  onEnded?: () => void;
-  onError?: (error: Error) => void;
-
-  // Styling
-  className?: string;
-  waveformOptions?: WaveformOptions;
-}
-```
-
-### 5. `ProgressiveAudioContext` - контекст (опционально)
-
-Для совместимости с существующими хуками:
-- `useAudioControls()`
-- `useAudioState()`
-- `useAudioElement()`
-
----
-
-## Файловая структура
-
-```
-AudioPlayer/
-├── @refactoring2/
-│   └── PLAN.md (этот файл)
-│
-├── components/
-│   ├── ProgressiveAudioPlayer.tsx    # NEW - главный компонент
-│   ├── WaveformCanvas.tsx            # NEW - canvas waveform
-│   ├── AudioPlayer.tsx               # существующий (WaveSurfer)
-│   └── SimpleAudioPlayer.tsx         # существующий
-│
-├── hooks/
-│   ├── useProgressiveWaveform.ts     # NEW - загрузка + декодирование
-│   ├── useAudioElement.ts            # NEW - управление audio
-│   ├── useWaveformRenderer.ts        # NEW - рендеринг на canvas
-│   └── useAudioHotkeys.ts            # существующий (переиспользуем)
-│
-├── context/
-│   ├── ProgressiveAudioProvider.tsx  # NEW - контекст
-│   └── AudioProvider.tsx             # существующий (WaveSurfer)
-│
-├── utils/
-│   ├── peaks.ts                      # NEW - извлечение peaks
-│   ├── audioDecoder.ts               # NEW - декодирование chunks
-│   └── formatTime.ts                 # существующий
-│
-└── types/
-    └── progressive.ts                # NEW - типы
-```
-
----
-
-## Этапы реализации
-
-### Этап 1: Базовые хуки (core) ✅ DONE
-
-**Файлы:**
-- `progressive/useAudioElement.ts` ✅
-- `progressive/peaks.ts` ✅
-- `progressive/types.ts` ✅
-
-**Задачи:**
-1. [x] Создать `useAudioElement` - обёртка над HTMLAudioElement
-2. [x] Создать `extractPeaks(audioBuffer)` - извлечение peaks из AudioBuffer
-3. [x] Создать утилиты для peaks (merge, resample, smooth)
-4. [x] Типы для всех новых компонентов
-
-### Этап 2: Progressive загрузка ✅ DONE
-
-**Файлы:**
-- `progressive/useProgressiveWaveform.ts` ✅
-
-**Задачи:**
-1. [x] HEAD запрос для Content-Length
-2. [x] Chunked fetch с Range headers
-3. [x] Декодирование каждого chunk
-4. [x] Накопление peaks в состоянии
-5. [x] Обработка ошибок и retry
-
-### Этап 3: Canvas рендеринг ✅ DONE
-
-**Файлы:**
-- `progressive/WaveformCanvas.tsx` ✅
-
-**Задачи:**
-1. [x] Canvas setup с правильным DPI
-2. [x] Рендеринг peaks (bars)
-3. [x] Progress overlay (проигранная часть)
-4. [x] Loading indicator для незагруженной части
-5. [x] Cursor (текущая позиция)
-6. [x] Buffered ranges indicator
-7. [x] Click/drag для seek
-8. [x] Hover preview
-
-### Этап 4: Главный компонент ✅ DONE
-
-**Файлы:**
-- `progressive/ProgressiveAudioPlayer.tsx` ✅
-- `progressive/index.ts` ✅
-
-**Задачи:**
-1. [x] Собрать всё вместе
-2. [x] Controls UI (play/pause, volume, etc.)
-3. [x] Timer display
-4. [x] Export из index.ts
-5. [ ] Keyboard shortcuts (переиспользовать useAudioHotkeys) - TODO
-
-### Этап 5: Интеграция и тесты 🔄 IN PROGRESS
-
-**Задачи:**
-1. [x] Export из AudioPlayer/index.ts
-2. [ ] Обновить AudioViewer в cmdop - использовать ProgressiveAudioPlayer
-3. [ ] Playground example
-4. [ ] Тестирование с разными форматами/размерами
-5. [ ] Добавить Context для совместимости с существующими хуками
-
----
-
-## Технические детали
-
-### Декодирование chunks
-
-```typescript
-async function decodeChunk(
-  chunk: ArrayBuffer,
-  audioContext: AudioContext
-): Promise<Float32Array> {
-  // Для MP3/AAC нужен полный frame
-  // Возможно потребуется накопление данных
-  const audioBuffer = await audioContext.decodeAudioData(chunk);
-  return audioBuffer.getChannelData(0); // mono
-}
-```
-
-**Проблема:** `decodeAudioData` требует валидный аудио-контейнер. Для streaming нужно:
-- Либо накапливать достаточно данных для декодирования
-- Либо использовать Web Codecs API (AudioDecoder)
-- Либо генерировать peaks на backend
-
-### Альтернатива: Backend peaks
-
-Если декодирование на frontend сложное, можно:
-1. Go генерирует peaks через FFmpeg при первом запросе
-2. Кэширует в файл рядом с аудио
-3. Frontend загружает peaks JSON отдельно
-
-```bash
-# FFmpeg генерация peaks
-ffmpeg -i audio.mp3 -af "asetnsamples=n=1024,astats=metadata=1:reset=1" -f null - 2>&1 | grep lavfi.astats
-```
-
-Или использовать `audiowaveform`:
-```bash
-audiowaveform -i audio.mp3 -o peaks.json --pixels-per-second 10
-```
-
----
-
-## Миграция
-
-### Для cmdop AudioViewer
-
-```typescript
-// Было:
-<SimpleAudioPlayer src={streamUrl} showWaveform />
-
-// Стало:
-<ProgressiveAudioPlayer src={streamUrl} showWaveform />
-```
-
-### Backwards compatibility
-
-- Существующие компоненты остаются для blob/local файлов
-- `ProgressiveAudioPlayer` для streaming URLs
-- `SimpleAudioPlayer` получает prop `progressive?: boolean`
-
----
-
-## Оценка сложности
-
-| Компонент | Сложность | Строки кода |
-|-----------|-----------|-------------|
-| useAudioElement | Низкая | ~80 |
-| peaks utils | Низкая | ~50 |
-| useProgressiveWaveform | Высокая | ~150 |
-| WaveformCanvas | Средняя | ~200 |
-| ProgressiveAudioPlayer | Средняя | ~150 |
-| Context | Низкая | ~100 |
-| **Итого** | | **~730** |
-
-**Сравнение:** WaveSurfer.js = ~15,000 строк
-
----
-
-## Риски и альтернативы
-
-### Риск 1: decodeAudioData требует полный файл
-
-**Решение:** Использовать Web Codecs API или генерировать peaks на backend
-
-### Риск 2: Производительность canvas на длинных треках
-
-**Решение:** Виртуализация - рендерить только видимую область
-
-### Риск 3: Совместимость браузеров
-
-**Решение:** AudioContext поддерживается везде, Web Codecs - fallback на backend peaks
-
----
-
-## Следующий шаг
-
-Начать с **Этапа 1** - базовые хуки и утилиты.
-
-Или сначала проверить **backend peaks** подход - если Go может генерировать peaks, это упростит frontend.