add vitepress
This commit is contained in:
5
.gitignore
vendored
5
.gitignore
vendored
@@ -24,3 +24,8 @@ test-output/
|
||||
|
||||
/data/
|
||||
bin/
|
||||
|
||||
# Игнорировать VitePress
|
||||
docs-dist/
|
||||
docs/.vitepress/cache
|
||||
docs/.vitepress/dist
|
||||
88
docs/.vitepress/config.mts
Normal file
88
docs/.vitepress/config.mts
Normal file
@@ -0,0 +1,88 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
// https://vitepress.dev/reference/site-config
|
||||
export default defineConfig({
|
||||
title: "Adaptive Video Converter",
|
||||
description: "Конвертер видео в адаптивные форматы DASH и HLS с GPU-ускорением",
|
||||
base: '/',
|
||||
outDir: '../docs-dist',
|
||||
lang: 'ru-RU',
|
||||
|
||||
themeConfig: {
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
|
||||
nav: [
|
||||
{ text: 'Главная', link: '/' },
|
||||
{ text: 'CLI', link: '/cli/' },
|
||||
{ text: 'API Библиотеки', link: '/api/' }
|
||||
],
|
||||
|
||||
sidebar: {
|
||||
// CLI sidebar
|
||||
'/cli/': [
|
||||
{
|
||||
text: 'CLI Документация',
|
||||
items: [
|
||||
{ text: 'Обзор', link: '/cli/' },
|
||||
{ text: 'Установка', link: '/cli/installation' },
|
||||
{ text: 'Использование', link: '/cli/usage' },
|
||||
{ text: 'Опции и ключи', link: '/cli/options' },
|
||||
{ text: 'Примеры', link: '/cli/examples' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
// API sidebar
|
||||
'/api/': [
|
||||
{
|
||||
text: 'API Библиотеки',
|
||||
items: [
|
||||
{ text: 'Обзор', link: '/api/' },
|
||||
{ text: 'convertToDash()', link: '/api/convert' },
|
||||
{ text: 'Утилиты', link: '/api/utilities' },
|
||||
{ text: 'Профили', link: '/api/profiles' },
|
||||
{ text: 'TypeScript типы', link: '/api/types' }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://gromlab.ru/gromov/adaptive-video-converter' }
|
||||
],
|
||||
|
||||
footer: {
|
||||
message: 'Выпущено под лицензией MIT',
|
||||
copyright: 'Copyright © 2024 grom13'
|
||||
},
|
||||
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
locales: {
|
||||
root: {
|
||||
translations: {
|
||||
button: {
|
||||
buttonText: 'Поиск',
|
||||
buttonAriaLabel: 'Поиск'
|
||||
},
|
||||
modal: {
|
||||
noResultsText: 'Нет результатов для',
|
||||
resetButtonTitle: 'Сбросить поиск',
|
||||
footer: {
|
||||
selectText: 'выбрать',
|
||||
navigateText: 'навигация'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
outline: {
|
||||
level: [2, 3],
|
||||
label: 'На этой странице'
|
||||
}
|
||||
}
|
||||
})
|
||||
367
docs/api/convert.md
Normal file
367
docs/api/convert.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# convertToDash()
|
||||
|
||||
Главная функция для конвертации видео в адаптивные форматы DASH и HLS.
|
||||
|
||||
## Сигнатура
|
||||
|
||||
```typescript
|
||||
async function convertToDash(
|
||||
options: DashConvertOptions
|
||||
): Promise<DashConvertResult>
|
||||
```
|
||||
|
||||
## Параметры
|
||||
|
||||
### `DashConvertOptions`
|
||||
|
||||
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|
||||
|----------|-----|--------------|--------------|----------|
|
||||
| `input` | `string` | ✅ | - | Путь к входному видео файлу |
|
||||
| `outputDir` | `string` | ✅ | - | Директория для выходных файлов |
|
||||
| `segmentDuration` | `number` | ❌ | `2` | Длительность сегмента в секундах |
|
||||
| `profiles` | `VideoProfile[]` | ❌ | автовыбор | Массив профилей качества |
|
||||
| `customProfiles` | `string[]` | ❌ | автовыбор | Профили как строки (например, `['720', '1080@60']`) |
|
||||
| `codec` | `CodecType` | ❌ | `'dual'` | Кодек: `'h264'`, `'av1'` или `'dual'` |
|
||||
| `format` | `StreamingFormat` | ❌ | `'both'` | Формат: `'dash'`, `'hls'` или `'both'` |
|
||||
| `useNvenc` | `boolean` | ❌ | auto | Использовать NVENC (автоопределение) |
|
||||
| `quality` | `QualitySettings` | ❌ | auto | Настройки качества (CQ/CRF) |
|
||||
| `generateThumbnails` | `boolean` | ❌ | `true` | Генерировать превью-спрайт |
|
||||
| `thumbnailConfig` | `ThumbnailConfig` | ❌ | см. ниже | Конфигурация превью |
|
||||
| `generatePoster` | `boolean` | ❌ | `true` | Генерировать постер |
|
||||
| `posterTimecode` | `string` | ❌ | `'00:00:01'` | Таймкод постера |
|
||||
| `parallel` | `boolean` | ❌ | `true` | Параллельное кодирование |
|
||||
| `onProgress` | `function` | ❌ | - | Колбэк для прогресса |
|
||||
|
||||
## Возвращаемое значение
|
||||
|
||||
### `DashConvertResult`
|
||||
|
||||
```typescript
|
||||
interface DashConvertResult {
|
||||
manifestPath: string; // Путь к DASH манифесту
|
||||
hlsManifestPath?: string; // Путь к HLS манифесту (если format='hls' или 'both')
|
||||
segments: string[]; // Пути к сегментам
|
||||
thumbnailPath?: string; // Путь к спрайту превью
|
||||
posterPath?: string; // Путь к постеру
|
||||
}
|
||||
```
|
||||
|
||||
## Примеры
|
||||
|
||||
### Базовое использование
|
||||
|
||||
```typescript
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
|
||||
console.log('DASH манифест:', result.manifestPath);
|
||||
console.log('HLS манифест:', result.hlsManifestPath);
|
||||
```
|
||||
|
||||
### С кастомными профилями
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
customProfiles: ['360', '720', '1080']
|
||||
});
|
||||
```
|
||||
|
||||
### С высоким FPS
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './gameplay.mp4',
|
||||
outputDir: './output',
|
||||
customProfiles: ['720@60', '1080@60', '1440@120']
|
||||
});
|
||||
```
|
||||
|
||||
### Выбор кодека
|
||||
|
||||
```typescript
|
||||
// Только H.264
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
codec: 'h264'
|
||||
});
|
||||
|
||||
// Только AV1
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
codec: 'av1'
|
||||
});
|
||||
|
||||
// Оба кодека (по умолчанию)
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
codec: 'dual'
|
||||
});
|
||||
```
|
||||
|
||||
### Выбор формата
|
||||
|
||||
```typescript
|
||||
// Только DASH
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
format: 'dash'
|
||||
});
|
||||
|
||||
// Только HLS
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
format: 'hls',
|
||||
codec: 'h264' // HLS лучше работает с H.264
|
||||
});
|
||||
|
||||
// Оба формата (по умолчанию)
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
format: 'both'
|
||||
});
|
||||
```
|
||||
|
||||
### С отслеживанием прогресса
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
onProgress: (progress) => {
|
||||
console.log(`Прогресс: ${progress.percent}%`);
|
||||
console.log(`Этап: ${progress.stage}`);
|
||||
console.log(`Профиль: ${progress.currentProfile}`);
|
||||
console.log(`ETA: ${progress.eta}s`);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### С настройками качества
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
quality: {
|
||||
h264: {
|
||||
cq: 28, // CQ для GPU
|
||||
crf: 23 // CRF для CPU (фоллбек)
|
||||
},
|
||||
av1: {
|
||||
cq: 35,
|
||||
crf: 35
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### С кастомной конфигурацией превью
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
thumbnailConfig: {
|
||||
width: 320, // Ширина превью
|
||||
height: 180, // Высота превью
|
||||
interval: 2, // Интервал в секундах
|
||||
columns: 10, // Колонок в спрайте
|
||||
rows: 10 // Строк в спрайте
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### С кастомным постером
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
posterTimecode: '00:02:30' // Постер с 2:30
|
||||
});
|
||||
```
|
||||
|
||||
### Без превью и постера
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
generateThumbnails: false,
|
||||
generatePoster: false
|
||||
});
|
||||
```
|
||||
|
||||
### С предварительной проверкой системы
|
||||
|
||||
```typescript
|
||||
import {
|
||||
convertToDash,
|
||||
checkFFmpeg,
|
||||
checkMP4Box,
|
||||
checkNvenc
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Проверки перед конвертацией
|
||||
try {
|
||||
await checkFFmpeg();
|
||||
await checkMP4Box();
|
||||
const hasNvenc = await checkNvenc();
|
||||
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
useNvenc: hasNvenc // Явное указание
|
||||
});
|
||||
|
||||
console.log('Успешно!', result.manifestPath);
|
||||
} catch (error) {
|
||||
console.error('Ошибка:', error.message);
|
||||
}
|
||||
```
|
||||
|
||||
### Последовательное кодирование (без параллелизма)
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
parallel: false // Медленнее, но меньше нагрузка
|
||||
});
|
||||
```
|
||||
|
||||
### С кастомными профилями (объектами)
|
||||
|
||||
```typescript
|
||||
import type { VideoProfile } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const customProfiles: VideoProfile[] = [
|
||||
{
|
||||
name: '720p',
|
||||
width: 1280,
|
||||
height: 720,
|
||||
videoBitrate: '2500k',
|
||||
audioBitrate: '128k',
|
||||
fps: 30
|
||||
},
|
||||
{
|
||||
name: '1080p',
|
||||
width: 1920,
|
||||
height: 1080,
|
||||
videoBitrate: '5000k',
|
||||
audioBitrate: '192k',
|
||||
fps: 30
|
||||
}
|
||||
];
|
||||
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
profiles: customProfiles
|
||||
});
|
||||
```
|
||||
|
||||
## Обработка ошибок
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
|
||||
console.log('✅ Успешно');
|
||||
} catch (error) {
|
||||
if (error.message.includes('FFmpeg not found')) {
|
||||
console.error('FFmpeg не установлен');
|
||||
} else if (error.message.includes('MP4Box not found')) {
|
||||
console.error('MP4Box не установлен');
|
||||
} else if (error.message.includes('File not found')) {
|
||||
console.error('Входной файл не найден');
|
||||
} else {
|
||||
console.error('Ошибка конвертации:', error.message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Поведение по умолчанию
|
||||
|
||||
Если не указаны параметры:
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
```
|
||||
|
||||
Эквивалентно:
|
||||
|
||||
```typescript
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
segmentDuration: 2,
|
||||
codec: 'dual',
|
||||
format: 'both',
|
||||
useNvenc: true, // если доступен
|
||||
generateThumbnails: true,
|
||||
generatePoster: true,
|
||||
posterTimecode: '00:00:01',
|
||||
parallel: true,
|
||||
customProfiles: автовыбор на основе исходного видео
|
||||
});
|
||||
```
|
||||
|
||||
## Автовыбор профилей
|
||||
|
||||
Если `profiles` и `customProfiles` не указаны:
|
||||
|
||||
| Исходное разрешение | Выбранные профили |
|
||||
|---------------------|-------------------|
|
||||
| ≤ 720p | 360p, 480p, 720p |
|
||||
| 1080p | 360p, 720p, 1080p |
|
||||
| 1440p | 720p, 1080p, 1440p |
|
||||
| 2160p (4K) | 1080p, 1440p, 2160p |
|
||||
|
||||
FPS профилей соответствует исходному видео (максимум 120fps).
|
||||
|
||||
## Структура вывода
|
||||
|
||||
После вызова `convertToDash()` создается следующая структура:
|
||||
|
||||
```
|
||||
output/
|
||||
└── video/
|
||||
├── manifest.mpd # DASH манифест
|
||||
├── master.m3u8 # HLS мастер-плейлист (если format='hls' или 'both')
|
||||
├── 720p-h264/ # Сегменты профиля
|
||||
│ ├── 720p-h264_init.mp4
|
||||
│ ├── 720p-h264_1.m4s
|
||||
│ └── ...
|
||||
├── 720p-av1/
|
||||
├── 1080p-h264/
|
||||
├── 1080p-av1/
|
||||
├── thumbnails.jpg # Спрайт превью
|
||||
├── thumbnails.vtt # WebVTT метки
|
||||
├── poster.jpg # Постер
|
||||
└── conversion.log # Лог конвертации
|
||||
```
|
||||
|
||||
## См. также
|
||||
|
||||
- [Утилиты](/api/utilities) — Вспомогательные функции
|
||||
- [Профили](/api/profiles) — Работа с профилями
|
||||
- [Типы](/api/types) — Все TypeScript типы
|
||||
236
docs/api/index.md
Normal file
236
docs/api/index.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# API Библиотеки
|
||||
|
||||
Adaptive Video Converter можно использовать программно в ваших Node.js/TypeScript проектах.
|
||||
|
||||
## Установка
|
||||
|
||||
```bash
|
||||
npm install @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
```typescript
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const result = await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
|
||||
console.log('Готово!', result.manifestPath);
|
||||
```
|
||||
|
||||
## Основные экспорты
|
||||
|
||||
### Функции
|
||||
|
||||
- [`convertToDash()`](/api/convert) — Главная функция конвертации
|
||||
- [Утилиты](/api/utilities) — Вспомогательные функции (checkFFmpeg, getVideoMetadata и др.)
|
||||
- [Профили](/api/profiles) — Работа с профилями качества
|
||||
|
||||
### TypeScript типы
|
||||
|
||||
- [Типы](/api/types) — Все доступные типы и интерфейсы
|
||||
|
||||
## Структура API
|
||||
|
||||
```typescript
|
||||
// Основная функция
|
||||
export { convertToDash } from './core/converter';
|
||||
|
||||
// Утилиты
|
||||
export {
|
||||
checkFFmpeg,
|
||||
checkMP4Box,
|
||||
checkNvenc,
|
||||
checkAV1Support,
|
||||
getVideoMetadata,
|
||||
selectAudioBitrate
|
||||
} from './utils';
|
||||
|
||||
// Профили
|
||||
export {
|
||||
DEFAULT_PROFILES,
|
||||
selectProfiles
|
||||
} from './config/profiles';
|
||||
|
||||
// Типы
|
||||
export type {
|
||||
DashConvertOptions,
|
||||
DashConvertResult,
|
||||
VideoProfile,
|
||||
ThumbnailConfig,
|
||||
ConversionProgress,
|
||||
VideoMetadata,
|
||||
VideoOptimizations,
|
||||
CodecType
|
||||
} from './types';
|
||||
```
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Базовая конвертация
|
||||
|
||||
```typescript
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
|
||||
await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
```
|
||||
|
||||
### С кастомными профилями
|
||||
|
||||
```typescript
|
||||
await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output',
|
||||
customProfiles: ['720', '1080', '1440']
|
||||
});
|
||||
```
|
||||
|
||||
### С обработкой прогресса
|
||||
|
||||
```typescript
|
||||
await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output',
|
||||
onProgress: (progress) => {
|
||||
console.log(`${progress.percent}% - ${progress.stage}`);
|
||||
console.log(`ETA: ${progress.eta}s`);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Выбор кодека и формата
|
||||
|
||||
```typescript
|
||||
await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output',
|
||||
codecType: 'dual', // 'h264' | 'av1' | 'dual'
|
||||
format: 'both' // 'dash' | 'hls' | 'both'
|
||||
});
|
||||
```
|
||||
|
||||
### С проверкой системы
|
||||
|
||||
```typescript
|
||||
import {
|
||||
convertToDash,
|
||||
checkFFmpeg,
|
||||
checkNvenc
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Проверка перед конвертацией
|
||||
try {
|
||||
await checkFFmpeg();
|
||||
const hasNvenc = await checkNvenc();
|
||||
|
||||
console.log('NVENC:', hasNvenc ? 'доступен' : 'недоступен');
|
||||
|
||||
await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('Ошибка:', error.message);
|
||||
}
|
||||
```
|
||||
|
||||
### С анализом исходного видео
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
convertToDash
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Получить метаданные
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
|
||||
console.log('Разрешение:', `${metadata.width}×${metadata.height}`);
|
||||
console.log('FPS:', metadata.fps);
|
||||
console.log('Длительность:', metadata.duration, 'сек');
|
||||
|
||||
// Конвертация с учетом метаданных
|
||||
await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output',
|
||||
customProfiles: metadata.height >= 1080
|
||||
? ['720', '1080', '1440']
|
||||
: ['360', '720']
|
||||
});
|
||||
```
|
||||
|
||||
## Обработка ошибок
|
||||
|
||||
```typescript
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
|
||||
try {
|
||||
const result = await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output'
|
||||
});
|
||||
|
||||
console.log('✅ Успешно:', result.manifestPath);
|
||||
} catch (error) {
|
||||
if (error.message.includes('FFmpeg not found')) {
|
||||
console.error('❌ FFmpeg не установлен');
|
||||
} else if (error.message.includes('MP4Box not found')) {
|
||||
console.error('❌ MP4Box не установлен');
|
||||
} else {
|
||||
console.error('❌ Ошибка:', error.message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Интеграция в Express
|
||||
|
||||
```typescript
|
||||
import express from 'express';
|
||||
import multer from 'multer';
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
import { promises as fs } from 'fs';
|
||||
|
||||
const app = express();
|
||||
const upload = multer({ dest: 'uploads/' });
|
||||
|
||||
app.post('/convert', upload.single('video'), async (req, res) => {
|
||||
try {
|
||||
const result = await convertToDash({
|
||||
inputPath: req.file.path,
|
||||
outputDir: './public/videos',
|
||||
onProgress: (progress) => {
|
||||
// Можно отправлять через WebSocket
|
||||
console.log(`${progress.percent}%`);
|
||||
}
|
||||
});
|
||||
|
||||
// Удалить временный файл
|
||||
await fs.unlink(req.file.path);
|
||||
|
||||
res.json({
|
||||
success: true,
|
||||
manifestPath: result.manifestPath
|
||||
});
|
||||
} catch (error) {
|
||||
res.status(500).json({
|
||||
success: false,
|
||||
error: error.message
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
app.listen(3000);
|
||||
```
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
- [convertToDash()](/api/convert) — Подробная документация основной функции
|
||||
- [Утилиты](/api/utilities) — Вспомогательные функции
|
||||
- [Профили](/api/profiles) — Работа с профилями качества
|
||||
- [Типы](/api/types) — TypeScript типы и интерфейсы
|
||||
316
docs/api/profiles.md
Normal file
316
docs/api/profiles.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# Профили качества
|
||||
|
||||
Работа с профилями качества видео (разрешения, битрейты, FPS).
|
||||
|
||||
## DEFAULT_PROFILES
|
||||
|
||||
Массив дефолтных профилей качества.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
const DEFAULT_PROFILES: VideoProfile[]
|
||||
```
|
||||
|
||||
**Содержимое:**
|
||||
|
||||
| Профиль | Разрешение | Видео битрейт | Аудио битрейт | FPS |
|
||||
|---------|------------|---------------|---------------|-----|
|
||||
| 360p | 640×360 | 800k | 96k | 30 |
|
||||
| 480p | 854×480 | 1400k | 128k | 30 |
|
||||
| 720p | 1280×720 | 2500k | 128k | 30 |
|
||||
| 1080p | 1920×1080 | 5000k | 192k | 30 |
|
||||
| 1440p | 2560×1440 | 8000k | 192k | 30 |
|
||||
| 2160p (4K) | 3840×2160 | 16000k | 192k | 30 |
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import { DEFAULT_PROFILES } from '@grom13/adaptive-video-converter';
|
||||
|
||||
console.log('Доступные профили:', DEFAULT_PROFILES.length);
|
||||
|
||||
DEFAULT_PROFILES.forEach(profile => {
|
||||
console.log(`${profile.name}: ${profile.width}×${profile.height} @ ${profile.videoBitrate}`);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## selectProfiles()
|
||||
|
||||
Автоматический выбор профилей на основе метаданных исходного видео.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
function selectProfiles(
|
||||
metadata: VideoMetadata,
|
||||
customProfiles?: string[]
|
||||
): VideoProfile[]
|
||||
```
|
||||
|
||||
**Параметры:**
|
||||
- `metadata` — Метаданные исходного видео (из `getVideoMetadata()`)
|
||||
- `customProfiles` — Опциональные кастомные профили как строки
|
||||
|
||||
**Возвращает:** Массив выбранных профилей
|
||||
|
||||
**Логика автовыбора:**
|
||||
|
||||
| Исходное разрешение | Выбранные профили |
|
||||
|---------------------|-------------------|
|
||||
| ≤ 720p | 360p, 480p, 720p |
|
||||
| 1080p | 360p, 720p, 1080p |
|
||||
| 1440p | 720p, 1080p, 1440p |
|
||||
| 2160p (4K) | 1080p, 1440p, 2160p |
|
||||
|
||||
**Особенности:**
|
||||
- FPS профилей соответствует исходному видео (до 120fps max)
|
||||
- Битрейты рассчитываются автоматически по формуле BPP (Bits Per Pixel)
|
||||
- Создаются варианты с высоким FPS если исходное видео поддерживает
|
||||
|
||||
**Примеры:**
|
||||
|
||||
### Автовыбор профилей
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
selectProfiles
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
const profiles = selectProfiles(metadata);
|
||||
|
||||
console.log('Выбранные профили:');
|
||||
profiles.forEach(p => {
|
||||
console.log(`- ${p.name}: ${p.width}×${p.height} @ ${p.fps}fps, ${p.videoBitrate}`);
|
||||
});
|
||||
```
|
||||
|
||||
### С кастомными профилями
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
selectProfiles
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
|
||||
// Парсинг кастомных профилей
|
||||
const profiles = selectProfiles(metadata, ['720', '1080', '1440']);
|
||||
|
||||
// Профили будут созданы на основе исходного FPS
|
||||
```
|
||||
|
||||
### С высоким FPS
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
selectProfiles
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
const metadata = await getVideoMetadata('./gameplay.mp4');
|
||||
|
||||
// Если исходное видео 60fps, создаст профили:
|
||||
// 720p@60, 1080p@60, 1440p@60
|
||||
const profiles = selectProfiles(metadata, ['720@60', '1080@60', '1440@60']);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VideoProfile интерфейс
|
||||
|
||||
```typescript
|
||||
interface VideoProfile {
|
||||
name: string; // Название (например, "1080p", "720p@60")
|
||||
width: number; // Ширина в пикселях
|
||||
height: number; // Высота в пикселях
|
||||
videoBitrate: string; // Видео битрейт (например, "5000k")
|
||||
audioBitrate: string; // Аудио битрейт (например, "128k")
|
||||
fps: number; // Кадров в секунду
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Создание кастомных профилей
|
||||
|
||||
### Вручную
|
||||
|
||||
```typescript
|
||||
import type { VideoProfile } from '@grom13/adaptive-video-converter';
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const myProfiles: VideoProfile[] = [
|
||||
{
|
||||
name: '720p-high',
|
||||
width: 1280,
|
||||
height: 720,
|
||||
videoBitrate: '3500k', // Выше стандартного
|
||||
audioBitrate: '192k',
|
||||
fps: 30
|
||||
},
|
||||
{
|
||||
name: '1080p-ultra',
|
||||
width: 1920,
|
||||
height: 1080,
|
||||
videoBitrate: '8000k', // Выше стандартного
|
||||
audioBitrate: '256k',
|
||||
fps: 60
|
||||
}
|
||||
];
|
||||
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
profiles: myProfiles
|
||||
});
|
||||
```
|
||||
|
||||
### С расчетом битрейта
|
||||
|
||||
```typescript
|
||||
import type { VideoProfile } from '@grom13/adaptive-video-converter';
|
||||
|
||||
// BPP (Bits Per Pixel) формула
|
||||
function calculateBitrate(
|
||||
width: number,
|
||||
height: number,
|
||||
fps: number,
|
||||
bpp: number = 0.1 // По умолчанию 0.1
|
||||
): string {
|
||||
const bitrate = Math.round(width * height * fps * bpp / 1000);
|
||||
return `${bitrate}k`;
|
||||
}
|
||||
|
||||
const profile: VideoProfile = {
|
||||
name: '1080p60',
|
||||
width: 1920,
|
||||
height: 1080,
|
||||
videoBitrate: calculateBitrate(1920, 1080, 60, 0.1), // ~12000k
|
||||
audioBitrate: '192k',
|
||||
fps: 60
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Форматы строк для customProfiles
|
||||
|
||||
### Базовый формат
|
||||
|
||||
```
|
||||
<resolution>[@<fps>]
|
||||
```
|
||||
|
||||
**Примеры:**
|
||||
- `'360'` → 360p @ 30fps
|
||||
- `'720'` → 720p @ 30fps
|
||||
- `'1080'` → 1080p @ 30fps
|
||||
|
||||
### С указанием FPS
|
||||
|
||||
```
|
||||
<resolution>@<fps>
|
||||
```
|
||||
|
||||
**Примеры:**
|
||||
- `'720@60'` → 720p @ 60fps
|
||||
- `'1080@60'` → 1080p @ 60fps
|
||||
- `'1440@120'` → 1440p @ 120fps
|
||||
|
||||
### Комбинации
|
||||
|
||||
```typescript
|
||||
const profiles = ['360', '720@30', '1080@60', '1440@120'];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Рекомендации по битрейтам
|
||||
|
||||
### Стандартное качество (BPP ~0.1)
|
||||
|
||||
| Профиль | Битрейт |
|
||||
|---------|---------|
|
||||
| 360p @ 30fps | 800k |
|
||||
| 480p @ 30fps | 1400k |
|
||||
| 720p @ 30fps | 2500k |
|
||||
| 1080p @ 30fps | 5000k |
|
||||
| 1440p @ 30fps | 8000k |
|
||||
| 2160p @ 30fps | 16000k |
|
||||
|
||||
### Высокое качество (BPP ~0.15)
|
||||
|
||||
| Профиль | Битрейт |
|
||||
|---------|---------|
|
||||
| 720p @ 30fps | 3800k |
|
||||
| 1080p @ 30fps | 7500k |
|
||||
| 1440p @ 30fps | 12000k |
|
||||
| 2160p @ 30fps | 24000k |
|
||||
|
||||
### Высокий FPS
|
||||
|
||||
Для 60fps — умножить на 2
|
||||
Для 120fps — умножить на 4
|
||||
|
||||
**Примеры:**
|
||||
- 1080p @ 60fps: 5000k × 2 = 10000k
|
||||
- 1440p @ 120fps: 8000k × 4 = 32000k
|
||||
|
||||
---
|
||||
|
||||
## Валидация профилей
|
||||
|
||||
При использовании `selectProfiles()` или `convertToDash()` автоматически происходит:
|
||||
|
||||
1. **Проверка разрешения** — не превышает исходное
|
||||
2. **Проверка FPS** — не превышает исходный
|
||||
3. **Ограничение FPS** — максимум 120fps
|
||||
4. **Расчет битрейтов** — автоматически если не указаны
|
||||
|
||||
**Пример:**
|
||||
|
||||
```typescript
|
||||
// Если исходное видео 1080p @ 30fps
|
||||
const profiles = selectProfiles(metadata, ['720@60', '1080', '1440']);
|
||||
|
||||
// Результат:
|
||||
// - 720p @ 30fps (FPS понижен до исходного)
|
||||
// - 1080p @ 30fps
|
||||
// - 1440p → ПРОПУЩЕН (разрешение выше исходного)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Интеграция с convertToDash()
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
selectProfiles,
|
||||
convertToDash
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// 1. Получить метаданные
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
|
||||
// 2. Выбрать профили
|
||||
const profiles = selectProfiles(metadata, ['720', '1080', '1440']);
|
||||
|
||||
// 3. Конвертация
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
profiles // Использовать выбранные профили
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## См. также
|
||||
|
||||
- [convertToDash()](/api/convert) — Главная функция
|
||||
- [Утилиты](/api/utilities) — getVideoMetadata()
|
||||
- [Типы](/api/types) — VideoProfile тип
|
||||
473
docs/api/types.md
Normal file
473
docs/api/types.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# TypeScript типы
|
||||
|
||||
Все доступные TypeScript типы и интерфейсы для работы с библиотекой.
|
||||
|
||||
## Основные типы
|
||||
|
||||
### `CodecType`
|
||||
|
||||
Тип видео кодека для кодирования.
|
||||
|
||||
```typescript
|
||||
type CodecType = 'av1' | 'h264' | 'dual';
|
||||
```
|
||||
|
||||
**Значения:**
|
||||
- `'av1'` — Только AV1
|
||||
- `'h264'` — Только H.264
|
||||
- `'dual'` — Оба кодека (H.264 + AV1)
|
||||
|
||||
---
|
||||
|
||||
### `StreamingFormat`
|
||||
|
||||
Тип формата стриминга.
|
||||
|
||||
```typescript
|
||||
type StreamingFormat = 'dash' | 'hls' | 'both';
|
||||
```
|
||||
|
||||
**Значения:**
|
||||
- `'dash'` — Только DASH
|
||||
- `'hls'` — Только HLS
|
||||
- `'both'` — Оба формата
|
||||
|
||||
---
|
||||
|
||||
## Интерфейсы опций
|
||||
|
||||
### `DashConvertOptions`
|
||||
|
||||
Конфигурация для `convertToDash()`.
|
||||
|
||||
```typescript
|
||||
interface DashConvertOptions {
|
||||
/** Входной видео файл */
|
||||
input: string;
|
||||
|
||||
/** Выходная директория */
|
||||
outputDir: string;
|
||||
|
||||
/** Длительность сегмента в секундах (по умолчанию: 2) */
|
||||
segmentDuration?: number;
|
||||
|
||||
/** Профили качества */
|
||||
profiles?: VideoProfile[];
|
||||
|
||||
/** Кастомные профили как строки (например, ['720', '1080@60']) */
|
||||
customProfiles?: string[];
|
||||
|
||||
/** Кодек: 'av1', 'h264' или 'dual' (по умолчанию: 'dual') */
|
||||
codec?: CodecType;
|
||||
|
||||
/** Формат: 'dash', 'hls' или 'both' (по умолчанию: 'both') */
|
||||
format?: StreamingFormat;
|
||||
|
||||
/** Использовать NVENC (авто-определение если undefined) */
|
||||
useNvenc?: boolean;
|
||||
|
||||
/** Настройки качества (CQ/CRF значения) */
|
||||
quality?: QualitySettings;
|
||||
|
||||
/** Генерировать превью-спрайт (по умолчанию: true) */
|
||||
generateThumbnails?: boolean;
|
||||
|
||||
/** Конфигурация превью */
|
||||
thumbnailConfig?: ThumbnailConfig;
|
||||
|
||||
/** Генерировать постер (по умолчанию: true) */
|
||||
generatePoster?: boolean;
|
||||
|
||||
/** Таймкод постера в формате HH:MM:SS или секунды (по умолчанию: '00:00:01') */
|
||||
posterTimecode?: string;
|
||||
|
||||
/** Параллельное кодирование (по умолчанию: true) */
|
||||
parallel?: boolean;
|
||||
|
||||
/** Колбэк для прогресса */
|
||||
onProgress?: (progress: ConversionProgress) => void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `DashConvertResult`
|
||||
|
||||
Результат выполнения `convertToDash()`.
|
||||
|
||||
```typescript
|
||||
interface DashConvertResult {
|
||||
/** Путь к DASH манифесту (manifest.mpd) */
|
||||
manifestPath: string;
|
||||
|
||||
/** Путь к HLS мастер-плейлисту (master.m3u8), если format='hls' или 'both' */
|
||||
hlsManifestPath?: string;
|
||||
|
||||
/** Пути к сегментам */
|
||||
segments: string[];
|
||||
|
||||
/** Путь к спрайту превью */
|
||||
thumbnailPath?: string;
|
||||
|
||||
/** Путь к постеру */
|
||||
posterPath?: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `VideoProfile`
|
||||
|
||||
Профиль качества видео.
|
||||
|
||||
```typescript
|
||||
interface VideoProfile {
|
||||
/** Название профиля (например, "1080p", "720p@60") */
|
||||
name: string;
|
||||
|
||||
/** Ширина в пикселях */
|
||||
width: number;
|
||||
|
||||
/** Высота в пикселях */
|
||||
height: number;
|
||||
|
||||
/** Видео битрейт (например, "5000k") */
|
||||
videoBitrate: string;
|
||||
|
||||
/** Аудио битрейт (например, "128k") */
|
||||
audioBitrate: string;
|
||||
|
||||
/** Кадров в секунду */
|
||||
fps: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `ThumbnailConfig`
|
||||
|
||||
Конфигурация генерации превью-спрайтов.
|
||||
|
||||
```typescript
|
||||
interface ThumbnailConfig {
|
||||
/** Ширина превью в пикселях (по умолчанию: 160) */
|
||||
width?: number;
|
||||
|
||||
/** Высота превью в пикселях (по умолчанию: 90) */
|
||||
height?: number;
|
||||
|
||||
/** Интервал между превью в секундах (по умолчанию: 1) */
|
||||
interval?: number;
|
||||
|
||||
/** Количество колонок в спрайте (по умолчанию: 10) */
|
||||
columns?: number;
|
||||
|
||||
/** Количество строк в спрайте (по умолчанию: 10) */
|
||||
rows?: number;
|
||||
}
|
||||
```
|
||||
|
||||
**По умолчанию:**
|
||||
```typescript
|
||||
{
|
||||
width: 160,
|
||||
height: 90,
|
||||
interval: 1,
|
||||
columns: 10,
|
||||
rows: 10
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `ConversionProgress`
|
||||
|
||||
Информация о прогрессе конвертации.
|
||||
|
||||
```typescript
|
||||
interface ConversionProgress {
|
||||
/** Процент выполнения (0-100) */
|
||||
percent: number;
|
||||
|
||||
/** Текущий этап (например, "encoding", "packaging") */
|
||||
stage: string;
|
||||
|
||||
/** Текущий профиль (например, "1080p-h264") */
|
||||
currentProfile?: string;
|
||||
|
||||
/** Оценка времени до завершения в секундах */
|
||||
eta?: number;
|
||||
|
||||
/** Скорость кодирования (например, "2.5x") */
|
||||
speed?: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `VideoMetadata`
|
||||
|
||||
Метаданные видео файла.
|
||||
|
||||
```typescript
|
||||
interface VideoMetadata {
|
||||
/** Ширина в пикселях */
|
||||
width: number;
|
||||
|
||||
/** Высота в пикселях */
|
||||
height: number;
|
||||
|
||||
/** Кадров в секунду */
|
||||
fps: number;
|
||||
|
||||
/** Длительность в секундах */
|
||||
duration: number;
|
||||
|
||||
/** Видео битрейт в кбит/с */
|
||||
videoBitrate: number;
|
||||
|
||||
/** Аудио битрейт в кбит/с */
|
||||
audioBitrate: number;
|
||||
|
||||
/** Видео кодек (например, "h264", "vp9") */
|
||||
codec: string;
|
||||
|
||||
/** Аудио кодек (например, "aac", "opus") */
|
||||
audioCodec: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `QualitySettings`
|
||||
|
||||
Настройки качества кодирования.
|
||||
|
||||
```typescript
|
||||
interface QualitySettings {
|
||||
/** Настройки для H.264 */
|
||||
h264?: CodecQualitySettings;
|
||||
|
||||
/** Настройки для AV1 */
|
||||
av1?: CodecQualitySettings;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `CodecQualitySettings`
|
||||
|
||||
Настройки качества для одного кодека.
|
||||
|
||||
```typescript
|
||||
interface CodecQualitySettings {
|
||||
/** CQ (Constant Quality) для GPU кодеров (0-51, меньше = лучше) */
|
||||
cq?: number;
|
||||
|
||||
/** CRF (Constant Rate Factor) для CPU кодеров
|
||||
* - 0-51 для H.264
|
||||
* - 0-63 для AV1
|
||||
* Меньше = лучше качество
|
||||
*/
|
||||
crf?: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `AV1Support`
|
||||
|
||||
Информация о доступных AV1 кодерах.
|
||||
|
||||
```typescript
|
||||
interface AV1Support {
|
||||
/** NVIDIA NVENC AV1 */
|
||||
nvenc: boolean;
|
||||
|
||||
/** Intel Quick Sync Video AV1 */
|
||||
qsv: boolean;
|
||||
|
||||
/** AMD AMF AV1 */
|
||||
amf: boolean;
|
||||
|
||||
/** libsvtav1 (CPU) */
|
||||
software: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Примеры использования типов
|
||||
|
||||
### С полной типизацией
|
||||
|
||||
```typescript
|
||||
import {
|
||||
convertToDash,
|
||||
type DashConvertOptions,
|
||||
type DashConvertResult,
|
||||
type VideoProfile,
|
||||
type ConversionProgress
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Кастомные профили
|
||||
const profiles: VideoProfile[] = [
|
||||
{
|
||||
name: '720p',
|
||||
width: 1280,
|
||||
height: 720,
|
||||
videoBitrate: '2500k',
|
||||
audioBitrate: '128k',
|
||||
fps: 30
|
||||
},
|
||||
{
|
||||
name: '1080p',
|
||||
width: 1920,
|
||||
height: 1080,
|
||||
videoBitrate: '5000k',
|
||||
audioBitrate: '192k',
|
||||
fps: 30
|
||||
}
|
||||
];
|
||||
|
||||
// Опции с типизацией
|
||||
const options: DashConvertOptions = {
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
profiles,
|
||||
codec: 'dual',
|
||||
format: 'both',
|
||||
onProgress: (progress: ConversionProgress) => {
|
||||
console.log(`${progress.percent}% - ${progress.stage}`);
|
||||
}
|
||||
};
|
||||
|
||||
// Результат с типизацией
|
||||
const result: DashConvertResult = await convertToDash(options);
|
||||
|
||||
console.log('DASH:', result.manifestPath);
|
||||
console.log('HLS:', result.hlsManifestPath);
|
||||
```
|
||||
|
||||
### С partial типами
|
||||
|
||||
```typescript
|
||||
import type { DashConvertOptions } from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Функция-помощник с дефолтными значениями
|
||||
function createOptions(
|
||||
input: string,
|
||||
overrides?: Partial<DashConvertOptions>
|
||||
): DashConvertOptions {
|
||||
return {
|
||||
input,
|
||||
outputDir: './output',
|
||||
codec: 'dual',
|
||||
format: 'both',
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
// Использование
|
||||
const options = createOptions('./video.mp4', {
|
||||
customProfiles: ['720', '1080'],
|
||||
generatePoster: false
|
||||
});
|
||||
```
|
||||
|
||||
### С дискриминирующими типами
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
CodecType,
|
||||
StreamingFormat
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Функция с проверкой типов
|
||||
function getEncoderName(codec: CodecType): string {
|
||||
switch (codec) {
|
||||
case 'h264':
|
||||
return 'h264_nvenc';
|
||||
case 'av1':
|
||||
return 'av1_nvenc';
|
||||
case 'dual':
|
||||
return 'both';
|
||||
default:
|
||||
// TypeScript гарантирует что это невозможно
|
||||
const _exhaustive: never = codec;
|
||||
throw new Error(`Unknown codec: ${_exhaustive}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Функция с проверкой формата
|
||||
function getManifestExtension(format: StreamingFormat): string {
|
||||
switch (format) {
|
||||
case 'dash':
|
||||
return '.mpd';
|
||||
case 'hls':
|
||||
return '.m3u8';
|
||||
case 'both':
|
||||
return '.mpd and .m3u8';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### С generic типами
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
DashConvertOptions,
|
||||
DashConvertResult
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Generic функция для обработки результата
|
||||
async function processConversion<T>(
|
||||
options: DashConvertOptions,
|
||||
transformer: (result: DashConvertResult) => T
|
||||
): Promise<T> {
|
||||
const result = await convertToDash(options);
|
||||
return transformer(result);
|
||||
}
|
||||
|
||||
// Использование
|
||||
const urls = await processConversion(
|
||||
{ input: './video.mp4', outputDir: './output' },
|
||||
(result) => ({
|
||||
dashUrl: `/videos/${result.manifestPath}`,
|
||||
hlsUrl: `/videos/${result.hlsManifestPath}`
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
### Type guards
|
||||
|
||||
```typescript
|
||||
import type { DashConvertResult } from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Type guard для проверки HLS
|
||||
function hasHLS(result: DashConvertResult): result is DashConvertResult & {
|
||||
hlsManifestPath: string;
|
||||
} {
|
||||
return result.hlsManifestPath !== undefined;
|
||||
}
|
||||
|
||||
// Использование
|
||||
const result = await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
format: 'both'
|
||||
});
|
||||
|
||||
if (hasHLS(result)) {
|
||||
// TypeScript знает что hlsManifestPath существует
|
||||
console.log('HLS:', result.hlsManifestPath);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## См. также
|
||||
|
||||
- [convertToDash()](/api/convert) — Использование типов в основной функции
|
||||
- [Утилиты](/api/utilities) — Типы для утилит
|
||||
- [Профили](/api/profiles) — VideoProfile тип
|
||||
341
docs/api/utilities.md
Normal file
341
docs/api/utilities.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# Утилиты
|
||||
|
||||
Вспомогательные функции для работы с системой и метаданными видео.
|
||||
|
||||
## Проверка системы
|
||||
|
||||
### `checkFFmpeg()`
|
||||
|
||||
Проверяет наличие FFmpeg в системе.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
async function checkFFmpeg(): Promise<void>
|
||||
```
|
||||
|
||||
**Возвращает:** `Promise<void>` — Успешно если FFmpeg найден
|
||||
|
||||
**Выбрасывает:** `Error` если FFmpeg не найден
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import { checkFFmpeg } from '@grom13/adaptive-video-converter';
|
||||
|
||||
try {
|
||||
await checkFFmpeg();
|
||||
console.log('✅ FFmpeg установлен');
|
||||
} catch (error) {
|
||||
console.error('❌ FFmpeg не найден');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `checkMP4Box()`
|
||||
|
||||
Проверяет наличие MP4Box (gpac) в системе.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
async function checkMP4Box(): Promise<void>
|
||||
```
|
||||
|
||||
**Возвращает:** `Promise<void>`
|
||||
|
||||
**Выбрасывает:** `Error` если MP4Box не найден
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import { checkMP4Box } from '@grom13/adaptive-video-converter';
|
||||
|
||||
try {
|
||||
await checkMP4Box();
|
||||
console.log('✅ MP4Box установлен');
|
||||
} catch (error) {
|
||||
console.error('❌ MP4Box не найден');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `checkNvenc()`
|
||||
|
||||
Проверяет доступность NVIDIA NVENC для H.264.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
async function checkNvenc(): Promise<boolean>
|
||||
```
|
||||
|
||||
**Возвращает:** `Promise<boolean>` — `true` если NVENC доступен
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import { checkNvenc } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const hasNvenc = await checkNvenc();
|
||||
|
||||
if (hasNvenc) {
|
||||
console.log('✅ NVENC доступен - будет использовано GPU-ускорение');
|
||||
} else {
|
||||
console.log('⚠️ NVENC недоступен - будет использован CPU');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `checkAV1Support()`
|
||||
|
||||
Проверяет доступность AV1 кодеров (GPU и CPU).
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
interface AV1Support {
|
||||
nvenc: boolean; // NVIDIA NVENC AV1
|
||||
qsv: boolean; // Intel Quick Sync Video
|
||||
amf: boolean; // AMD AMF
|
||||
software: boolean; // libsvtav1 (CPU)
|
||||
}
|
||||
|
||||
async function checkAV1Support(): Promise<AV1Support>
|
||||
```
|
||||
|
||||
**Возвращает:** Объект с информацией о доступных AV1 кодерах
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import { checkAV1Support } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const av1Support = await checkAV1Support();
|
||||
|
||||
console.log('AV1 NVENC:', av1Support.nvenc);
|
||||
console.log('AV1 QSV:', av1Support.qsv);
|
||||
console.log('AV1 AMF:', av1Support.amf);
|
||||
console.log('AV1 Software:', av1Support.software);
|
||||
|
||||
if (av1Support.nvenc) {
|
||||
console.log('✅ Будет использован AV1 NVENC (GPU)');
|
||||
} else if (av1Support.software) {
|
||||
console.log('⚠️ Будет использован libsvtav1 (CPU)');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Работа с метаданными
|
||||
|
||||
### `getVideoMetadata()`
|
||||
|
||||
Извлекает метаданные видео файла через ffprobe.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
interface VideoMetadata {
|
||||
width: number; // Ширина в пикселях
|
||||
height: number; // Высота в пикселях
|
||||
fps: number; // Кадров в секунду
|
||||
duration: number; // Длительность в секундах
|
||||
videoBitrate: number; // Видео битрейт в кбит/с
|
||||
audioBitrate: number; // Аудио битрейт в кбит/с
|
||||
codec: string; // Кодек (например, "h264")
|
||||
audioCodec: string; // Аудио кодек
|
||||
}
|
||||
|
||||
async function getVideoMetadata(
|
||||
filePath: string
|
||||
): Promise<VideoMetadata>
|
||||
```
|
||||
|
||||
**Параметры:**
|
||||
- `filePath` — Путь к видео файлу
|
||||
|
||||
**Возвращает:** Объект с метаданными видео
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import { getVideoMetadata } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
|
||||
console.log(`Разрешение: ${metadata.width}×${metadata.height}`);
|
||||
console.log(`FPS: ${metadata.fps}`);
|
||||
console.log(`Длительность: ${metadata.duration}с`);
|
||||
console.log(`Видео битрейт: ${metadata.videoBitrate}кбит/с`);
|
||||
console.log(`Аудио битрейт: ${metadata.audioBitrate}кбит/с`);
|
||||
console.log(`Кодек: ${metadata.codec}`);
|
||||
```
|
||||
|
||||
**Использование с convertToDash:**
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
convertToDash
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
// Анализ перед конвертацией
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
|
||||
// Выбор профилей на основе исходного разрешения
|
||||
const profiles = metadata.height >= 1080
|
||||
? ['720', '1080', '1440']
|
||||
: ['360', '720'];
|
||||
|
||||
await convertToDash({
|
||||
input: './video.mp4',
|
||||
outputDir: './output',
|
||||
customProfiles: profiles
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `selectAudioBitrate()`
|
||||
|
||||
Выбирает оптимальный аудио битрейт на основе исходного.
|
||||
|
||||
**Сигнатура:**
|
||||
```typescript
|
||||
function selectAudioBitrate(
|
||||
sourceAudioBitrate: number
|
||||
): number
|
||||
```
|
||||
|
||||
**Параметры:**
|
||||
- `sourceAudioBitrate` — Исходный аудио битрейт в кбит/с
|
||||
|
||||
**Возвращает:** Оптимальный аудио битрейт в кбит/с
|
||||
|
||||
**Логика:**
|
||||
- Если исходный ≥ 192 → 192
|
||||
- Если исходный ≥ 128 → 128
|
||||
- Иначе → 96
|
||||
|
||||
**Пример:**
|
||||
```typescript
|
||||
import {
|
||||
getVideoMetadata,
|
||||
selectAudioBitrate
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
const metadata = await getVideoMetadata('./video.mp4');
|
||||
const audioBitrate = selectAudioBitrate(metadata.audioBitrate);
|
||||
|
||||
console.log(`Исходный: ${metadata.audioBitrate}кбит/с`);
|
||||
console.log(`Выбранный: ${audioBitrate}кбит/с`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Комплексная проверка системы
|
||||
|
||||
```typescript
|
||||
import {
|
||||
checkFFmpeg,
|
||||
checkMP4Box,
|
||||
checkNvenc,
|
||||
checkAV1Support
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
async function checkSystem() {
|
||||
console.log('🔍 Проверка системы...\n');
|
||||
|
||||
// FFmpeg
|
||||
try {
|
||||
await checkFFmpeg();
|
||||
console.log('✅ FFmpeg найден');
|
||||
} catch (error) {
|
||||
console.error('❌ FFmpeg не найден');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// MP4Box
|
||||
try {
|
||||
await checkMP4Box();
|
||||
console.log('✅ MP4Box найден');
|
||||
} catch (error) {
|
||||
console.error('❌ MP4Box не найден');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// NVENC
|
||||
const hasNvenc = await checkNvenc();
|
||||
if (hasNvenc) {
|
||||
console.log('✅ NVENC H.264 доступен');
|
||||
} else {
|
||||
console.log('⚠️ NVENC недоступен, будет использован CPU');
|
||||
}
|
||||
|
||||
// AV1
|
||||
const av1 = await checkAV1Support();
|
||||
if (av1.nvenc) {
|
||||
console.log('✅ NVENC AV1 доступен');
|
||||
} else if (av1.qsv) {
|
||||
console.log('✅ Quick Sync AV1 доступен');
|
||||
} else if (av1.amf) {
|
||||
console.log('✅ AMF AV1 доступен');
|
||||
} else if (av1.software) {
|
||||
console.log('⚠️ Только CPU AV1 (libsvtav1)');
|
||||
} else {
|
||||
console.log('⚠️ AV1 недоступен');
|
||||
}
|
||||
|
||||
console.log('\n✅ Система готова к работе');
|
||||
}
|
||||
|
||||
await checkSystem();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Интеграция с Express
|
||||
|
||||
```typescript
|
||||
import express from 'express';
|
||||
import {
|
||||
checkFFmpeg,
|
||||
checkMP4Box,
|
||||
checkNvenc,
|
||||
getVideoMetadata,
|
||||
convertToDash
|
||||
} from '@grom13/adaptive-video-converter';
|
||||
|
||||
const app = express();
|
||||
|
||||
// Проверка при старте сервера
|
||||
async function startup() {
|
||||
try {
|
||||
await checkFFmpeg();
|
||||
await checkMP4Box();
|
||||
const hasNvenc = await checkNvenc();
|
||||
|
||||
console.log('Server ready. NVENC:', hasNvenc);
|
||||
|
||||
app.listen(3000, () => {
|
||||
console.log('Listening on port 3000');
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('Startup error:', error.message);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
// Эндпоинт для получения метаданных
|
||||
app.get('/video/metadata', async (req, res) => {
|
||||
try {
|
||||
const metadata = await getVideoMetadata(req.query.path);
|
||||
res.json(metadata);
|
||||
} catch (error) {
|
||||
res.status(500).json({ error: error.message });
|
||||
}
|
||||
});
|
||||
|
||||
startup();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## См. также
|
||||
|
||||
- [convertToDash()](/api/convert) — Главная функция конвертации
|
||||
- [Профили](/api/profiles) — Работа с профилями
|
||||
- [Типы](/api/types) — TypeScript типы
|
||||
442
docs/cli/examples.md
Normal file
442
docs/cli/examples.md
Normal file
@@ -0,0 +1,442 @@
|
||||
# Примеры
|
||||
|
||||
Практические примеры для различных сценариев использования.
|
||||
|
||||
## Базовые сценарии
|
||||
|
||||
### Быстрая конвертация с настройками по умолчанию
|
||||
|
||||
```bash
|
||||
avc video.mp4
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- Папка `video/` в текущей директории
|
||||
- DASH + HLS манифесты
|
||||
- H.264 + AV1 кодеки
|
||||
- Автоматические профили качества
|
||||
- Постер с 1-й секунды
|
||||
- Thumbnail спрайты
|
||||
|
||||
---
|
||||
|
||||
### Указание выходной директории
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./public/videos
|
||||
```
|
||||
|
||||
**Структура:**
|
||||
```
|
||||
public/
|
||||
└── videos/
|
||||
└── video/
|
||||
├── manifest.mpd
|
||||
├── master.m3u8
|
||||
├── 720p-h264/
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Выбор разрешений
|
||||
|
||||
### Стандартные веб-разрешения
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 720,1080
|
||||
```
|
||||
|
||||
**Для кого:** Большинство веб-сайтов
|
||||
|
||||
**Профили:** 720p, 1080p на 30fps
|
||||
|
||||
---
|
||||
|
||||
### Полный спектр качества
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 360,480,720,1080,1440,2160
|
||||
```
|
||||
|
||||
**Для кого:** Стриминговые платформы типа YouTube/Netflix
|
||||
|
||||
**Покрытие:** От мобильных до 4K мониторов
|
||||
|
||||
---
|
||||
|
||||
### Высокий FPS для игр
|
||||
|
||||
```bash
|
||||
avc gameplay.mp4 -r 720@60,1080@60,1440@120
|
||||
```
|
||||
|
||||
**Для кого:** Игровой контент, стримы
|
||||
|
||||
**Особенность:** Плавное воспроизведение 60/120 FPS
|
||||
|
||||
---
|
||||
|
||||
### Только мобильные разрешения
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 360,480,720
|
||||
```
|
||||
|
||||
**Для кого:** Мобильные приложения
|
||||
|
||||
**Преимущество:** Экономия трафика
|
||||
|
||||
---
|
||||
|
||||
## Выбор кодеков
|
||||
|
||||
### Только H.264 (максимальная совместимость)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -c h264
|
||||
```
|
||||
|
||||
**Когда использовать:**
|
||||
- Старые браузеры и устройства
|
||||
- Гарантированное воспроизведение
|
||||
- Safari/iOS (обязательно для HLS)
|
||||
|
||||
---
|
||||
|
||||
### Только AV1 (максимальное сжатие)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -c av1
|
||||
```
|
||||
|
||||
**Когда использовать:**
|
||||
- Современные браузеры (Chrome 90+, Firefox 90+)
|
||||
- Экономия полосы пропускания
|
||||
- Ограниченное хранилище
|
||||
|
||||
**Экономия:** ~40-50% по сравнению с H.264
|
||||
|
||||
---
|
||||
|
||||
### Dual codec (лучшая стратегия)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -c dual
|
||||
```
|
||||
|
||||
**Преимущества:**
|
||||
- Современные браузеры используют AV1
|
||||
- Старые устройства переключаются на H.264
|
||||
- Автоматический выбор плеером
|
||||
|
||||
---
|
||||
|
||||
## Выбор форматов
|
||||
|
||||
### Только DASH
|
||||
|
||||
```bash
|
||||
avc video.mp4 -f dash
|
||||
```
|
||||
|
||||
**Для кого:**
|
||||
- Веб-плееры: dash.js, Shaka Player, Video.js
|
||||
- Android устройства
|
||||
- Современные smart TV
|
||||
|
||||
---
|
||||
|
||||
### Только HLS
|
||||
|
||||
```bash
|
||||
avc video.mp4 -f hls -c h264
|
||||
```
|
||||
|
||||
**Для кого:**
|
||||
- Apple устройства (iPhone, iPad, Mac)
|
||||
- Safari браузер
|
||||
- Нативная поддержка в iOS
|
||||
|
||||
**Важно:** HLS лучше работает с H.264
|
||||
|
||||
---
|
||||
|
||||
### Оба формата (рекомендуется)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -f both -c dual
|
||||
```
|
||||
|
||||
**Преимущество:** 100% совместимость со всеми устройствами
|
||||
|
||||
---
|
||||
|
||||
## Настройка качества
|
||||
|
||||
### Высокое качество (архивное)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 1080,1440,2160 \
|
||||
-c dual \
|
||||
--h264-cq 18 \
|
||||
--av1-cq 25
|
||||
```
|
||||
|
||||
**Для кого:** Архивы, профессиональные видео
|
||||
|
||||
**Размер:** Большой (~80-90% от исходника)
|
||||
|
||||
---
|
||||
|
||||
### Сбалансированное качество
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 720,1080 \
|
||||
-c dual \
|
||||
--h264-cq 28 \
|
||||
--av1-cq 35
|
||||
```
|
||||
|
||||
**Для кого:** Обычные веб-сайты
|
||||
|
||||
**Размер:** Средний (~40-50% от исходника)
|
||||
|
||||
---
|
||||
|
||||
### Экономия места
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 480,720 \
|
||||
-c av1 \
|
||||
--av1-cq 40
|
||||
```
|
||||
|
||||
**Для кого:** Мобильные приложения, ограниченное хранилище
|
||||
|
||||
**Размер:** Малый (~20-30% от исходника)
|
||||
|
||||
---
|
||||
|
||||
## Постеры
|
||||
|
||||
### Постер с определенной секунды
|
||||
|
||||
```bash
|
||||
# Интересный момент на 30-й секунде
|
||||
avc video.mp4 -p 30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Постер из середины видео
|
||||
|
||||
Сначала узнайте длительность:
|
||||
```bash
|
||||
ffprobe -v error -show_entries format=duration \
|
||||
-of default=noprint_wrappers=1:nokey=1 video.mp4
|
||||
# Вывод: 300.5 (5 минут)
|
||||
|
||||
# Постер из середины (2:30)
|
||||
avc video.mp4 -p 00:02:30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Реальные сценарии
|
||||
|
||||
### 1. Корпоративный сайт
|
||||
|
||||
**Требования:**
|
||||
- Несколько разрешений
|
||||
- Широкая совместимость
|
||||
- Хорошее качество
|
||||
|
||||
```bash
|
||||
avc presentation.mp4 ./public/videos \
|
||||
-r 720,1080 \
|
||||
-c dual \
|
||||
-f both \
|
||||
-p 5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Образовательная платформа
|
||||
|
||||
**Требования:**
|
||||
- Экономия трафика для студентов
|
||||
- Разные устройства
|
||||
- Много видео
|
||||
|
||||
```bash
|
||||
avc lecture.mp4 ./courses/math-101 \
|
||||
-r 360,480,720 \
|
||||
-c av1 \
|
||||
-f dash \
|
||||
--av1-cq 38
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Стриминговый сервис
|
||||
|
||||
**Требования:**
|
||||
- Полный спектр качества
|
||||
- 4K контент
|
||||
- Высокое качество
|
||||
|
||||
```bash
|
||||
avc movie.mp4 ./cdn/movies/avatar \
|
||||
-r 360,720,1080,1440,2160 \
|
||||
-c dual \
|
||||
-f both \
|
||||
--h264-cq 23 \
|
||||
--av1-cq 30 \
|
||||
-p 00:00:10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Игровой портал
|
||||
|
||||
**Требования:**
|
||||
- Высокий FPS
|
||||
- Геймплейные видео
|
||||
- Плавность
|
||||
|
||||
```bash
|
||||
avc gameplay.mp4 ./streams \
|
||||
-r 720@60,1080@60,1440@120 \
|
||||
-c dual \
|
||||
-f dash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Мобильное приложение
|
||||
|
||||
**Требования:**
|
||||
- Минимальный трафик
|
||||
- Быстрая загрузка
|
||||
- Малые разрешения
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./app/assets \
|
||||
-r 360,480 \
|
||||
-c av1 \
|
||||
-f dash \
|
||||
--av1-cq 42
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Apple-only приложение
|
||||
|
||||
**Требования:**
|
||||
- iOS/macOS приложение
|
||||
- HLS формат
|
||||
- Надежность
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./ios-app/videos \
|
||||
-r 480,720,1080 \
|
||||
-c h264 \
|
||||
-f hls \
|
||||
-p 00:00:03
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Пакетная обработка
|
||||
|
||||
### Bash script для множества файлов
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Конвертация всех MP4 файлов в папке
|
||||
for video in *.mp4; do
|
||||
echo "Converting: $video"
|
||||
avc "$video" ./output \
|
||||
-r 720,1080 \
|
||||
-c dual \
|
||||
-f both
|
||||
done
|
||||
|
||||
echo "All videos converted!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### С сохранением структуры папок
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Найти все MP4 и конвертировать
|
||||
find ./source -name "*.mp4" -type f | while read video; do
|
||||
# Получить путь относительно source
|
||||
rel_path="${video#./source/}"
|
||||
dir_name=$(dirname "$rel_path")
|
||||
|
||||
# Создать выходную директорию
|
||||
mkdir -p "./output/$dir_name"
|
||||
|
||||
# Конвертировать
|
||||
avc "$video" "./output/$dir_name" \
|
||||
-r 720,1080 \
|
||||
-c dual \
|
||||
-f both
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Оптимизация производительности
|
||||
|
||||
### Быстрая конвертация (минимум профилей)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 720 -c h264 -f dash
|
||||
```
|
||||
|
||||
**Время:** ~30% от полной конвертации
|
||||
|
||||
---
|
||||
|
||||
### Использование только GPU
|
||||
|
||||
```bash
|
||||
# Убедитесь что NVENC доступен
|
||||
avc video.mp4 -c dual # Автоматически использует NVENC
|
||||
```
|
||||
|
||||
**Скорость:** В 5-10 раз быстрее CPU
|
||||
|
||||
---
|
||||
|
||||
## Проверка результата
|
||||
|
||||
После конвертации проверьте результат:
|
||||
|
||||
```bash
|
||||
# Список созданных файлов
|
||||
ls -lh video/
|
||||
|
||||
# Проверка DASH манифеста
|
||||
cat video/manifest.mpd
|
||||
|
||||
# Проверка HLS манифеста
|
||||
cat video/master.m3u8
|
||||
|
||||
# Размер всех файлов
|
||||
du -sh video/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
- [Опции и ключи](/cli/options) — Полный справочник параметров
|
||||
- [API Библиотеки](/api/) — Использование в коде
|
||||
90
docs/cli/index.md
Normal file
90
docs/cli/index.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# CLI Документация
|
||||
|
||||
Adaptive Video Converter предоставляет мощный интерфейс командной строки для конвертации видео в адаптивные форматы DASH и HLS.
|
||||
|
||||
## Основной синтаксис
|
||||
|
||||
```bash
|
||||
avc <input-video> [output-dir] [options]
|
||||
```
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
Простейший способ использования:
|
||||
|
||||
```bash
|
||||
# Конвертация с настройками по умолчанию
|
||||
avc video.mp4
|
||||
```
|
||||
|
||||
Это создаст в текущей директории папку с именем видео, содержащую:
|
||||
- DASH и HLS манифесты
|
||||
- Сегменты для H.264 и AV1
|
||||
- Автоматически выбранные профили качества
|
||||
- Превью-спрайты и постер
|
||||
|
||||
## Основные возможности
|
||||
|
||||
### 🎯 Автоматическая конфигурация
|
||||
- Автоопределение GPU (NVENC)
|
||||
- Автовыбор профилей качества на основе исходного видео
|
||||
- Динамический расчет битрейтов
|
||||
|
||||
### ⚡ GPU-ускорение
|
||||
- NVIDIA NVENC для H.264 и AV1
|
||||
- Автоматический фоллбек на CPU если GPU недоступен
|
||||
|
||||
### 📊 Адаптивный стриминг
|
||||
- DASH (современный стандарт)
|
||||
- HLS (совместимость с Apple)
|
||||
- Множественные профили качества (360p - 4K)
|
||||
- Поддержка высоких FPS (60/90/120)
|
||||
|
||||
### 🎬 Двойное кодирование
|
||||
- H.264 для максимальной совместимости
|
||||
- AV1 для оптимального качества/размера
|
||||
- Возможность выбрать один кодек
|
||||
|
||||
## Системные требования
|
||||
|
||||
Перед использованием убедитесь, что установлены:
|
||||
|
||||
```bash
|
||||
# Проверка FFmpeg
|
||||
ffmpeg -version
|
||||
|
||||
# Проверка MP4Box
|
||||
MP4Box -version
|
||||
```
|
||||
|
||||
**Необходимо:**
|
||||
- Node.js ≥ 18.0.0
|
||||
- FFmpeg (с NVENC для GPU)
|
||||
- MP4Box (gpac)
|
||||
|
||||
**Опционально:**
|
||||
- NVIDIA GPU с поддержкой NVENC
|
||||
|
||||
## Структура выходных файлов
|
||||
|
||||
```
|
||||
video/
|
||||
├── manifest.mpd # DASH манифест
|
||||
├── master.m3u8 # HLS мастер-плейлист
|
||||
├── 720p-h264/ # Сегменты профиля 720p H.264
|
||||
│ ├── 720p-h264_init.mp4
|
||||
│ └── 720p-h264_*.m4s
|
||||
├── 720p-av1/ # Сегменты профиля 720p AV1
|
||||
├── 1080p-h264/
|
||||
├── 1080p-av1/
|
||||
├── thumbnails.jpg # Спрайт превью (160×90px)
|
||||
├── thumbnails.vtt # WebVTT метки для превью
|
||||
└── poster.jpg # Постер из видео (1-я секунда)
|
||||
```
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
- [Установка](/cli/installation) — Различные способы установки
|
||||
- [Использование](/cli/usage) — Базовые сценарии использования
|
||||
- [Опции и ключи](/cli/options) — Полный справочник параметров
|
||||
- [Примеры](/cli/examples) — Практические примеры для разных задач
|
||||
197
docs/cli/installation.md
Normal file
197
docs/cli/installation.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Установка
|
||||
|
||||
## Системные требования
|
||||
|
||||
### Обязательные зависимости
|
||||
|
||||
**Node.js**
|
||||
```bash
|
||||
node --version # Требуется ≥ 18.0.0
|
||||
```
|
||||
|
||||
**FFmpeg**
|
||||
```bash
|
||||
# Arch Linux
|
||||
sudo pacman -S ffmpeg
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install ffmpeg
|
||||
|
||||
# macOS
|
||||
brew install ffmpeg
|
||||
|
||||
# Проверка
|
||||
ffmpeg -version
|
||||
```
|
||||
|
||||
**MP4Box (gpac)**
|
||||
```bash
|
||||
# Arch Linux
|
||||
sudo pacman -S gpac
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install gpac
|
||||
|
||||
# macOS
|
||||
brew install gpac
|
||||
|
||||
# Проверка
|
||||
MP4Box -version
|
||||
```
|
||||
|
||||
### Опциональные зависимости
|
||||
|
||||
**NVIDIA GPU с NVENC** (для GPU-ускорения)
|
||||
- Драйверы NVIDIA с поддержкой NVENC
|
||||
- FFmpeg собранный с `--enable-nvenc`
|
||||
|
||||
Проверка поддержки:
|
||||
```bash
|
||||
ffmpeg -encoders | grep nvenc
|
||||
```
|
||||
|
||||
Должно показать:
|
||||
```
|
||||
h264_nvenc # H.264 NVENC
|
||||
av1_nvenc # AV1 NVENC (новые GPU)
|
||||
```
|
||||
|
||||
## Способы установки
|
||||
|
||||
### 1. Глобальная установка (рекомендуется)
|
||||
|
||||
```bash
|
||||
npm install -g @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
После установки команда `avc` будет доступна глобально:
|
||||
|
||||
```bash
|
||||
avc --version
|
||||
avc video.mp4
|
||||
```
|
||||
|
||||
### 2. Использование через npx (без установки)
|
||||
|
||||
```bash
|
||||
npx @grom13/adaptive-video-converter video.mp4
|
||||
```
|
||||
|
||||
**Преимущества:**
|
||||
- Не требует установки
|
||||
- Всегда использует последнюю версию
|
||||
- Подходит для разового использования
|
||||
|
||||
**Недостатки:**
|
||||
- Медленнее (загрузка при каждом запуске)
|
||||
- Требует интернет
|
||||
|
||||
### 3. Локальная установка в проект
|
||||
|
||||
```bash
|
||||
npm install @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
Использование через npm scripts:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"convert": "avc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
npm run convert video.mp4
|
||||
```
|
||||
|
||||
## Проверка установки
|
||||
|
||||
После установки проверьте работоспособность:
|
||||
|
||||
```bash
|
||||
# Проверка версии
|
||||
avc --version
|
||||
|
||||
# Или полное название команды
|
||||
adaptive-video-converter --version
|
||||
```
|
||||
|
||||
## Обновление
|
||||
|
||||
### Глобальная установка
|
||||
```bash
|
||||
npm update -g @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
### Локальная установка
|
||||
```bash
|
||||
npm update @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
## Удаление
|
||||
|
||||
### Глобальная установка
|
||||
```bash
|
||||
npm uninstall -g @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
### Локальная установка
|
||||
```bash
|
||||
npm uninstall @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
## Устранение проблем
|
||||
|
||||
### FFmpeg не найден
|
||||
```
|
||||
Error: FFmpeg not found
|
||||
```
|
||||
|
||||
**Решение:**
|
||||
1. Убедитесь что FFmpeg установлен: `ffmpeg -version`
|
||||
2. Проверьте PATH: `which ffmpeg`
|
||||
3. Переустановите FFmpeg
|
||||
|
||||
### MP4Box не найден
|
||||
```
|
||||
Error: MP4Box not found
|
||||
```
|
||||
|
||||
**Решение:**
|
||||
1. Убедитесь что gpac установлен: `MP4Box -version`
|
||||
2. Проверьте PATH: `which MP4Box`
|
||||
3. Переустановите gpac
|
||||
|
||||
### NVENC недоступен
|
||||
```
|
||||
Warning: NVENC not available, using CPU encoding
|
||||
```
|
||||
|
||||
Это предупреждение, не ошибка. Конвертация продолжится на CPU.
|
||||
|
||||
**Для включения NVENC:**
|
||||
1. Установите NVIDIA драйверы
|
||||
2. Убедитесь что FFmpeg собран с NVENC: `ffmpeg -encoders | grep nvenc`
|
||||
3. Если нет — переустановите FFmpeg с поддержкой NVENC
|
||||
|
||||
## Проверка системы
|
||||
|
||||
Перед первым использованием рекомендуется запустить команду, которая покажет доступность всех компонентов:
|
||||
|
||||
```bash
|
||||
avc --help
|
||||
```
|
||||
|
||||
При запуске CLI автоматически проверяет:
|
||||
- ✅ FFmpeg
|
||||
- ✅ MP4Box
|
||||
- ⚠️ NVENC (опционально)
|
||||
- ⚠️ AV1 encoders (опционально)
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
После успешной установки переходите к:
|
||||
- [Использование](/cli/usage) — Базовые сценарии
|
||||
- [Опции и ключи](/cli/options) — Параметры командной строки
|
||||
290
docs/cli/options.md
Normal file
290
docs/cli/options.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# Опции и ключи
|
||||
|
||||
Полный справочник всех доступных опций командной строки.
|
||||
|
||||
## Позиционные аргументы
|
||||
|
||||
### `<input-video>`
|
||||
**Обязательный**. Путь к входному видео файлу.
|
||||
|
||||
```bash
|
||||
avc video.mp4
|
||||
avc /path/to/movie.mkv
|
||||
avc ../videos/stream.avi
|
||||
```
|
||||
|
||||
**Поддерживаемые форматы:** MP4, MKV, AVI, MOV, WebM и другие, поддерживаемые FFmpeg.
|
||||
|
||||
### `[output-dir]`
|
||||
**Опциональный**. Директория для сохранения результата.
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./output
|
||||
avc video.mp4 /var/www/videos
|
||||
```
|
||||
|
||||
**По умолчанию:** `.` (текущая директория)
|
||||
|
||||
**Структура:** Внутри создается папка с именем видео без расширения.
|
||||
|
||||
## Основные опции
|
||||
|
||||
### `-r, --resolutions`
|
||||
Выбор профилей качества (разрешений).
|
||||
|
||||
**Формат:**
|
||||
```bash
|
||||
-r <resolution>[,<resolution>...]
|
||||
-r <resolution>@<fps>[,<resolution>@<fps>...]
|
||||
```
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# Стандартные разрешения (30fps)
|
||||
avc video.mp4 -r 720,1080,1440
|
||||
|
||||
# С указанием FPS
|
||||
avc video.mp4 -r 720@60,1080@60,1440@120
|
||||
|
||||
# Смешанный формат
|
||||
avc video.mp4 -r 360,720@60,1080
|
||||
|
||||
# Одно разрешение
|
||||
avc video.mp4 -r 1080
|
||||
```
|
||||
|
||||
**Поддерживаемые разрешения:**
|
||||
|
||||
| Значение | Разрешение | Название |
|
||||
|----------|------------|----------|
|
||||
| `360` | 640×360 | 360p |
|
||||
| `480` | 854×480 | 480p |
|
||||
| `720` | 1280×720 | 720p HD |
|
||||
| `1080` | 1920×1080 | 1080p Full HD |
|
||||
| `1440` | 2560×1440 | 1440p 2K |
|
||||
| `2160` | 3840×2160 | 2160p 4K |
|
||||
|
||||
**Поддерживаемые FPS:** 30, 60, 90, 120
|
||||
|
||||
**По умолчанию:** Автовыбор на основе исходного видео.
|
||||
|
||||
**Правила автовыбора:**
|
||||
- Исходное ≤ 720p → 360p, 480p, 720p
|
||||
- Исходное 1080p → 360p, 720p, 1080p
|
||||
- Исходное 1440p → 720p, 1080p, 1440p
|
||||
- Исходное 4K → 1080p, 1440p, 2160p
|
||||
|
||||
---
|
||||
|
||||
### `-c, --codec`
|
||||
Выбор видео кодека.
|
||||
|
||||
**Значения:**
|
||||
- `h264` — Только H.264
|
||||
- `av1` — Только AV1
|
||||
- `dual` — Оба кодека (H.264 + AV1)
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# Только H.264 (максимальная совместимость)
|
||||
avc video.mp4 -c h264
|
||||
|
||||
# Только AV1 (лучшее сжатие)
|
||||
avc video.mp4 -c av1
|
||||
|
||||
# Оба кодека
|
||||
avc video.mp4 -c dual
|
||||
```
|
||||
|
||||
**По умолчанию:** `dual`
|
||||
|
||||
**Особенности:**
|
||||
- H.264: Широкая поддержка браузерами и устройствами
|
||||
- AV1: Лучшее качество при меньшем размере, но требует современные браузеры
|
||||
- Dual: Браузер автоматически выберет оптимальный кодек
|
||||
|
||||
---
|
||||
|
||||
### `-f, --format`
|
||||
Выбор формата стриминга.
|
||||
|
||||
**Значения:**
|
||||
- `dash` — Только DASH
|
||||
- `hls` — Только HLS
|
||||
- `both` — Оба формата
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# Только DASH (современный стандарт)
|
||||
avc video.mp4 -f dash
|
||||
|
||||
# Только HLS (для Apple устройств)
|
||||
avc video.mp4 -f hls
|
||||
|
||||
# Оба формата
|
||||
avc video.mp4 -f both
|
||||
```
|
||||
|
||||
**По умолчанию:** `both`
|
||||
|
||||
**Когда использовать:**
|
||||
- `dash` — Современные веб-плееры (dash.js, Shaka Player)
|
||||
- `hls` — Apple устройства, Safari, нативная поддержка в iOS
|
||||
- `both` — Максимальная совместимость
|
||||
|
||||
---
|
||||
|
||||
### `-p, --poster`
|
||||
Таймкод для извлечения постера.
|
||||
|
||||
**Форматы:**
|
||||
- Секунды: `5`, `30`, `120`
|
||||
- Таймкод: `HH:MM:SS` (например, `00:02:30`)
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# С 5-й секунды
|
||||
avc video.mp4 -p 5
|
||||
|
||||
# С 2 минут 30 секунд
|
||||
avc video.mp4 -p 00:02:30
|
||||
|
||||
# С 1 часа 15 минут
|
||||
avc video.mp4 -p 01:15:00
|
||||
```
|
||||
|
||||
**По умолчанию:** `1` (1-я секунда)
|
||||
|
||||
---
|
||||
|
||||
## Опции качества
|
||||
|
||||
Эти опции позволяют вручную контролировать качество кодирования. Используйте только если понимаете что делаете.
|
||||
|
||||
### `--h264-cq`
|
||||
Значение CQ (Constant Quality) для H.264 NVENC GPU кодирования.
|
||||
|
||||
**Диапазон:** 0-51 (меньше = лучше качество, больше размер)
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# Очень высокое качество
|
||||
avc video.mp4 -c h264 --h264-cq 18
|
||||
|
||||
# Балан между качеством и размером
|
||||
avc video.mp4 -c h264 --h264-cq 28
|
||||
|
||||
# Экономия места
|
||||
avc video.mp4 -c h264 --h264-cq 35
|
||||
```
|
||||
|
||||
**По умолчанию:** Автоматический расчет на основе разрешения и битрейта
|
||||
|
||||
**Рекомендации:**
|
||||
- 18-23: Практически без потерь (большой размер)
|
||||
- 23-28: Отличное качество (средний размер)
|
||||
- 28-33: Хорошее качество (малый размер)
|
||||
- 33+: Заметные артефакты
|
||||
|
||||
---
|
||||
|
||||
### `--h264-crf`
|
||||
Значение CRF для H.264 CPU (libx264) кодирования.
|
||||
|
||||
**Диапазон:** 0-51
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
avc video.mp4 -c h264 --h264-crf 20
|
||||
```
|
||||
|
||||
**Используется:** Когда NVENC недоступен (фоллбек на CPU)
|
||||
|
||||
---
|
||||
|
||||
### `--av1-cq`
|
||||
Значение CQ для AV1 NVENC GPU кодирования.
|
||||
|
||||
**Диапазон:** 0-51
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# Высокое качество AV1
|
||||
avc video.mp4 -c av1 --av1-cq 30
|
||||
|
||||
# Dual codec с разным качеством
|
||||
avc video.mp4 -c dual --h264-cq 28 --av1-cq 35
|
||||
```
|
||||
|
||||
**По умолчанию:** Автоматический расчет
|
||||
|
||||
**Рекомендации:**
|
||||
- AV1 обычно на 5-8 единиц выше чем H.264 для того же визуального качества
|
||||
- Если H.264 CQ=28, то AV1 CQ=35-37
|
||||
|
||||
---
|
||||
|
||||
### `--av1-crf`
|
||||
Значение CRF для AV1 CPU (libsvtav1) кодирования.
|
||||
|
||||
**Диапазон:** 0-63
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
avc video.mp4 -c av1 --av1-crf 35
|
||||
```
|
||||
|
||||
**Используется:** Когда AV1 NVENC недоступен
|
||||
|
||||
---
|
||||
|
||||
## Комбинации опций
|
||||
|
||||
### Веб-сайт (стандартное качество)
|
||||
```bash
|
||||
avc video.mp4 -r 720,1080 -c dual -f both
|
||||
```
|
||||
|
||||
### Стриминговый сервис (высокое качество)
|
||||
```bash
|
||||
avc video.mp4 -r 360,720,1080,1440,2160 -c dual -f both --h264-cq 23 --av1-cq 30
|
||||
```
|
||||
|
||||
### Мобильные устройства (экономия трафика)
|
||||
```bash
|
||||
avc video.mp4 -r 360,480,720 -c av1 -f dash --av1-cq 40
|
||||
```
|
||||
|
||||
### Игровой контент (60 FPS)
|
||||
```bash
|
||||
avc video.mp4 -r 720@60,1080@60,1440@120 -c dual -f dash
|
||||
```
|
||||
|
||||
### Apple экосистема
|
||||
```bash
|
||||
avc video.mp4 -r 720,1080 -c h264 -f hls
|
||||
```
|
||||
|
||||
### Архивное качество (максимум)
|
||||
```bash
|
||||
avc video.mp4 -r 1080,1440,2160 -c dual -f both --h264-cq 18 --av1-cq 25
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Логи и отладка
|
||||
|
||||
CLI автоматически создает файл `conversion.log` в выходной директории с подробной информацией о конвертации.
|
||||
|
||||
**Содержимое:**
|
||||
- Параметры FFmpeg
|
||||
- Битрейты каждого профиля
|
||||
- Время кодирования
|
||||
- Ошибки и предупреждения
|
||||
|
||||
---
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
- [Примеры](/cli/examples) — Практические сценарии использования
|
||||
- [API Библиотеки](/api/) — Программное использование
|
||||
215
docs/cli/usage.md
Normal file
215
docs/cli/usage.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Использование
|
||||
|
||||
## Базовый синтаксис
|
||||
|
||||
```bash
|
||||
avc <input-video> [output-dir] [options]
|
||||
```
|
||||
|
||||
## Позиционные аргументы
|
||||
|
||||
| Аргумент | Описание | По умолчанию |
|
||||
|----------|----------|--------------|
|
||||
| `<input-video>` | Путь к входному видео файлу | **Обязательный** |
|
||||
| `[output-dir]` | Директория для результата | `.` (текущая папка) |
|
||||
|
||||
## Базовые сценарии
|
||||
|
||||
### 1. Простейшая конвертация
|
||||
|
||||
```bash
|
||||
avc video.mp4
|
||||
```
|
||||
|
||||
**Что происходит:**
|
||||
- Создается папка `video/` в текущей директории
|
||||
- Генерируются DASH и HLS манифесты
|
||||
- Используются оба кодека (H.264 + AV1)
|
||||
- Автоматический выбор профилей качества
|
||||
- GPU-ускорение если доступно
|
||||
|
||||
### 2. Указание выходной директории
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./output
|
||||
```
|
||||
|
||||
Результат будет в `./output/video/`
|
||||
|
||||
```bash
|
||||
avc video.mp4 /var/www/cdn/videos
|
||||
```
|
||||
|
||||
Результат будет в `/var/www/cdn/videos/video/`
|
||||
|
||||
### 3. Выбор разрешений
|
||||
|
||||
```bash
|
||||
# Конкретные разрешения
|
||||
avc video.mp4 -r 720,1080,1440
|
||||
|
||||
# Только одно разрешение
|
||||
avc video.mp4 -r 1080
|
||||
```
|
||||
|
||||
### 4. Выбор кодека
|
||||
|
||||
```bash
|
||||
# Только H.264 (максимальная совместимость)
|
||||
avc video.mp4 -c h264
|
||||
|
||||
# Только AV1 (лучшее сжатие)
|
||||
avc video.mp4 -c av1
|
||||
|
||||
# Оба кодека (по умолчанию)
|
||||
avc video.mp4 -c dual
|
||||
```
|
||||
|
||||
### 5. Выбор формата
|
||||
|
||||
```bash
|
||||
# Только DASH
|
||||
avc video.mp4 -f dash
|
||||
|
||||
# Только HLS (для Apple устройств)
|
||||
avc video.mp4 -f hls
|
||||
|
||||
# Оба формата (по умолчанию)
|
||||
avc video.mp4 -f both
|
||||
```
|
||||
|
||||
## Типичные рабочие процессы
|
||||
|
||||
### Для веб-сайта (универсальная совместимость)
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./public/videos -r 720,1080 -c dual -f both
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- DASH для современных браузеров
|
||||
- HLS для Safari/iOS
|
||||
- H.264 для старых устройств
|
||||
- AV1 для экономии трафика
|
||||
|
||||
### Для стримингового сервиса (максимальное качество)
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./cdn -r 360,720,1080,1440,2160 -c dual -f both
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- Полный спектр качества от 360p до 4K
|
||||
- Адаптация под любую скорость интернета
|
||||
|
||||
### Для игрового контента (высокий FPS)
|
||||
|
||||
```bash
|
||||
avc gameplay.mp4 -r 720@60,1080@60,1440@120 -c dual
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- Поддержка 60 и 120 FPS
|
||||
- Плавное воспроизведение
|
||||
|
||||
### Для мобильных устройств (экономия трафика)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 360,480,720 -c av1 -f dash
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- Небольшие размеры файлов (AV1)
|
||||
- Подходящие разрешения для мобильных
|
||||
|
||||
### Только для Apple экосистемы
|
||||
|
||||
```bash
|
||||
avc video.mp4 -f hls -c h264
|
||||
```
|
||||
|
||||
**Результат:**
|
||||
- HLS формат (нативная поддержка)
|
||||
- H.264 (гарантированная совместимость)
|
||||
|
||||
## Работа с постерами
|
||||
|
||||
### Постер с определенной секунды
|
||||
|
||||
```bash
|
||||
# С 5-й секунды
|
||||
avc video.mp4 -p 5
|
||||
|
||||
# С 2 минут 30 секунд
|
||||
avc video.mp4 -p 00:02:30
|
||||
|
||||
# С 1 часа 15 минут 45 секунд
|
||||
avc video.mp4 -p 01:15:45
|
||||
```
|
||||
|
||||
## Комбинированные примеры
|
||||
|
||||
### Максимальная производительность (только GPU)
|
||||
|
||||
```bash
|
||||
avc video.mp4 ./output \
|
||||
-r 720,1080,1440 \
|
||||
-c dual \
|
||||
-f both \
|
||||
-p 5
|
||||
```
|
||||
|
||||
### Минимальный размер файлов
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 720,1080 -c av1 -f dash
|
||||
```
|
||||
|
||||
### Быстрая конвертация (меньше профилей)
|
||||
|
||||
```bash
|
||||
avc video.mp4 -r 720 -c h264 -f dash
|
||||
```
|
||||
|
||||
## Мониторинг прогресса
|
||||
|
||||
CLI автоматически показывает прогресс:
|
||||
|
||||
```
|
||||
🔍 Checking system...
|
||||
|
||||
✅ FFmpeg found
|
||||
✅ MP4Box found
|
||||
✅ NVENC available (H.264)
|
||||
✅ AV1 NVENC available
|
||||
|
||||
📹 Analyzing video...
|
||||
Resolution: 1920x1080 @ 30fps
|
||||
Duration: 00:05:30
|
||||
Bitrate: 5000 kbps
|
||||
|
||||
🎯 Selected profiles:
|
||||
- 360p @ 30fps
|
||||
- 720p @ 30fps
|
||||
- 1080p @ 30fps
|
||||
|
||||
⚙️ Encoding profiles...
|
||||
[████████████████████] 100% | 1080p-h264
|
||||
[████████████████████] 100% | 1080p-av1
|
||||
...
|
||||
|
||||
📦 Packaging DASH/HLS...
|
||||
✅ DASH manifest created
|
||||
✅ HLS master playlist created
|
||||
|
||||
🖼️ Generating thumbnails...
|
||||
✅ Thumbnail sprite created
|
||||
|
||||
✅ Conversion complete!
|
||||
Output: ./video/
|
||||
```
|
||||
|
||||
## Следующие шаги
|
||||
|
||||
- [Опции и ключи](/cli/options) — Полный справочник всех параметров
|
||||
- [Примеры](/cli/examples) — Дополнительные практические примеры
|
||||
143
docs/index.md
Normal file
143
docs/index.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: "Adaptive Video Converter"
|
||||
text: "Конвертер видео в адаптивные форматы"
|
||||
tagline: DASH и HLS с GPU-ускорением (NVENC) и генерацией превью
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Быстрый старт
|
||||
link: /guide/getting-started
|
||||
- theme: alt
|
||||
text: Возможности
|
||||
link: /FEATURES
|
||||
- theme: alt
|
||||
text: API Reference
|
||||
link: /api/overview
|
||||
|
||||
features:
|
||||
- icon: ⚡
|
||||
title: GPU-ускорение
|
||||
details: Использование NVIDIA NVENC для быстрого кодирования H.264 и AV1 с фоллбеком на CPU
|
||||
|
||||
- icon: 🎯
|
||||
title: DASH + HLS
|
||||
details: Поддержка обоих форматов адаптивного стриминга для максимальной совместимости
|
||||
|
||||
- icon: 📊
|
||||
title: Адаптивный битрейт (ABR)
|
||||
details: Автоматическое создание множественных профилей качества от 360p до 4K
|
||||
|
||||
- icon: 🎬
|
||||
title: Dual Codec
|
||||
details: Одновременная генерация H.264 (совместимость) и AV1 (эффективность)
|
||||
|
||||
- icon: 🖼️
|
||||
title: Превью-спрайты
|
||||
details: Автоматическая генерация thumbnail спрайтов с VTT для seek preview
|
||||
|
||||
- icon: 📸
|
||||
title: Постер
|
||||
details: Извлечение постера из видео в заданном таймкоде
|
||||
|
||||
- icon: ⏱️
|
||||
title: Прогресс в реальном времени
|
||||
details: Детальное отображение прогресса конвертации с процентами и ETA
|
||||
|
||||
- icon: 🔧
|
||||
title: CLI + API
|
||||
details: Удобный CLI для терминала и программный API для интеграции
|
||||
|
||||
- icon: 🚀
|
||||
title: Параллельное кодирование
|
||||
details: Одновременное кодирование нескольких профилей для максимальной скорости
|
||||
---
|
||||
|
||||
## Быстрая установка
|
||||
|
||||
::: code-group
|
||||
|
||||
```bash [npm]
|
||||
npm install -g @grom13/adaptive-video-converter
|
||||
```
|
||||
|
||||
```bash [npx (без установки)]
|
||||
npx @grom13/adaptive-video-converter video.mp4
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Использование
|
||||
|
||||
```bash
|
||||
# Базовая конвертация
|
||||
avc video.mp4
|
||||
|
||||
# С параметрами
|
||||
avc video.mp4 ./output -r 720,1080,1440 -c dual -f both
|
||||
|
||||
# Только HLS для Safari/iOS
|
||||
avc video.mp4 -f hls -c h264
|
||||
|
||||
# Высокий FPS для игровых стримов
|
||||
avc video.mp4 -r 720@60,1080@60,1440@120
|
||||
```
|
||||
|
||||
## Системные требования
|
||||
|
||||
- Node.js ≥ 18.0.0
|
||||
- FFmpeg (с поддержкой NVENC для GPU)
|
||||
- MP4Box (gpac)
|
||||
- Опционально: NVIDIA GPU с NVENC
|
||||
|
||||
::: tip
|
||||
Проверьте наличие необходимых инструментов:
|
||||
```bash
|
||||
ffmpeg -version
|
||||
MP4Box -version
|
||||
```
|
||||
:::
|
||||
|
||||
## Результат
|
||||
|
||||
После конвертации вы получите:
|
||||
|
||||
```
|
||||
video/
|
||||
├── manifest.mpd # DASH манифест
|
||||
├── master.m3u8 # HLS мастер-плейлист
|
||||
├── 720p-h264/ # Сегменты по профилям
|
||||
├── 720p-av1/
|
||||
├── 1080p-h264/
|
||||
├── 1080p-av1/
|
||||
├── thumbnails.jpg # Спрайт превью
|
||||
├── thumbnails.vtt # WebVTT временные метки
|
||||
└── poster.jpg # Постер
|
||||
```
|
||||
|
||||
## Программное использование
|
||||
|
||||
```typescript
|
||||
import { convertToDash } from '@grom13/adaptive-video-converter';
|
||||
|
||||
const result = await convertToDash({
|
||||
inputPath: './video.mp4',
|
||||
outputDir: './output',
|
||||
codecType: 'dual',
|
||||
format: 'both',
|
||||
onProgress: (progress) => {
|
||||
console.log(`${progress.percent}% - ${progress.stage}`);
|
||||
}
|
||||
});
|
||||
|
||||
console.log('Готово:', result.manifestPath);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<div style="text-align: center; margin-top: 2rem;">
|
||||
<a href="/guide/getting-started" style="font-size: 1.2rem;">
|
||||
→ Начать работу с документацией
|
||||
</a>
|
||||
</div>
|
||||
2593
package-lock.json
generated
Normal file
2593
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
@@ -27,7 +27,9 @@
|
||||
"build:cli": "bun build src/cli.ts --outfile bin/cli.js --target node --minify",
|
||||
"prepublishOnly": "npm run build",
|
||||
"dev": "bun run src/cli.ts",
|
||||
"test": "bun run src/cli.ts"
|
||||
"test": "bun run src/cli.ts",
|
||||
"docs:dev": "vitepress dev docs",
|
||||
"docs:build": "vitepress build docs"
|
||||
},
|
||||
"keywords": [
|
||||
"adaptive-video",
|
||||
@@ -60,10 +62,10 @@
|
||||
"devDependencies": {
|
||||
"@types/bun": "^1.3.2",
|
||||
"@types/cli-progress": "^3.11.6",
|
||||
"typescript": "^5.3.3"
|
||||
"typescript": "^5.3.3",
|
||||
"vitepress": "^1.6.4"
|
||||
},
|
||||
"dependencies": {
|
||||
"cli-progress": "^3.12.0"
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user