Модуль GStreamer: серверный транскодинг HLS/fMP4

GStreamer-модуль принимает HTTP/HTTPS-ссылку на MKV или WebM и отдаёт поток как HLS/fMP4. По умолчанию видео не перекодируется: H.264, H.265, AV1 и VP9 копируются в новый контейнер без потери качества. AAC-аудио тоже копируется, а остальные аудиокодеки автоматически преобразуются в AAC.

Быстрое включение

Включите модуль в init.conf

"gst": {
  "enable": true
}

Или в init.yaml:

gst:
  enable: true

Добавьте плагин в Lampa

Укажите адрес:

http://192.168.1.10:9118/gst.js

Замените 192.168.1.10 на IP-адрес сервера Core.

Установите GStreamer (Linux/macOS)

В Windows portable-библиотеки уже включены. Для Linux и macOS выполните инструкции из раздела Установка.

Copy или transcode

Для большинства файлов достаточно режима copy. Оставьте все параметры transcode* выключенными, если устройство умеет воспроизводить исходный видеокодек.

Исходник	Поведение по умолчанию	Параметр для перекодирования
H.264	Copy без потери качества	`transcodeH264: true` перекодирует снова в H.264
H.265 / HEVC	Copy без потери качества	`transcodeH265: true` преобразует в H.264
AV1	Copy без потери качества	`transcodeAV1: true` преобразует в H.264
VP9	Copy без потери качества	`transcodeVP9: true` преобразует в H.264
VP8	Не принимается	`transcodeVP8: true` разрешает VP8 и преобразует в H.264
Контейнер AVI	Не принимается	`transcodeAVI: true` разрешает AVI и преобразует видео в H.264
HDR PQ/HLG	Остаётся HDR	`hdr_to_sdr: true` выполняет tone mapping и перекодирует в H.264 SDR

transcode* запускает полное декодирование и повторное кодирование видео. Это требует заметно больше CPU или GPU, может снизить качество и должно успевать работать в реальном времени. Для 4K нагрузка особенно высокая.

Включайте перекодирование только когда понимаете причину:

устройство не поддерживает H.265, AV1 или VP9
нужно уменьшить видеобитрейт
для H.264 нужны сегменты точной длительности
HDR нужно преобразовать в SDR

Сегментация в режиме copy

В режиме copy для MKV/WebM с найденными CuePoint границы сегментов и значения EXTINF берутся из Cue, поэтому segment_seconds не используется. Если CuePoint недоступны, длительность сегмента зависит от ключевых кадров исходного видео и может немного отличаться от segment_seconds. При перекодировании модуль создаёт ключевые кадры сам, поэтому длительность сегментов точнее.

Аудио

AAC передаётся без перекодирования. AC3, E-AC3, DTS, TrueHD и другие поддерживаемые декодером форматы преобразуются в AAC автоматически, независимо от transcode*. Параметры aac_bitrate, aac_samplerate и aac_channels применяются только при преобразовании аудио в AAC. На готовую AAC-дорожку они не влияют.

Параметры конфигурации

Основные

Параметр	По умолчанию	Назначение
`enable`	`false`	Включает модуль
`allowed_uids`	не задано	Разрешает доступ только указанным UID или токенам. Без списка модуль доступен всем
`conf_uids`	не задано	Отдельные настройки pipeline для конкретных UID
`inactiveMinutes`	`10`	Через сколько минут без запросов приостановить pipeline. При следующем запросе задача возобновится
`maxTasks`	`0`	Максимальное количество задач. `0` отключает лимит. При создании задачи сверх лимита удаляется задача с самым старым `lastActive`
`subtitles`	`true`	Добавляет поддерживаемые текстовые субтитры в HLS как WebVTT. Графические субтитры не преобразуются
`gst_version`	авто	Версия определяется через `gst-inspect-1.0`. Резервное значение: `1.28` в Windows и `1.22` в остальных ОС
`PATH`	`C:\Program Files\gstreamer\1.0\mingw_x86_64`	Корень установленного MinGW GStreamer в Windows
`souphttpsrc_max_mb`	`0`	Максимальная скорость чтения исходного HTTP-потока в MB/s. `0` отключает ограничение
`debugType`	не задано	Служебная диагностика. `mp4box-diff` выводит отклонения временных границ сегментов

Сегменты и кеш

Параметр	По умолчанию	Назначение
`segment_seconds`	`6`	Целевая длительность HLS-сегмента в секундах. Не используется для MKV/WebM copy с CuePoint
`segment_past`	`1`	Сколько готовых сегментов хранить позади текущей позиции клиента. Минимум `1`
`segment_past_mb`	`0`	Максимальный суммарный размер сегментов позади в MB. `0` отключает ограничение
`segment_buffer`	`10`	Сколько сегментов заранее подготовить впереди. Минимум `2`
`segment_buffer_mb`	`0`	Максимальный суммарный размер буфера впереди в MB. `0` отключает ограничение
`segment_diff`	`20`	Допуск выравнивания сегментов по временным меткам ключевых кадров в режиме copy

Аудио

Параметр	По умолчанию	Назначение
`aac_bitrate`	`256`	Битрейт AAC в кбит/с. Для аудио с числом каналов больше двух умножается на два
`aac_samplerate`	`0` (авто)	Частота AAC в Гц. При `0` выбирается ближайшая поддерживаемая частота к исходной
`aac_channels`	`0` (авто)	Число каналов AAC. При `0` используется исходное значение, от 1 до 8

Видео, GPU и HDR

Параметр	По умолчанию	Назначение
`video_bitrate`	`14000`	Целевой битрейт H.264 в кбит/с. Работает только при перекодировании
`hdr_to_sdr`	`false`	Для обнаруженного PQ/HLG HDR выполняет tone mapping в SDR BT.709 и перекодирует в H.264
`useGpu`	`true`	Разрешает GPU-бэкенды модуля. При `false` H.264 кодируется через CPU `x264enc`
`hardwareAcceleration`	`true`	Использует аппаратный H.264 encoder при `useGpu: true`
`x264Ultrafast`	`false`	Для CPU encoder выбирает `ultrafast` вместо `veryfast`. Снижает нагрузку CPU ценой качества

useGpu управляет GPU-бэкендами, добавленными модулем. Он не запрещает стандартному decodebin GStreamer автоматически выбрать доступный аппаратный декодер.

Примеры конфигурации

Обычный режим copy

"gst": {
  "enable": true
}

Это рекомендуемая отправная точка. H.264, H.265, AV1 и VP9 копируются, а видео не занимает encoder CPU/GPU.

Совместимость со старым устройством

"gst": {
  "enable": true,
  "transcodeH265": true,
  "transcodeAV1": true,
  "transcodeVP9": true,
  "video_bitrate": 8000,
  "useGpu": true,
  "hardwareAcceleration": true
}

Перекодируется только кодек текущего файла. Например, H.264 по-прежнему будет передан через copy, а H.265 будет преобразован в H.264 с целевым битрейтом 8000 кбит/с.

Настройки для отдельных UID

conf_uids задаёт отдельный pipeline для конкретного устройства. Параметры профиля не объединяются с основными настройками: неуказанные поля получают стандартные значения. enable, allowed_uids, inactiveMinutes, maxTasks, gst_version и PATH остаются общими.

"gst": {
  "enable": true,
  "allowed_uids": [
    "tv-uid",
    "mobile-uid"
  ],
  "conf_uids": {
    "mobile-uid": {
      "transcodeH265": true,
      "video_bitrate": 4000,
      "segment_seconds": 6,
      "aac_channels": 2,
      "aac_bitrate": 192
    }
  }
}

Для mobile-uid H.265 преобразуется в H.264 4000 кбит/с, не-AAC аудио будет стерео AAC 192 кбит/с, а целевая длительность сегмента составит 6 секунд. tv-uid использует основные настройки.

Установка GStreamer

Windows

Portable MinGW GStreamer уже включён в модуль, дополнительная установка не требуется. При необходимости установите MinGW x86_64 Runtime с официальной страницы. Укажите корневой каталог в PATH:

"gst": {
  "enable": true,
  "PATH": "C:\\Program Files\\gstreamer\\1.0\\mingw_x86_64"
}

Не используйте путь от MSVC-сборки вместе с MinGW-библиотеками модуля.

Linux (Debian/Ubuntu)

apt-get update

apt-get install -y --no-install-recommends \
    libgstreamer1.0-0 \
    libgstreamer-plugins-base1.0-0 \
    gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good \
    gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-base-apps \
    gstreamer1.0-plugins-ugly \
    gstreamer1.0-libav \
    gstreamer1.0-tools \
    ocl-icd-libopencl1 \
    ca-certificates

Готовый libgsthdrtonemap.so для linux-x64 уже включён. Он требует glibc 2.35+ и GStreamer 1.20+ и проверен на Ubuntu 22.04 и Debian 12. ocl-icd-libopencl1 устанавливает OpenCL loader. Реализацию OpenCL предоставляет драйвер GPU. Если подходящий GPU недоступен, HDR tone mapping автоматически использует CPU.

macOS

Установите GStreamer Runtime с официальной страницы. Готовый native hdrtonemap в модуле поставляется только для Windows x64 и Linux x64. На других платформах hdr_to_sdr может быть недоступен.

HDR в SDR

hdr_to_sdr работает только для распознанного PQ или HLG. SDR-видео не проходит через tone mapping. При useGpu: true модуль сначала пробует OpenCL GPU. Если GPU отсутствует или обработка завершается ошибкой, используется CPU fallback. CPU tone mapping 4K-видео может не успевать в реальном времени. HDR-to-SDR всегда заканчивается перекодированием в H.264, поэтому на него также влияют video_bitrate, hardwareAcceleration и x264Ultrafast. Dolby Vision обрабатывается только при наличии распознаваемого PQ/HLG base layer; динамические RPU metadata не применяются.

Проверка GStreamer

Для системной установки проверьте доступную версию:

gst-inspect-1.0 --version

В portable Windows эта команда может быть недоступна в обычном терминале: модуль настраивает пути GStreamer только внутри процесса Core. Версия GStreamer, результат проверки аппаратного encoder и доступность HDR backend записываются при запуске Core. Если версия успешно определяется, gst_version вручную задавать не нужно.

Get Started

Configuration

Architecture

Modules

Content Providers

Deployment

Maintenance

Модуль GStreamer: серверный транскодинг HLS/fMP4

Быстрое включение

Copy или transcode

Сегментация в режиме copy

Аудио

Параметры конфигурации

Основные

Сегменты и кеш

Аудио

Видео, GPU и HDR

Примеры конфигурации

Обычный режим copy

Совместимость со старым устройством

Настройки для отдельных UID

Установка GStreamer

Windows

Linux (Debian/Ubuntu)

macOS

HDR в SDR

Проверка GStreamer

​Быстрое включение

​Copy или transcode

​Сегментация в режиме copy

​Аудио

​Параметры конфигурации

​Основные

​Сегменты и кеш

​Аудио

​Видео, GPU и HDR

​Примеры конфигурации

​Обычный режим copy

​Совместимость со старым устройством

​Настройки для отдельных UID

​Установка GStreamer

​Windows

​Linux (Debian/Ubuntu)

​macOS

​HDR в SDR

​Проверка GStreamer

Быстрое включение

Copy или transcode

Сегментация в режиме copy

Аудио

Параметры конфигурации

Основные

Сегменты и кеш

Аудио

Видео, GPU и HDR

Примеры конфигурации

Обычный режим copy

Совместимость со старым устройством

Настройки для отдельных UID

Установка GStreamer

Windows

Linux (Debian/Ubuntu)

macOS

HDR в SDR

Проверка GStreamer