dvc-cli/README.md

DASH Video Converter 🎬

Быстрая библиотека для конвертации видео в формат DASH с поддержкой аппаратного ускорения NVIDIA NVENC и генерацией превью спрайтов.

Возможности

• ⚡ Аппаратное ускорение NVENC - максимальная скорость конвертации на GPU
• 🎯 Адаптивный стриминг - автоматическое создание нескольких битрейтов
• 🖼️ Превью спрайты - генерация thumbnail спрайтов с VTT файлами
• 🔄 Параллельная обработка - одновременное кодирование нескольких профилей
• 📊 Прогресс в реальном времени - отслеживание процесса конвертации
• 🎬 Фрагменты 2 секунды - оптимальная сегментация для потокового вещания

Требования

• Bun >= 1.0.0
• FFmpeg с поддержкой DASH (libavformat)
• NVIDIA GPU (опционально, для NVENC)

Установка FFmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

# macOS
brew install ffmpeg

Установка

bun install

Быстрый старт

import { convertToDash } from '@dash-converter/core';

const result = await convertToDash({
  input: './video.mp4',
  outputDir: './output',
  segmentDuration: 2,
  useNvenc: true, // Использовать NVENC если доступен
  generateThumbnails: true,
  onProgress: (progress) => {
    console.log(`${progress.stage}: ${progress.percent}%`);
  }
});

console.log('Готово!', result.manifestPath);

API

convertToDash(options: DashConvertOptions): Promise<DashConvertResult>

Основная функция конвертации видео в DASH формат.

Опции

interface DashConvertOptions {
  // Путь к входному видео файлу (обязательно)
  input: string;
  
  // Директория для выходных файлов (обязательно)
  outputDir: string;
  
  // Длительность сегмента в секундах (по умолчанию: 2)
  segmentDuration?: number;
  
  // Профили качества видео (авто-определение если не указано)
  profiles?: VideoProfile[];
  
  // Использовать NVENC ускорение (авто-определение если не указано)
  useNvenc?: boolean;
  
  // Генерировать превью спрайты (по умолчанию: true)
  generateThumbnails?: boolean;
  
  // Настройки превью спрайтов
  thumbnailConfig?: ThumbnailConfig;
  
  // Параллельное кодирование профилей (по умолчанию: true)
  parallel?: boolean;
  
  // Коллбэк для отслеживания прогресса
  onProgress?: (progress: ConversionProgress) => void;
}

Профили видео

interface VideoProfile {
  name: string;        // Название профиля (например, "1080p")
  width: number;       // Ширина в пикселях
  height: number;      // Высота в пикселях
  videoBitrate: string; // Битрейт видео (например, "5000k")
  audioBitrate: string; // Битрейт аудио (например, "256k")
}

Профили по умолчанию:

• 1080p: 1920x1080, 5000k видео, 256k аудио
• 720p: 1280x720, 3000k видео, 256k аудио
• 480p: 854x480, 1500k видео, 256k аудио
• 360p: 640x360, 800k видео, 256k аудио

Настройки превью

interface ThumbnailConfig {
  width?: number;    // Ширина миниатюры (по умолчанию: 160)
  height?: number;   // Высота миниатюры (по умолчанию: 90)
  interval?: number; // Интервал между превью в секундах (по умолчанию: 10)
  columns?: number;  // Количество столбцов в спрайте (по умолчанию: 10)
}

Результат

interface DashConvertResult {
  manifestPath: string;        // Путь к MPD манифесту
  videoPaths: string[];        // Пути к видео сегментам
  thumbnailSpritePath?: string; // Путь к спрайту превью
  thumbnailVttPath?: string;    // Путь к VTT файлу превью
  duration: number;            // Длительность видео в секундах
  profiles: VideoProfile[];    // Использованные профили
  usedNvenc: boolean;          // Использовался ли NVENC
}

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

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

import { convertToDash } from '@dash-converter/core';

const result = await convertToDash({
  input: './my-video.mp4',
  outputDir: './dash-output'
});

С кастомными профилями

const result = await convertToDash({
  input: './my-video.mp4',
  outputDir: './dash-output',
  profiles: [
    {
      name: '4k',
      width: 3840,
      height: 2160,
      videoBitrate: '15000k',
      audioBitrate: '256k'
    },
    {
      name: '1080p',
      width: 1920,
      height: 1080,
      videoBitrate: '5000k',
      audioBitrate: '256k'
    }
  ]
});

С отслеживанием прогресса

const result = await convertToDash({
  input: './my-video.mp4',
  outputDir: './dash-output',
  onProgress: (progress) => {
    console.log(`
      Стадия: ${progress.stage}
      Прогресс: ${progress.percent.toFixed(2)}%
      Профиль: ${progress.currentProfile || 'N/A'}
    `);
  }
});

Без GPU ускорения (только CPU)

const result = await convertToDash({
  input: './my-video.mp4',
  outputDir: './dash-output',
  useNvenc: false // Принудительно использовать CPU
});

Кастомные настройки превью

const result = await convertToDash({
  input: './my-video.mp4',
  outputDir: './dash-output',
  thumbnailConfig: {
    width: 320,
    height: 180,
    interval: 5,  // Каждые 5 секунд
    columns: 5    // 5 превью в ряд
  }
});

Запуск примера

# Конвертировать видео
bun run example examples/basic.ts ./input.mp4 ./output

# Или через npm script
bun run example

Утилиты

Проверка системы

import { checkFFmpeg, checkNvenc } from '@dash-converter/core';

const hasFFmpeg = await checkFFmpeg();
const hasNvenc = await checkNvenc();

console.log('FFmpeg:', hasFFmpeg ? '✓' : '✗');
console.log('NVENC:', hasNvenc ? '✓' : '✗');

Получение метаданных видео

import { getVideoMetadata } from '@dash-converter/core';

const metadata = await getVideoMetadata('./video.mp4');
console.log(`
  Разрешение: ${metadata.width}x${metadata.height}
  Длительность: ${metadata.duration}s
  FPS: ${metadata.fps}
  Кодек: ${metadata.codec}
`);

Выбор профилей

import { selectProfiles } from '@dash-converter/core';

// Автоматический выбор профилей на основе разрешения
const profiles = selectProfiles(1920, 1080);
console.log('Доступные профили:', profiles.map(p => p.name));

Производительность

Сравнение NVENC vs CPU

Тестовое видео: 1080p, 60fps, 2 минуты

Метод	Время конвертации	Ускорение
CPU (libx264, preset medium)	~8 минут	1x
NVENC (preset p4)	~45 секунд	10.6x

Советы по оптимизации

1. Используйте NVENC - самое большое ускорение
2. Параллельное кодирование - включено по умолчанию
3. Оптимальная длина сегментов - 2-4 секунды для баланса качества/размера
4. Профили по необходимости - не генерируйте лишние разрешения

Структура выходных файлов

Библиотека автоматически создает структурированную папку с именем входного видеофайла:

output/
└── video-name/                      # Имя входного файла
    ├── manifest.mpd                 # Главный DASH манифест
    ├── thumbnails.jpg               # Спрайт превью
    ├── thumbnails.vtt               # WebVTT для превью
    ├── audio/                       # Общий аудио трек
    │   ├── audio_init.m4s           # Инициализационный сегмент
    │   ├── audio_1.m4s              # Аудио сегмент #1
    │   ├── audio_2.m4s              # Аудио сегмент #2
    │   └── ...
    ├── 1080p/                       # Папка для профиля 1080p
    │   ├── 1080p_init.m4s           # Инициализационный сегмент
    │   ├── 1080p_1.m4s              # Видео сегмент #1
    │   ├── 1080p_2.m4s              # Видео сегмент #2
    │   └── ...
    ├── 720p/                        # Папка для профиля 720p
    │   ├── 720p_init.m4s
    │   ├── 720p_1.m4s
    │   └── ...
    ├── 480p/                        # Папка для профиля 480p
    │   └── ...
    └── 360p/                        # Папка для профиля 360p
        └── ...

Лицензия

MIT

Автор

Создано с ❤️ на Bun + TypeScript