sync
This commit is contained in:
213
docs/FEATURES.md
Normal file
213
docs/FEATURES.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Возможности DASH Video Converter
|
||||
|
||||
## Архитектура
|
||||
|
||||
Конвертация выполняется в два этапа для обеспечения стабильности и максимальной производительности:
|
||||
|
||||
**Этап 1: Кодирование** - тяжелая работа по перекодированию видео во все профили качества с использованием FFmpeg и NVENC.
|
||||
|
||||
**Этап 2: Упаковка DASH** - быстрая упаковка готовых MP4 файлов в DASH формат через MP4Box с генерацией манифеста.
|
||||
|
||||
Преимущества подхода:
|
||||
- Стабильность: MP4Box специализируется на DASH, FFmpeg - на кодирование
|
||||
- Параллелизм: все профили кодируются одновременно на GPU
|
||||
- Надежность: разделение ответственности между инструментами
|
||||
|
||||
## Этап 1: Оптимизация и кодирование
|
||||
|
||||
### Стандартные профили разрешений
|
||||
|
||||
Автоматически создаются профили с частотой 30 FPS:
|
||||
- 360p (640x360) - 800 kbps
|
||||
- 480p (854x480) - 1200 kbps
|
||||
- 720p (1280x720) - 2800 kbps
|
||||
- 1080p (1920x1080) - 5000 kbps
|
||||
|
||||
### Опциональные профили высокого разрешения
|
||||
|
||||
Создаются только если исходное видео имеет соответствующее или более высокое разрешение:
|
||||
- 2K (2560x1440) - если исходное >= 1440p
|
||||
- 4K (3840x2160) - если исходное >= 2160p
|
||||
|
||||
Система автоматически определяет разрешение исходного видео и создает только применимые профили без upscaling.
|
||||
|
||||
### Высокочастотные профили
|
||||
|
||||
Система автоматически определяет частоту кадров исходного видео и создает дополнительные высокочастотные профили только если это поддерживается оригиналом:
|
||||
|
||||
- **Оригинал >= 45 FPS**: создаются профили @ 60 FPS для всех разрешений
|
||||
- **Оригинал >= 75 FPS**: создаются профили @ 90 FPS для всех разрешений
|
||||
- **Оригинал >= 95 FPS**: создаются профили @ 120 FPS для всех разрешений
|
||||
|
||||
Стандартные 30 FPS профили создаются всегда.
|
||||
|
||||
Пример: если исходное видео 60 FPS, будут созданы:
|
||||
- 360p @ 30fps, 360p @ 60fps
|
||||
- 480p @ 30fps, 480p @ 60fps
|
||||
- 720p @ 30fps, 720p @ 60fps
|
||||
- 1080p @ 30fps, 1080p @ 60fps
|
||||
|
||||
Интерполяция кадров не применяется - создаются только те частоты, которые нативно поддерживаются исходным материалом.
|
||||
|
||||
### Технические особенности
|
||||
|
||||
- **NVENC GPU ускорение**: аппаратное кодирование на видеокарте NVIDIA
|
||||
- **GOP size выравнивание**: keyframe каждые N кадров для точной сегментации (N = FPS × segment_duration)
|
||||
- **VBR режим**: переменный битрейт для оптимального качества
|
||||
- **Умное кодирование аудио**: автоматический выбор оптимального битрейта без upscaling
|
||||
- Целевой максимум: 256 kbps AAC стерео
|
||||
- Фактический битрейт: `min(source_bitrate, 256 kbps)`
|
||||
- Округление до стандартных значений: 64k, 96k, 128k, 192k, 256k
|
||||
- Примеры: исходник 64 kbps → выход 64 kbps | исходник 320 kbps → выход 256 kbps
|
||||
|
||||
## Этап 2: Создание DASH
|
||||
|
||||
### Упаковка через MP4Box
|
||||
|
||||
- Создание фрагментированных MP4 сегментов длительностью 2 секунды
|
||||
- Генерация единого MPD манифеста для всех профилей
|
||||
- Выравнивание сегментов по Random Access Points (RAP)
|
||||
|
||||
### Организация файловой структуры
|
||||
|
||||
После упаковки файлы автоматически организуются в подпапки:
|
||||
- Видео сегменты: `{resolution}/`
|
||||
- Аудио сегменты: `audio/`
|
||||
- Манифест: корень директории
|
||||
|
||||
Пути в MPD манифесте обновляются для соответствия структуре подпапок.
|
||||
|
||||
## Множественные аудио дорожки
|
||||
|
||||
### Поддержка озвучек и языков
|
||||
|
||||
Система поддерживает несколько аудио дорожек с различными источниками:
|
||||
|
||||
**Извлечение из видео**:
|
||||
- Автоматическое извлечение всех аудио дорожек из входного файла
|
||||
- Выбор конкретных дорожек по индексу
|
||||
|
||||
**Внешние файлы**:
|
||||
- Добавление аудио из отдельных файлов (MP3, AAC, M4A)
|
||||
- Синхронизация с видео
|
||||
|
||||
### Метаданные аудио дорожек
|
||||
|
||||
Каждая дорожка содержит метаданные для правильного отображения в плеере:
|
||||
|
||||
- **language**: код языка (ru, en, ja)
|
||||
- **label**: название озвучки ("Кубик в кубе", "LostFilm", "Original")
|
||||
- **role**: тип озвучки
|
||||
- `main` - основная
|
||||
- `dub` - дубляж
|
||||
- `commentary` - комментарии
|
||||
|
||||
Пример структуры в MPD:
|
||||
```xml
|
||||
<AdaptationSet lang="ru" label="Кубик в кубе">
|
||||
<Role schemeIdUri="urn:mpeg:dash:role:2011" value="dub"/>
|
||||
<Representation id="audio_kubik" .../>
|
||||
</AdaptationSet>
|
||||
```
|
||||
|
||||
## Генерация постера
|
||||
|
||||
### Автоматический режим
|
||||
|
||||
По умолчанию постер создается из первого кадра видео (00:00:00).
|
||||
|
||||
### Указание таймкода
|
||||
|
||||
Возможно указание конкретного времени для извлечения постера:
|
||||
|
||||
Формат:
|
||||
- `MM:SS` - минуты:секунды (например, `06:32`)
|
||||
- `HH:MM:SS` - часы:минуты:секунды (например, `01:23:45`)
|
||||
|
||||
Команда:
|
||||
```bash
|
||||
--poster-time 06:32
|
||||
```
|
||||
|
||||
Постер сохраняется в формате JPEG с оптимизированным качеством.
|
||||
|
||||
## Превью спрайты
|
||||
|
||||
### Thumbnail спрайты
|
||||
|
||||
Автоматическая генерация спрайта с миниатюрами для навигации по видео:
|
||||
|
||||
- **Интервал**: 1 секунда (по умолчанию)
|
||||
- **Размер миниатюры**: 160x90 пикселей
|
||||
- **Сетка**: 10 колонок, динамическое количество строк
|
||||
- **Формат**: JPEG sprite
|
||||
|
||||
### WebVTT файл
|
||||
|
||||
Генерируется VTT файл с координатами каждой миниатюры:
|
||||
|
||||
```vtt
|
||||
WEBVTT
|
||||
|
||||
00:00:00.000 --> 00:00:01.000
|
||||
thumbnails.jpg#xywh=0,0,160,90
|
||||
|
||||
00:00:01.000 --> 00:00:02.000
|
||||
thumbnails.jpg#xywh=160,0,160,90
|
||||
```
|
||||
|
||||
Плееры используют VTT для отображения превью при наведении на timeline.
|
||||
|
||||
## Выходная структура файлов
|
||||
|
||||
### Организация директорий
|
||||
|
||||
```
|
||||
output/
|
||||
└── video-name/
|
||||
├── manifest.mpd # Главный DASH манифест
|
||||
├── poster.jpg # Постер видео
|
||||
├── thumbnails.jpg # Спрайт превью
|
||||
├── thumbnails.vtt # WebVTT для превью
|
||||
├── audio/ # Аудио дорожки
|
||||
│ ├── audio_init.m4s # Инициализационный сегмент
|
||||
│ ├── audio_1.m4s # Сегмент #1
|
||||
│ └── audio_N.m4s # Сегмент #N
|
||||
├── 1080p/ # Профиль 1080p @ 30fps
|
||||
│ ├── 1080p_init.m4s
|
||||
│ ├── 1080p_1.m4s
|
||||
│ └── 1080p_N.m4s
|
||||
├── 1080p-60/ # Профиль 1080p @ 60fps (если применимо)
|
||||
│ └── ...
|
||||
├── 720p/ # Профиль 720p @ 30fps
|
||||
│ └── ...
|
||||
├── 480p/ # Профиль 480p @ 30fps
|
||||
│ └── ...
|
||||
└── 360p/ # Профиль 360p @ 30fps
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Именование файлов
|
||||
|
||||
**Инициализационные сегменты**: `{profile}_init.m4s` или `{profile}_.mp4`
|
||||
|
||||
**Медиа сегменты**: `{profile}_{number}.m4s`
|
||||
|
||||
**Аудио**: `audio_{number}.m4s` или `audio_{lang}_{number}.m4s` для множественных дорожек
|
||||
|
||||
Имя выходной директории всегда соответствует имени входного видео файла (без расширения).
|
||||
|
||||
## Производительность
|
||||
|
||||
- Параллельное кодирование до 3 профилей одновременно (с NVENC)
|
||||
- GOP size точно соответствует длительности сегмента для быстрой упаковки
|
||||
- Временные файлы в `/tmp/` с автоочисткой
|
||||
- Прогресс-бары в реальном времени для каждого профиля
|
||||
|
||||
## Требования
|
||||
|
||||
- **FFmpeg**: с поддержкой h264_nvenc (опционально), aac, scale
|
||||
- **MP4Box** (GPAC): для DASH упаковки
|
||||
- **NVIDIA GPU**: для NVENC ускорения (опционально, fallback на CPU)
|
||||
- **Bun**: runtime окружение
|
||||
|
||||
136
docs/PUBLISHING.md
Normal file
136
docs/PUBLISHING.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# 📦 Инструкция по публикации в NPM
|
||||
|
||||
## Подготовка к публикации
|
||||
|
||||
### Шаг 1: Авторизация в NPM
|
||||
|
||||
```bash
|
||||
npm login
|
||||
```
|
||||
|
||||
Введите credentials для аккаунта с доступом к организации `@grom13`.
|
||||
|
||||
### Шаг 2: Сборка проекта
|
||||
|
||||
```bash
|
||||
cd /home/gromov/projects/my/dvc-cli
|
||||
npm run build
|
||||
```
|
||||
|
||||
Эта команда выполнит:
|
||||
- Сборку библиотеки в `dist/`
|
||||
- Генерацию TypeScript деклараций (`.d.ts`)
|
||||
- Сборку CLI бинарника в `bin/cli.js`
|
||||
|
||||
### Шаг 3: Проверка перед публикацией (опционально)
|
||||
|
||||
```bash
|
||||
# Посмотреть какие файлы будут опубликованы
|
||||
npm pack --dry-run
|
||||
|
||||
# Или создать тестовый архив для проверки
|
||||
npm pack
|
||||
# Это создаст файл grom13-dvc-cli-0.1.0.tgz
|
||||
```
|
||||
|
||||
## Публикация
|
||||
|
||||
### Шаг 4: Публикация в NPM
|
||||
|
||||
```bash
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
⚠️ **Важно:** Флаг `--access public` обязателен для scoped пакетов (`@grom13/...`), иначе NPM попытается опубликовать как приватный пакет (требует платную подписку).
|
||||
|
||||
### Шаг 5: Проверка публикации
|
||||
|
||||
```bash
|
||||
# Проверить что пакет доступен
|
||||
npm view @grom13/dvc-cli
|
||||
|
||||
# Протестировать установку через npx
|
||||
npx @grom13/dvc-cli --help
|
||||
|
||||
# Или установить глобально и протестировать
|
||||
npm install -g @grom13/dvc-cli
|
||||
dvc --help
|
||||
```
|
||||
|
||||
## Обновление версии
|
||||
|
||||
Для будущих релизов используйте команды версионирования:
|
||||
|
||||
```bash
|
||||
# Patch версия (0.1.0 → 0.1.1) - исправления багов
|
||||
npm version patch
|
||||
|
||||
# Minor версия (0.1.0 → 0.2.0) - новые функции
|
||||
npm version minor
|
||||
|
||||
# Major версия (0.1.0 → 1.0.0) - breaking changes
|
||||
npm version major
|
||||
```
|
||||
|
||||
После обновления версии:
|
||||
|
||||
```bash
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
## Откат публикации (если нужно)
|
||||
|
||||
```bash
|
||||
# Удалить конкретную версию (в течение 72 часов)
|
||||
npm unpublish @grom13/dvc-cli@0.1.0
|
||||
|
||||
# Удалить весь пакет (использовать осторожно!)
|
||||
npm unpublish @grom13/dvc-cli --force
|
||||
```
|
||||
|
||||
⚠️ **Внимание:** После unpublish нельзя повторно опубликовать ту же версию. Нужно увеличить версию.
|
||||
|
||||
## Использование после публикации
|
||||
|
||||
Пакет будет доступен для использования:
|
||||
|
||||
```bash
|
||||
# Через npx (без установки)
|
||||
npx @grom13/dvc-cli video.mp4 ./output
|
||||
|
||||
# Глобальная установка
|
||||
npm install -g @grom13/dvc-cli
|
||||
dvc video.mp4 ./output
|
||||
|
||||
# Локальная установка в проект
|
||||
npm install @grom13/dvc-cli
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Ошибка: "You must sign up for private packages"
|
||||
|
||||
Решение: Добавьте флаг `--access public` при публикации.
|
||||
|
||||
### Ошибка: "You do not have permission to publish"
|
||||
|
||||
Решение: Убедитесь что вы авторизованы (`npm whoami`) и имеете доступ к организации `@grom13`.
|
||||
|
||||
### Ошибка при сборке
|
||||
|
||||
Решение: Убедитесь что установлены все зависимости:
|
||||
```bash
|
||||
npm install
|
||||
# или
|
||||
bun install
|
||||
```
|
||||
|
||||
## Checklist перед публикацией
|
||||
|
||||
- [ ] Обновлена версия в `package.json`
|
||||
- [ ] Обновлен `README.md` с актуальной информацией
|
||||
- [ ] Проект успешно собирается (`npm run build`)
|
||||
- [ ] Протестирован CLI локально
|
||||
- [ ] Авторизованы в NPM (`npm whoami`)
|
||||
- [ ] Проверены файлы для публикации (`npm pack --dry-run`)
|
||||
|
||||
Reference in New Issue
Block a user