412 lines
11 KiB
Markdown
412 lines
11 KiB
Markdown
# 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) — Быстрый старт
|