adaptive-video-converter/docs/api/types.md

# 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 тип