Last updated 2026-06-29 15:18

vf/overlay

1. Сводка

Накладывает второе видео или графику на базовое видео. Применяется для брендовых логотипов, водяных знаков, нижних третей, прожига таймкода и «картинки в картинке». Наложение позиционируется попиксельными смещениями и сохраняет собственный альфа-канал, когда он есть.

2. Когда использовать

• Прожигаете брендовый логотип на каждом кадре поставки.
• Добавляете водяной знак на превью или черновое ревью-кодирование.
• Составляете компоновку «картинка в картинке» или сплит-скрин из двух исходных видео.
• Прожигаете таймкод, нижние трети или другие графические наложения во время кодирования, а не при выдаче.

3. Входы

• Main — filtergraph.VideoTransform. Базовое видео, на которое рисуется наложение. Обязателен.

  Совместимые узлы выше по потоку:

  • vf/crop — обрезает кадр до интересующей области.
  • vf/dar — задаёт метаданные соотношения сторон при отображении.
  • vf/deinterlace — убирает артефакты чересстрочности.
  • vf/fieldorder — меняет или задаёт флаг порядка полей.
  • vf/format — преобразует пиксельный формат или цветовые свойства.
  • vf/fps — меняет частоту кадров на выходе.
  • vf/hwupload — загружает кадры в GPU для аппаратной обработки.
  • vf/letterbox — дополняет кадр до целевого растра.
  • vf/scale — масштабирует видео до заданных размеров.
  • map/video — выбирает видеопоток для выхода.

• Overlay — filtergraph.VideoTransform. Источник наложения — логотип, водяной знак или второе видео. Обязателен.

  Совместимые узлы выше по потоку:

  • download — загружает графический файл (PNG, MOV, MP4) по известному URL.
  • map/video — выбирает видеопоток из второго источника.
  • vf/scale — меняет размер графики наложения до её финального экранного размера.
  • vf/format — приводит пиксельный формат наложения к формату базового видео, чтобы композит был чистым.

4. Выходы

• Video — filtergraph.VideoTransform. Композитированный кадр.

  Совместимые узлы ниже по потоку:

  • vf/crop — обрезает кадр до интересующей области.
  • vf/dar — задаёт метаданные соотношения сторон при отображении.
  • vf/deinterlace — убирает артефакты чересстрочности.
  • vf/fieldorder — меняет или задаёт флаг порядка полей.
  • vf/format — преобразует пиксельный формат или цветовые свойства.
  • vf/fps — меняет частоту кадров на выходе.
  • vf/hwupload — загружает кадры в GPU для аппаратной обработки.
  • vf/letterbox — дополняет кадр до целевого растра.
  • vf/scale — масштабирует видео до заданных размеров.
  • avcintra — кодирует видео профилями AVC-Intra.
  • dv — пишет выход как файл/контейнер DV.
  • ni264 — использует аппаратно-ускоренное кодирование H.264.
  • prores — кодирует видео в профили Apple ProRes.
  • qsv264 — кодирует H.264 через Intel Quick Sync Video.
  • x264 — программно кодирует видео H.264/AVC.
  • x265 — программно кодирует видео H.265/HEVC.
  • xdcam — кодирует XDCAM HD MXF для вещательной доставки.

5. Параметры

Форма «Настройки» — один столбец с двумя полями. Описаны в порядке следования в форме.

• X (string пиксели или выражение, без значения по умолчанию)

  Горизонтальная позиция наложения относительно базового кадра.

  • Что задаёт. Где рисуется левый край наложения, отсчитываемый от левого края базового видео. Значение принимает фиксированное число пикселей (24, 100) или выражение с шириной базы W и шириной наложения w ((W-w)/2 центрирует по горизонтали, W-w-24 выравнивает вправо с отступом 24 px).
  • Когда менять. Задавайте для каждого наложения — разумного значения по умолчанию нет. Используйте фиксированные пиксели для угловых логотипов и выражения — для центрированных или выровненных вправо размещений, которые подстраиваются под разные размеры наложения.

• Y (string пиксели или выражение, без значения по умолчанию)

  Вертикальная позиция наложения.

  • Что задаёт. Где рисуется верхний край наложения, отсчитываемый от верха базового видео. Тот же синтаксис выражений, что и у X, с H (высота базы) и h (высота наложения).
  • Когда менять. Задавайте явно для каждого наложения. H-h-24 ставит логотип заподлицо с нижне-правым отступом; (H-h)/2 центрирует по вертикали.

Соответствие JSON-ключей и названий полей

JSON-ключ	Название поля
x	X
y	Y

6. Пример

Полный разбор — переменные, настройка каждого узла и ожидаемый результат — смотрите в MP4 with branded logo overlay.

7. Где используется

• MP4 with branded logo overlay — накладывает брендовый логотип на каждый кадр поставки 1080p H.264.
• Three-tier MP4 ladder (LQ / MQ / HQ) — прожигает идентификационное наложение на тире HQ лестницы распространения.

8. Антипаттерны

• Композитинг без согласования пиксельных форматов. Когда база и наложение несут разные пиксельные форматы (например, база yuv420p, наложение yuva422p), композит падает с ошибкой или показывает цветовые артефакты. Сначала прогоните vf/format на обеих ветвях.

• Наложение графики без изменения её размера. 4K-логотип на кадре 720p оставляет часть наложения за экраном; 200-пиксельный логотип на 4K-кадре невидим. Меняйте размер ветви наложения узлом vf/scale перед vf/overlay.

• Забытая обработка альфа-канала на наложениях PNG / MOV. Когда наложение — плоский формат изображения, альфа-канала может не быть. Либо преобразуйте в формат, несущий альфу (yuva422p), либо примите прямоугольный композит.

• Использование vf/overlay там, где подошла бы chrome-надстройка плеера. Прожиг таймкода, логотипов или водяных знаков в каждый кадр раздувает размер файла и не даёт удалить их при выдаче. Берите vf/overlay только когда прожиг постоянен и намеренен.