vod/create-vod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0813bea1d4bb503cdf0eb519f62c00592014ace4
create-vod/docs/CLI_REFERENCE.md

11 KiB
Raw Blame History

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

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

Синтаксис

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)

Примеры:

# Базовые разрешения (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 (лучшее сжатие, новые браузеры)

Примеры:

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

Примеры:

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 — программный декод

Примеры:

create-vod video.mp4 -d nvenc
create-vod video.mp4 -d cpu    # декод только на CPU

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

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

Значения:

  • dash — только DASH (MPEG-DASH)
  • hls — только HLS (HTTP Live Streaming)

Примеры:

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

Примеры:

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

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

По умолчанию: 00:00:00 (первый кадр)

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

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

# Простейший запуск (оба формата, авто кодек, автопрофили)
create-vod video.mp4

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

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

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

Выбор кодека

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

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

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

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

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

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

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

Установка:

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

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

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

create-vod video.mp4

Генерирует:

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

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

create-vod video.mp4 -r 720 -c h264 -f dash

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

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

create-vod video.mp4 -r 360,480,720,1080,1440

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

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

create-vod video.mp4 -r 720,1080,1440,2160

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

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

HLS требует H.264

Ошибка:

❌ Error: HLS format requires H.264 codec

Решение:

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

Решение:

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

См. также

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