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

```bash
# Ubuntu/Debian
sudo apt install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

# macOS
brew install ffmpeg
```

## Установка

```bash
bun install
```

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

```typescript
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 формат.

#### Опции

```typescript
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;
}
```

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

```typescript
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 аудио

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

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

#### Результат

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

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

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

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

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

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

```typescript
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'
    }
  ]
});
```

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

```typescript
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)

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

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

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

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

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

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

## Утилиты

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

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

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

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

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

```typescript
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}
`);
```

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

```typescript
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