# CLI Reference — Справочник команд Полное руководство по использованию DASH Video Converter CLI. --- ## Синтаксис ```bash dvc-cli [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) dvc-cli video.mp4 -r 360,720,1080 # С указанием FPS dvc-cli video.mp4 -r 720@60,1080@60 # Смешанный формат dvc-cli 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 (быстрее, больше места) dvc-cli video.mp4 -c h264 # Только AV1 (медленнее, меньше места) dvc-cli video.mp4 -c av1 # Оба кодека (максимальная совместимость) dvc-cli 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 dvc-cli video.mp4 -f dash # Только HLS (для Safari/iOS) dvc-cli video.mp4 -f hls # Оба формата (максимальная совместимость) dvc-cli 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 секунд от начала dvc-cli video.mp4 -p 5 # 1 минута 30 секунд dvc-cli video.mp4 -p 00:01:30 ``` **По умолчанию:** `00:00:01` (1 секунда от начала) --- ## Примеры использования ### Базовое использование ```bash # Простейший запуск (оба формата, dual codec, автопрофили) dvc-cli video.mp4 # С указанием выходной директории dvc-cli video.mp4 ./output ``` ### Кастомные профили ```bash # Только 720p и 1080p dvc-cli video.mp4 -r 720,1080 # High FPS профили dvc-cli video.mp4 -r 720@60,1080@60,1440@120 # Один профиль 4K dvc-cli video.mp4 -r 2160 ``` ### Выбор кодека ```bash # Быстрое кодирование (только H.264) dvc-cli video.mp4 -c h264 # Лучшее сжатие (только AV1) dvc-cli video.mp4 -c av1 # Максимальная совместимость dvc-cli video.mp4 -c dual ``` ### Выбор формата ```bash # DASH для современных браузеров dvc-cli video.mp4 -f dash # HLS для Safari/iOS dvc-cli video.mp4 -f hls -c h264 # Оба формата для всех устройств dvc-cli video.mp4 -f both -c dual ``` ### Комбинированные примеры ```bash # Производственная конфигурация dvc-cli video.mp4 ./cdn/videos -r 360,720,1080 -c dual -f both # High-end конфигурация (4K, high FPS) dvc-cli video.mp4 -r 720@60,1080@60,1440@120,2160@60 -c dual -f both # Быстрая конвертация для тестов dvc-cli video.mp4 -r 720 -c h264 -f dash # Mobile-first (низкие разрешения, HLS) dvc-cli video.mp4 -r 360,480,720 -c h264 -f hls # Кастомный постер dvc-cli 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 dvc-cli video.mp4 -c dual -f both ``` Генерирует: - DASH с H.264 + AV1 (Chrome, Firefox, Edge) - HLS с H.264 (Safari, iOS) - Все современные устройства поддерживаются ### Для быстрой разработки ```bash dvc-cli video.mp4 -r 720 -c h264 -f dash ``` Быстрое кодирование одного профиля. ### Для продакшена ```bash dvc-cli video.mp4 -r 360,480,720,1080,1440 -c dual -f both ``` Широкий диапазон профилей для всех устройств. ### Для 4K контента ```bash dvc-cli 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 dvc-cli video.mp4 -f hls -c h264 # или dvc-cli 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) — Быстрый старт