07-07-03 Частые ошибки: caps, autoplugging, несовместимость форматов

При работе с GStreamer, особенно на начальном этапе, легко попасть на типичные ошибки, которые могут привести к неработающему пайплайну, неожиданной задержке или даже падению приложения. Эти «грабли» возникают не из-за сложности самого медиапотока, а из-за особенностей архитектуры GStreamer — в частности, из-за механизма автоподключения (autoplugging), строгой проверки форматов (caps) и неявного поведения некоторых элементов.

В этом разделе мы подробно разберём четыре самых распространённых ловушки, объясним, почему они возникают, как их распознать и как избежать. Также дадим общую рекомендацию по подходу к построению пайплайнов, чтобы минимизировать риски.

---

1. Элементы не соединяются из-за несовместимых caps

Одна из самых частых проблем — пайплайн не запускается, и в логах появляется сообщение вроде:

ERROR: from element /GstPipeline:pipeline0/GstDecodeBin:decodebin0: 
Could not link video decoder to next element

Или просто: Failed to link elements.

Почему это происходит

GStreamer требует, чтобы формат данных (caps) на выходе одного элемента был совместим с форматом на входе следующего. Если элемент A выдаёт, например, видео в формате I420, а элемент B ожидает NV12, автоподключение не произойдёт — GStreamer не будет автоматически конвертировать формат, даже если знает, как это сделать.

Капабилити (caps) — это строгие объявления формата данных на пэде (pad). Пример:

video/x-raw, format=I420, width=1280, height=720, framerate=30/1

Если между элементами формат не совпадает и нет преобразователя, GStreamer не сможет соединить их.

Как исправить

Решение — вставить преобразователь формата:

• Для видео: videoconvert
• Для аудио: audioconvert

Например, если декодер выдаёт NV12, а синк принимает только I420, добавьте videoconvert:

... ! avdec_h264 ! videoconvert ! autovideosink

videoconvert — это «умный» элемент, который автоматически определит, какую конверсию нужно выполнить, и подключится к нужному цветовому пространству.

Когда ещё нужен capsfilter

Иногда нужно явно задать формат на каком-то этапе. Для этого используется capsfilter. Например, если вы хотите зафиксировать разрешение или FPS:

... ! videoconvert ! video/x-raw,width=640,height=480,framerate=15/1 ! videoscale ! ...

Здесь video/x-raw,... — это caps-строка, передаваемая через capsfilter. Это можно записать коротко как:

... ! videoconvert ! "video/x-raw,width=640,height=480" ! ...

Совет: Если пайплайн не собирается — проверьте, совпадают ли форматы. Добавьте videoconvert/audioconvert перед sink или после декодера. Это почти всегда помогает.

---

2. decodebin выбирает не тот декодер или создаёт несколько веток

decodebin — удобный элемент, который автоматически подбирает подходящий декодер под входной поток. Но именно его «ум» может стать источником проблем.

Что может пойти не так

• decodebin может выбрать аппаратный декодер, если он доступен, даже если вы не планировали его использовать.
• Он может создать несколько веток (pads) — например, отдельно для видео и аудио, или даже для нескольких видеопотоков.
• В сложных случаях decodebin может не подключиться к следующему элементу, потому что не знает, какую ветку выбрать.

Пример проблемы

Допустим, у вас такой пайплайн:

rtspsrc location=rtsp://... ! decodebin ! autovideosink

Но ничего не показывается. Почему?

Потому что decodebin создал два пэда: один для видео, один для аудио. Но autovideosink принимает только видео. Аудио-ветка остаётся "висеть", и GStreamer может не решить, какую ветку использовать.

Как диагностировать

Включите отладку:

GST_DEBUG=3 gst-launch-1.0 rtspsrc location=rtsp://... ! decodebin ! autovideosink

В логах вы увидите что-то вроде:

New pad added: src_0 (video/x-h264)
New pad added: src_1 (audio/x-opus)

Это значит, что decodebin создал две ветки.

Как исправить

Есть два подхода:

1. Явно обрабатывать динамические пэды в коде (Python)

В Python вы можете подключить обработчик сигнала pad-added:

def on_pad_added(element, pad):
    sink_pad = sink.get_static_pad("sink")
    if not sink_pad.is_linked():
        pad.link(sink_pad)

decodebin.connect("pad-added", on_pad_added)

2. В gst-launch — использовать более детализированный пайплайн

Вместо decodebin можно разобрать поток вручную:

rtspsrc location=rtsp://... ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! autovideosink

Этот подход даёт полный контроль над каждым шагом и избегает неопределённости decodebin.

Рекомендация: Используйте decodebin только на начальном этапе тестирования. В продакшн-пайплайнах лучше разбирать поток вручную.

---

3. Неправильное использование queue: либо нет, либо слишком много

queue — один из самых важных, но и самых неправильно используемых элементов в GStreamer.

Что делает queue

• Это буфер между элементами.
• Позволяет разделить потоки на разные потоки выполнения (threads).
• Может накапливать данные, если следующий элемент не успевает.

Две крайности

Проблема 1: Нет queue там, где нужно

Без queue элементы работают в одном потоке. Если один элемент «зависает» (например, декодер), весь пайплайн блокируется.

Пример:

rtspsrc ! decodebin ! videoconvert ! autovideosink

Если декодер начинает тормозить, приём RTP-пакетов тоже замедляется — это может привести к потере кадров.

Решение: Вставьте queue между decodebin и videoconvert:

... ! decodebin ! queue ! videoconvert ! ...

Теперь декодер и отображение могут работать независимо.

Проблема 2: Слишком много queue

Каждый queue — это потенциальный источник задержки. Если вы добавите 5 очередей, каждая из которых хранит по 100 мс видео — задержка вырастет на полсекунды.

Кроме того, очереди потребляют память. Если поток идёт медленно, а данные приходят быстро, очередь будет расти.

Как настроить queue разумно

Используйте параметры:

• max-size-buffers — максимальное число буферов в очереди.
• max-size-time — максимальное время хранения буферов (в наносекундах).
• leaky — куда сбрасывать данные при переполнении:
  • leaky=upstream — сбрасывать входящие буферы (полезно для снижения нагрузки).
  • leaky=downstream — сбрасывать буферы, которые не успели обработать.

Пример low-latency очереди:

queue max-size-buffers=2 max-size-time=0 leaky=downstream

Это означает:

• Хранить не более 2 буферов.
• Не ограничивать по времени.
• Если очередь переполнена — сбрасывать новые буферы (те, что не успели выйти).

Такой подход минимизирует задержку и предотвращает накопление.

---

4. sync=true мешает мониторингу в реальном времени

По умолчанию большинство sink-элементов (например, autovideosink, ximagesink) работают в режиме sync=true. Это значит, что они ждут точного времени отображения кадра (на основе таймстемпа), чтобы сохранить синхронизацию с аудио или другими источниками.

Почему это плохо для мониторинга

Если вы смотрите в прямом эфире за камерой (например, при настройке оборудования), вам нужно минимальное время отклика. Но sync=true заставляет синк ждать, пока "придёт время" показать кадр — даже если он уже готов.

Результат: задержка в 100–300 мс, хотя пайплайн технически способен работать быстрее.

Решение: отключить синхронизацию

Установите sync=false у видеосинка:

... ! autovideosink sync=false

Теперь кадры будут отображаться сразу после обработки, без ожидания.

Когда нельзя отключать sync

• При воспроизведении записанного видео.
• При работе с несколькими синхронизированными источниками (например, мультивью с аудио).
• В продакшн-трансляциях, где важна точная синхронизация.

Рекомендация: Используйте sync=false только для мониторинга в реальном времени. В остальных случаях оставляйте sync=true.

---

Общий подход: от простого к сложному

Чтобы избежать большинства ошибок, следуйте проверенной стратегии:

1. Начните с минимального рабочего пайплайна.
   Например:

   gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink

2. Постепенно добавляйте элементы.
   После каждого шага проверяйте, работает ли пайплайн.

3. Используйте отладку.
   Запускайте с GST_DEBUG=2 или GST_DEBUG=3, чтобы видеть, что происходит.

4. Проверяйте caps.
   Если пайплайн не собирается — вставьте videoconvert и/или capsfilter.

5. Добавляйте queue только при необходимости.
   Не кидайте queue "на всякий случай" — это увеличивает задержку.

6. Избегайте decodebin в сложных сценариях.
   Разбирайте поток вручную, когда важна стабильность.

---

Сводная таблица: типичные ошибки и решения

Проблема	Причина	Решение
Элементы не соединяются	Несовместимые caps	Добавить videoconvert или audioconvert
Пайплайн не запускается с decodebin	Много веток или неправильный выбор декодера	Использовать ручную распаковку или обработать pad-added в коде
Большая задержка	Слишком много queue или max-size-time слишком большое	Ограничить размер очереди, использовать leaky=downstream
Видео "тормозит" при мониторинге	sync=true у синка	Установить sync=false
Растёт потребление памяти	Очереди переполняются	Настроить max-size-buffers и leaky

---

Заключение

Ошибки в GStreamer — не признак сложности фреймворка, а скорее следствие его гибкости. Понимание механизмов caps, autoplugging, queue и синхронизации позволяет не просто исправлять проблемы, но и строить предсказуемые, стабильные и низколатентные пайплайны.

Главное правило: не бойтесь экспериментировать, но делайте это пошагово. Каждый пайплайн — это результат итераций, а не магическая строка.