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