adaptive-video-converter/docs/FEATURES.md

# Возможности Adaptive Video Converter

## Архитектура

Конвертация выполняется в два этапа для обеспечения стабильности и максимальной производительности:

**Этап 1: Кодирование** - тяжелая работа по перекодированию видео во все профили качества с использованием FFmpeg и NVENC.

**Этап 2: Упаковка DASH** - быстрая упаковка готовых MP4 файлов в DASH формат через MP4Box с генерацией манифеста.

Преимущества подхода:
- Стабильность: MP4Box специализируется на DASH, FFmpeg - на кодирование
- Параллелизм: все профили кодируются одновременно на GPU
- Надежность: разделение ответственности между инструментами

## Этап 1: Оптимизация и кодирование

### Стандартные профили разрешений

Автоматически создаются профили с частотой 30 FPS:
- 360p (640x360) - 800 kbps
- 480p (854x480) - 1200 kbps
- 720p (1280x720) - 2800 kbps
- 1080p (1920x1080) - 5000 kbps

### Опциональные профили высокого разрешения

Создаются только если исходное видео имеет соответствующее или более высокое разрешение:
- 2K (2560x1440) - если исходное >= 1440p
- 4K (3840x2160) - если исходное >= 2160p

Система автоматически определяет разрешение исходного видео и создает только применимые профили без upscaling.

### Высокочастотные профили

Система автоматически определяет частоту кадров исходного видео и создает дополнительные высокочастотные профили только если это поддерживается оригиналом:

- **Оригинал >= 45 FPS**: создаются профили @ 60 FPS для всех разрешений
- **Оригинал >= 75 FPS**: создаются профили @ 90 FPS для всех разрешений
- **Оригинал >= 95 FPS**: создаются профили @ 120 FPS для всех разрешений

Стандартные 30 FPS профили создаются всегда.

Пример: если исходное видео 60 FPS, будут созданы:
- 360p @ 30fps, 360p @ 60fps
- 480p @ 30fps, 480p @ 60fps
- 720p @ 30fps, 720p @ 60fps
- 1080p @ 30fps, 1080p @ 60fps

Интерполяция кадров не применяется - создаются только те частоты, которые нативно поддерживаются исходным материалом.

### Технические особенности

- **NVENC GPU ускорение**: аппаратное кодирование на видеокарте NVIDIA
- **GOP size выравнивание**: keyframe каждые N кадров для точной сегментации (N = FPS × segment_duration)
- **VBR режим**: переменный битрейт для оптимального качества
- **Умное кодирование аудио**: автоматический выбор оптимального битрейта без upscaling
  - Целевой максимум: 256 kbps AAC стерео
  - Фактический битрейт: `min(source_bitrate, 256 kbps)`
  - Округление до стандартных значений: 64k, 96k, 128k, 192k, 256k
  - Примеры: исходник 64 kbps → выход 64 kbps | исходник 320 kbps → выход 256 kbps

## Этап 2: Создание DASH

### Упаковка через MP4Box

- Создание фрагментированных MP4 сегментов длительностью 2 секунды
- Генерация единого MPD манифеста для всех профилей
- Выравнивание сегментов по Random Access Points (RAP)

### Организация файловой структуры

После упаковки файлы автоматически организуются в подпапки:
- Видео сегменты: `{resolution}/`
- Аудио сегменты: `audio/`
- Манифест: корень директории

Пути в MPD манифесте обновляются для соответствия структуре подпапок.

## Множественные аудио дорожки

### Поддержка озвучек и языков

Система поддерживает несколько аудио дорожек с различными источниками:

**Извлечение из видео**:
- Автоматическое извлечение всех аудио дорожек из входного файла
- Выбор конкретных дорожек по индексу

**Внешние файлы**:
- Добавление аудио из отдельных файлов (MP3, AAC, M4A)
- Синхронизация с видео

### Метаданные аудио дорожек

Каждая дорожка содержит метаданные для правильного отображения в плеере:

- **language**: код языка (ru, en, ja)
- **label**: название озвучки ("Кубик в кубе", "LostFilm", "Original")
- **role**: тип озвучки
  - `main` - основная
  - `dub` - дубляж
  - `commentary` - комментарии

Пример структуры в MPD:
```xml
<AdaptationSet lang="ru" label="Кубик в кубе">
  <Role schemeIdUri="urn:mpeg:dash:role:2011" value="dub"/>
  <Representation id="audio_kubik" .../>
</AdaptationSet>
```

## Генерация постера

### Автоматический режим

По умолчанию постер создается из первого кадра видео (00:00:00).

### Указание таймкода

Возможно указание конкретного времени для извлечения постера:

Формат:
- `MM:SS` - минуты:секунды (например, `06:32`)
- `HH:MM:SS` - часы:минуты:секунды (например, `01:23:45`)

Команда:
```bash
--poster-time 06:32
```

Постер сохраняется в формате JPEG с оптимизированным качеством.

## Превью спрайты

### Thumbnail спрайты

Автоматическая генерация спрайта с миниатюрами для навигации по видео:

- **Интервал**: 1 секунда (по умолчанию)
- **Размер миниатюры**: 160x90 пикселей
- **Сетка**: 10 колонок, динамическое количество строк
- **Формат**: JPEG sprite

### WebVTT файл

Генерируется VTT файл с координатами каждой миниатюры:

```vtt
WEBVTT

00:00:00.000 --> 00:00:01.000
thumbnails.jpg#xywh=0,0,160,90

00:00:01.000 --> 00:00:02.000
thumbnails.jpg#xywh=160,0,160,90
```

Плееры используют VTT для отображения превью при наведении на timeline.

## Выходная структура файлов

### Организация директорий

```
output/
└── video-name/
    ├── manifest.mpd              # Главный DASH манифест
    ├── poster.jpg                # Постер видео
    ├── thumbnails.jpg            # Спрайт превью
    ├── thumbnails.vtt            # WebVTT для превью
    ├── audio/                    # Аудио дорожки
    │   ├── audio_init.m4s        # Инициализационный сегмент
    │   ├── audio_1.m4s           # Сегмент #1
    │   └── audio_N.m4s           # Сегмент #N
    ├── 1080p/                    # Профиль 1080p @ 30fps
    │   ├── 1080p_init.m4s
    │   ├── 1080p_1.m4s
    │   └── 1080p_N.m4s
    ├── 1080p-60/                 # Профиль 1080p @ 60fps (если применимо)
    │   └── ...
    ├── 720p/                     # Профиль 720p @ 30fps
    │   └── ...
    ├── 480p/                     # Профиль 480p @ 30fps
    │   └── ...
    └── 360p/                     # Профиль 360p @ 30fps
        └── ...
```

### Именование файлов

**Инициализационные сегменты**: `{profile}_init.m4s` или `{profile}_.mp4`

**Медиа сегменты**: `{profile}_{number}.m4s`

**Аудио**: `audio_{number}.m4s` или `audio_{lang}_{number}.m4s` для множественных дорожек

Имя выходной директории всегда соответствует имени входного видео файла (без расширения).

## Производительность

- Параллельное кодирование до 3 профилей одновременно (с NVENC)
- GOP size точно соответствует длительности сегмента для быстрой упаковки
- Временные файлы в `/tmp/` с автоочисткой
- Прогресс-бары в реальном времени для каждого профиля

## Требования

- **FFmpeg**: с поддержкой h264_nvenc (опционально), aac, scale
- **MP4Box** (GPAC): для DASH упаковки
- **NVIDIA GPU**: для NVENC ускорения (опционально, fallback на CPU)
- **Bun**: runtime окружение