Конвертер видео в стриминговый формат hls

Конвертер видеофайлов из любых популярных форматов в стриминговый формат HLS (HTTP Live Streaming) с помощью FFmpeg

Что делает проект

• Конвертирует отдельный видеофайл или все видео из папки video (рекурсивно) в HLS-плейлисты с сегментами
• Поддерживает большинство популярных форматов видео: .mov, .mp4, .mkv, .avi, .webm, .flv, .wmv, .mpeg, .mpg и др.
• Позволяет гибко настраивать параметры качества и форматирования через аргументы скриптов

Структура проекта

/
├─ scripts/
│ └─ clear-folder.js # Утилита для очистки папок (оставляет .gitignore)
├─ video/ # Исходные видеофайлы (источник)
├─ video-hls/ # Папка с результатами конвертации в HLS
├─ config.json # Конфигурационный файл для параметров конвертации и пресетов
├─ convert-to-hls.ps1 # Скрипт для конвертации видео из папки video
├─ package.json # Скрипты npm для запуска задач
└─ README.md # Этот файл

Рекомендуемая структура папки video

Чтобы избежать хаоса при работе с большим количеством видео, рекомендуется структурировать папку video/. Это помогает:

• Сохранять порядок в исходниках и в итоговых HLS-папках
• Поддерживать читаемую иерархию
• Исключать случайные пересечения имён и путей

Пример структуры:

video/
├── module-1/
│   ├── video-1.mov
│   └── video-2.mov
├── module-2/
│   ├── video-1.mov
│   └── video-2.mov

После конвертации структура сохраняется в video-hls/:

video-hls/
├── module-1/
│   ├── video-1/
│   │   ├── video-1.m3u8
│   │   └── segment0.ts ...
│   └── video-2/
│       ├── video-2.m3u8
│       └── segment0.ts ...
├── module-2/
│   ├── video-1/
│   │   ├── video-1.m3u8
│   │   └── segment0.ts ...
│   └── video-2/
│       ├── video-2.m3u8
│       └── segment0.ts ...

Почему так лучше:

• Каждый видеофайл попадает в отдельную HLS-папку, названную по имени файла (без расширения)
• Исходная структура вложенных папок сохраняется
• Можно использовать video/ как библиотеку исходников и video-hls/ как прод-выход без риска путаницы

Примеры запуска

1. Запуск с параметрами по умолчанию

Если не передавать никаких параметров, будут использованы значения по умолчанию из скрипта (например, height=1080, crf=23 и т.д.):

npm run convert

2. Запуск с указанием пресета из конфига

Чтобы использовать заранее заданный пресет из конфигурационного файла (например, fullhd-high, fullhd-medium, fullhd-low), передай его через параметр -presetName:

npm run convert -- -presetName fullhd-high
npm run convert -- -presetName fullhd-medium
npm run convert -- -presetName fullhd-low

Примечание: пресеты задаются в конфиге (config.json), где хранятся параметры качества, битрейты и прочее

3. Запуск с кастомными параметрами (переопределение пресета или дефолта)

Можно явно указать любые параметры, чтобы переопределить либо дефолты, либо параметры из пресета:

npm run convert -- -height 720 -crf 28 -preset veryfast -audioBitrate 96 -hlsTime 4

Или совместить пресет с частичным переопределением параметров:

npm run convert -- -presetName fullhd-high -crf 20 -hlsTime 8

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

Параметр	Описание	Значение по умолчанию
height	Высота видео после ресайза. Ширина считается автоматически, кратной 2	1080
crf	Constant Rate Factor — качество видео. Чем меньше, тем выше качество и размер файла	23
preset	Предустановка скорости кодирования: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow	slow
audioBitrate	Битрейт аудио в килобитах	128
hlsTime	Длительность сегмента в секундах (для HLS)	6

Как влияют параметры на качество и размер видео

• height и масштабирование (scale=-2:height): Задаёт вертикальное разрешение выходного видео. Ширина автоматически рассчитывается для сохранения пропорций и кратности 2 (требование кодека H.264)

• crf (Constant Rate Factor): Основной параметр качества видеокодека x264. Значения от 0 (максимальное качество и размер) до 51 (минимальное качество). Рекомендуется 18-28, 23 — сбалансированное качество. Меньше — лучше качество, но больше размер

• preset: Определяет скорость кодирования. Чем быстрее — хуже качество при том же crf и меньше нагрузка на CPU. Чем медленнее — выше качество и дольше кодирование

• audioBitrate: Битрейт аудиопотока. Чем выше, тем лучше качество звука и больше размер аудио. Обычно достаточно 128 кбит/с

• hlsTime: Время одного сегмента в секундах. Меньше время — более плавное переключение в стриминге, но больше файлов и overhead

Очистка папок

В проекте есть скрипт для безопасной очистки папок video и video-hls, который не удаляет сами папки и .gitignore внутри них:

npm run clear:source     # Очистка папки с исходными видео (video)
npm run clear:converted  # Очистка папки с конвертированными видео (video-hls)

Требования и совместимость

Node.js

• Требуется Node.js версии 18 и выше

PowerShell

• Скрипты написаны на PowerShell 7+

• Проверить установленную версию можно командой:

  $PSVersionTable.PSVersion

• Если у тебя Windows и используется устаревший PowerShell 5.1, рекомендуется установить PowerShell 7 с официального репозитория: https://github.com/PowerShell/PowerShell

FFmpeg

Для конвертации используется FFmpeg с поддержкой HLS и кодека libx264

Проверка наличия

Проверь, установлен ли ffmpeg и доступен ли он в PATH:

ffmpeg -version

Убедись, что в выводе присутствует строка:

configuration: --enable-gpl --enable-libx264 ...

Установка FFmpeg

Windows (через Chocolatey)

choco install ffmpeg

Или вручную:

1. Перейди на сайт: https://ffmpeg.org/download.html
2. Скачай релиз от Gyan или BtbN
3. Распакуй в удобное место, добавь путь к bin/ в переменную окружения PATH

Важно: FFmpeg должен быть установлен глобально и доступен из командной строки. Скрипт не проверяет наличие ffmpeg, поэтому ошибки будут появляться уже на этапе запуска.