Last updated 2026-06-29 15:18

vf/letterbox

1. Сводка

Добавляет полосы леттербокса или пилларбокса, чтобы вписать кадр в целевое соотношение сторон без обрезки. Исходный кадр центрируется поверх сплошного фона, заполняющего разницу между источником и выбранным кадром.

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

• Дополняете 16:9-источник в 4:3-растр SD (DVCPRO, DV PAL) без потери краёв.
• Дополняете 4:3-мастер в 16:9-поставку, чтобы картинка сидела в центрированном пилларбоксе.
• Приводите вертикальный или нестандартный источник в стандартный кадр 16:9 или 4:3 для распространения с фиксированным соотношением.
• Сочетаете с vf/scale, чтобы дойти до точного целевого растра, когда соотношение источника не совпадает.

3. Входы

• Video — filtergraph.VideoTransform. Видео для дополнения. Обязателен.

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

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

4. Выходы

• Video — filtergraph.VideoTransform. Дополненное видео в выбранном соотношении.

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

  • vf/crop — обрезает кадр до интересующей области.
  • vf/dar — задаёт метаданные соотношения сторон при отображении.
  • vf/deinterlace — убирает артефакты чересстрочности.
  • vf/fieldorder — меняет или задаёт флаг порядка полей.
  • vf/format — преобразует пиксельный формат или цветовые свойства.
  • vf/fps — меняет частоту кадров на выходе.
  • vf/hwupload — загружает кадры в GPU для аппаратной обработки.
  • vf/overlay — накладывает графику на видео.
  • 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. Параметры

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

• Aspect Ratio (enum, по умолчанию 16/9)

  Целевое соотношение дополненного выходного кадра.

  • Что задаёт. Соотношение сторон итогового холста. Источник центрируется, а полосы добавляются на ту пару краёв, которой требует разница.
  • Когда менять. Выбирайте 16/9 для широкоэкранных HD-поставок и 4/3 для устаревших SD- или DV-целей.
  • Допустимые значения. 4/3, 16/9.
  • Обязательно. да.

• Color (enum, по умолчанию Black)

  Цвет заливки полос.

  • Что задаёт. Цвет области, добавляемой вокруг исходного кадра. Поддерживается полная палитра именованных CSS-цветов.
  • Когда менять. Оставляйте Black для обычных вещательных, стриминговых и архивных поставок. Задавайте брендовый цвет для промо-контента, которому нужны цветные полосы пилларбокса под креативную спецификацию.

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

JSON-ключ	Название поля
aspect	Aspect Ratio
color	Color

6. Пример

Полный разбор — переменные, настройка каждого узла и ожидаемый результат — смотрите в AVC-Intra MXF broadcast mezzanine.

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

• AVC-Intra MXF broadcast mezzanine — добавляет полосы леттербокса 16:9 перед кодером AVC-Intra, когда источник выше 16:9.
• MP4 with branded logo overlay — вписывает источник в кадр 16:9 перед композитом логотипа и кодированием H.264.
• DVCPRO 576i SD master — дополняет источник в 4:3-растр SD, которого требует мастер DVCPRO.

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

• Леттербоксинг там, где подошло бы масштабирование. Когда цель — вписать 16:9-источник в 16:9-поставку меньшего растра, используйте vf/scale, а не vf/letterbox. Леттербоксинг помогает только когда соотношения источника и цели различаются.

• Леттербоксинг перед vf/scale в неверном порядке. Добавление полос с последующим масштабированием уменьшает полосы вместе с картинкой и даёт смещённый кадр. Сначала масштабируйте до растра активной картинки, затем леттербоксьте в целевой кадр, затем кодируйте.

• Использование vf/letterbox для обеспечения безопасных зон. Леттербоксинг добавляет полосы, чтобы вписать соотношение; он не защищает безопасную для логотипа или титров зону на исходной картинке. Для работы с безопасными зонами используйте композиционную направляющую выше кодирования (или в монтаже).