adaptive-video-converter/docs/CLI_REFERENCE.md

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

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

---

## Синтаксис

```bash
avc <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)
avc video.mp4 -r 360,720,1080

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

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

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

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

---

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

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

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

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

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

# Оба кодека (максимальная совместимость)
avc video.mp4 -c dual
```

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

**По умолчанию:** `dual`

---

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

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

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

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

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

# Оба формата (максимальная совместимость)
avc video.mp4 -f both
```

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

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

**Ограничения:**
- HLS требует `--codec h264` или `--codec dual`
- 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 используют одни и те же .m4s файлы
- Экономия 50% места при `format=both`

**По умолчанию:** `both` (максимальная совместимость)

---

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

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

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

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

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

**По умолчанию:** `00:00:01` (1 секунда от начала)

---

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

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

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

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

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

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

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

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

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

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

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

# Максимальная совместимость
avc video.mp4 -c dual
```

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

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

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

# Оба формата для всех устройств
avc video.mp4 -f both -c dual
```

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

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

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

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

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

# Кастомный постер
avc 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 секунд, dual codec, 3 профиля:

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

---

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

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

```bash
avc video.mp4 -c dual -f both
```

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

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

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

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

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

```bash
avc video.mp4 -r 360,480,720,1080,1440 -c dual -f both
```

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

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

```bash
avc video.mp4 -r 720,1080,1440,2160 -c dual -f both
```

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

---

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

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

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

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

### 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) — Быстрый старт