gromov/dvc-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
dvc-cli/docs/CLI_REFERENCE.md

10 KiB
Raw Permalink Blame History

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

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

Синтаксис

dvc-cli <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)

Примеры:

# Базовые разрешения (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 — оба кодека (рекомендуется)

Примеры:

# Только 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 — оба формата

Примеры:

# Только 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

Примеры:

# 5 секунд от начала
dvc-cli video.mp4 -p 5

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

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

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

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

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

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

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

# Только 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

Выбор кодека

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

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

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

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

# 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

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

# Производственная конфигурация
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

Установка:

# 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 секунд

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

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

dvc-cli video.mp4 -c dual -f both

Генерирует:

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

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

dvc-cli video.mp4 -r 720 -c h264 -f dash

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

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

dvc-cli video.mp4 -r 360,480,720,1080,1440 -c dual -f both

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

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

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

Решение:

# Используйте 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

Решение:

sudo pacman -S gpac  # Arch
sudo apt install gpac  # Ubuntu

См. также

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