create-vod/docs/CLI_REFERENCE.md

# CLI Reference — Справочник команд

Полное руководство по использованию DASH Video Converter CLI.

---

## Синтаксис

```bash
create-vod <input-video> [output-dir] [options]
```

## Позиционные аргументы

| Аргумент | Описание | По умолчанию |
|----------|----------|--------------|
| `input-video` | Путь к входному видео файлу | **Обязательный** |
| `output-dir` | Директория для сохранения результата | `.` (текущая папка) |

---

## Опции

### `-r, --resolutions` — Профили разрешений

Задает список профилей для генерации. Можно указывать разрешение и FPS.

**Формат:**
- `<resolution>` — только разрешение (FPS = 30)
- `<resolution>@<fps>` — разрешение с FPS (разделитель `@`)
- `<resolution>-<fps>` — разрешение с FPS (разделитель `-`)

**Поддерживаемые разрешения:**
- `360p` (640×360)
- `480p` (854×480)
- `720p` (1280×720)
- `1080p` (1920×1080)
- `1440p` (2560×1440)
- `2160p` (3840×2160)

**Примеры:**
```bash
# Базовые разрешения (30 FPS)
create-vod video.mp4 -r 360,720,1080

# С указанием FPS
create-vod video.mp4 -r 720@60,1080@60

# Смешанный формат
create-vod video.mp4 -r 360 720@60 1080 1440@120
```

**Автоматическая коррекция FPS:**
- Если запрошенный FPS > FPS источника → используется FPS источника
- Максимальный FPS: **120** (ограничение системы)
- Система выведет предупреждение при коррекции

**По умолчанию:** Автоматический выбор всех подходящих разрешений (≤ разрешения источника) с 30 FPS.

---

### `-c, --codec` — Видео кодек

Выбор видео кодека для кодирования.

**Значения:**
- `h264` — только H.264 (максимальная совместимость)
- `av1` — только AV1 (лучшее сжатие, новые браузеры)

**Примеры:**
```bash
# Только H.264 (быстрее, больше места)
create-vod video.mp4 -c h264

# Только AV1 (медленнее, меньше места)
create-vod video.mp4 -c av1
```

**GPU ускорение:**
- H.264: `h264_nvenc` (NVIDIA), fallback → `libx264` (CPU)
- AV1: `av1_nvenc` (NVIDIA), `av1_qsv` (Intel), `av1_amf` (AMD), fallback → `libsvtav1` (CPU)

**По умолчанию:** авто (H.264 всегда, AV1 если есть аппаратный AV1)

---

### `-e, --encoder` — Видео энкодер

Выбор приоритетного видео энкодера.

**Значения:**
- `auto` — автоопределение по приоритету (NVENC → QSV → AMF → VAAPI → CPU)
- `nvenc` — NVIDIA NVENC
- `qsv` — Intel Quick Sync
- `amf` — AMD AMF
- `vaapi` — VAAPI (Linux)
- `videotoolbox` — Apple VT (macOS)
- `v4l2` — V4L2 M2M (ARM/SBC)
- `cpu` — принудительно без GPU (`libx264`/`libsvtav1`)

**Примеры:**
```bash
create-vod video.mp4 -e nvenc
create-vod video.mp4 -e qsv
create-vod video.mp4 -e cpu   # отключить GPU
```

---

### `-d, --decoder` — Видео декодер (hwaccel)

Выбор аппаратного декодера / hwaccel.

**Значения:**
- `auto` — автоопределение (NVDEC → QSV → VAAPI → CPU)
- `nvenc` — CUDA/NVDEC
- `qsv` — Intel Quick Sync
- `vaapi` — VAAPI (Linux)
- `videotoolbox` — Apple VT (macOS)
- `v4l2` — V4L2 M2M (ARM/SBC)
- `cpu` — программный декод

**Примеры:**
```bash
create-vod video.mp4 -d nvenc
create-vod video.mp4 -d cpu    # декод только на CPU
```

---

### `-f, --format` — Формат стриминга

Выбор формата адаптивного стриминга.

**Значения:**
- `dash` — только DASH (MPEG-DASH)
- `hls` — только HLS (HTTP Live Streaming)

**Примеры:**
```bash
# Только DASH
create-vod video.mp4 -f dash

# Только HLS (для Safari/iOS)
create-vod video.mp4 -f hls

# Оба формата (по умолчанию авто)
create-vod video.mp4    # формат не указывать
```

**Особенности:**

| Формат | Кодеки | Совместимость | Примечание |
|--------|--------|---------------|------------|
| DASH | H.264 + AV1 | Chrome, Firefox, Edge, Safari (с dash.js) | Стандарт индустрии |
| HLS | H.264 только | Safari, iOS, все браузеры | Требует H.264 |

**Ограничения:**
- HLS требует наличие H.264 в итоговом наборе кодеков
- AV1 не поддерживается в HLS (Safari не поддерживает AV1)

**Файловая структура:**
```
output/
└── video_name/
    ├── 720p-h264/         ← Сегменты H.264 720p
    │   ├── 720p-h264_.mp4
    │   ├── 720p-h264_1.m4s
    │   └── playlist.m3u8  ← HLS медиа плейлист
    ├── 720p-av1/          ← Сегменты AV1 720p (только для DASH)
    │   ├── 720p-av1_.mp4
    │   └── 720p-av1_1.m4s
    ├── audio/             ← Аудио сегменты
    │   ├── audio_.mp4
    │   ├── audio_1.m4s
    │   └── playlist.m3u8
    ├── manifest.mpd       ← DASH манифест (корень)
    ├── master.m3u8        ← HLS мастер плейлист (корень)
    ├── poster.jpg         ← Общие файлы
    ├── thumbnails.jpg
    └── thumbnails.vtt
```

**По умолчанию:** генерируются DASH и HLS

---

### `-p, --poster` — Тайм-код постера

Время, с которого извлечь кадр для постера.

**Формат:**
- Секунды: `5`, `10.5`
- Тайм-код: `00:00:05`, `00:01:30`

**Примеры:**
```bash
# 5 секунд от начала
create-vod video.mp4 -p 5

# 1 минута 30 секунд
create-vod video.mp4 -p 00:01:30
```

**По умолчанию:** `00:00:00` (первый кадр)

---

## Примеры использования

### Базовое использование

```bash
# Простейший запуск (оба формата, авто кодек, автопрофили)
create-vod video.mp4

# С указанием выходной директории
create-vod video.mp4 ./output
```

### Кастомные профили

```bash
# Только 720p и 1080p
create-vod video.mp4 -r 720,1080

# High FPS профили
create-vod video.mp4 -r 720@60,1080@60,1440@120

# Один профиль 4K
create-vod video.mp4 -r 2160
```

### Выбор кодека

```bash
# Быстрое кодирование (только H.264)
create-vod video.mp4 -c h264

# Лучшее сжатие (только AV1)
create-vod video.mp4 -c av1
```

### Выбор формата

```bash
# DASH для современных браузеров
create-vod video.mp4 -f dash

# HLS для Safari/iOS
create-vod video.mp4 -f hls -c h264
```

### Комбинированные примеры

```bash
# Производственная конфигурация
create-vod video.mp4 ./cdn/videos -r 360,720,1080

# High-end конфигурация (4K, high FPS)
create-vod video.mp4 -r 720@60,1080@60,1440@120,2160@60

# Быстрая конвертация для тестов
create-vod video.mp4 -r 720 -c h264 -f dash

# Mobile-first (низкие разрешения, HLS)
create-vod video.mp4 -r 360,480,720 -c h264 -f hls

# Кастомный постер
create-vod video.mp4 -r 720,1080 -p 00:02:30
```

---

## Системные требования

### Обязательные зависимости

- **FFmpeg** — кодирование видео
- **MP4Box (GPAC)** — упаковка DASH/HLS

Установка:
```bash
# Arch Linux
sudo pacman -S ffmpeg gpac

# Ubuntu/Debian
sudo apt install ffmpeg gpac

# macOS
brew install ffmpeg gpac
```

### Опциональные (для GPU ускорения)

- **NVIDIA GPU** — для H.264/AV1 кодирования через NVENC
- **Intel GPU** — для AV1 через QSV
- **AMD GPU** — для AV1 через AMF

---

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

### CPU vs GPU

| Кодек | CPU | GPU (NVENC) | Ускорение |
|-------|-----|-------------|-----------|
| H.264 | libx264 | h264_nvenc | ~10-20x |
| AV1 | libsvtav1 | av1_nvenc | ~15-30x |

### Параллельное кодирование

- **GPU**: до 3 профилей одновременно
- **CPU**: до 2 профилей одновременно

### Время конвертации (примерные данные)

Видео 4K, 10 секунд, h264 + av1 (авто), 3 профиля:

| Конфигурация | Время |
|--------------|-------|
| CPU (libx264 + libsvtav1) | ~5-10 минут |
| GPU (NVENC) | ~30-60 секунд |

---

## Рекомендации

### Для максимальной совместимости

```bash
create-vod video.mp4
```

Генерирует:
- DASH с H.264 + AV1 (Chrome, Firefox, Edge при наличии поддержки)
- HLS с H.264 (Safari, iOS)
- Все современные устройства поддерживаются; AV1 добавляется при наличии HW

### Для быстрой разработки

```bash
create-vod video.mp4 -r 720 -c h264 -f dash
```

Быстрое кодирование одного профиля.

### Для продакшена

```bash
create-vod video.mp4 -r 360,480,720,1080,1440
```

Широкий диапазон профилей для всех устройств.

### Для 4K контента

```bash
create-vod video.mp4 -r 720,1080,1440,2160
```

От HD до 4K для премиум контента.

---

## Устранение проблем

### HLS требует H.264

**Ошибка:**
```
❌ Error: HLS format requires H.264 codec
```

**Решение:**
```bash
# Используйте h264 или auto
create-vod video.mp4 -f hls -c h264
# или
create-vod video.mp4 -f hls
```

### FPS источника ниже запрошенного

**Предупреждение:**
```
⚠️  Requested 120 FPS, but source is 60 FPS. Using 60 FPS instead
```

Это нормально! Система автоматически ограничивает FPS до максимума источника.

### MP4Box не найден

**Ошибка:**
```
❌ MP4Box not found
```

**Решение:**
```bash
sudo pacman -S gpac  # Arch
sudo apt install gpac  # Ubuntu
```

---

## См. также

- [FEATURES.md](./FEATURES.md) — Возможности и технические детали
- [PUBLISHING.md](./PUBLISHING.md) — Публикация пакета в npm
- [README.md](../README.md) — Быстрый старт