# CLI Reference — Справочник команд Полное руководство по использованию DASH Video Converter CLI. --- ## Синтаксис ```bash create-vod [output-dir] [options] ``` ## Позиционные аргументы | Аргумент | Описание | По умолчанию | |----------|----------|--------------| | `input-video` | Путь к входному видео файлу | **Обязательный** | | `output-dir` | Директория для сохранения результата | `.` (текущая папка) | --- ## Опции ### `-r, --resolutions` — Профили разрешений Задает список профилей для генерации. Можно указывать разрешение и FPS. **Формат:** - `` — только разрешение (FPS = 30) - `@` — разрешение с 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) — Быстрый старт