07-07-04 Инструменты отладки: `GST_DEBUG`, `gst-inspect`, графы пайплайнов

На этапе создания и настройки GStreamer-пайплайнов — особенно сложных, с несколькими источниками, преобразованиями и приёмниками — рано или поздно возникают ситуации, когда пайплайн не запускается, падает с ошибкой, или работает не так, как ожидается. В таких случаях невозможно полагаться только на интуицию или пробные запуски. Нужны инструменты диагностики, которые помогут понять, что происходит «под капотом».

В этом разделе мы рассмотрим три ключевых инструмента, которые входят в стандартную поставку GStreamer и доступны из командной строки:

GST_DEBUG — включение подробного логирования;
gst-inspect-1.0 — изучение структуры элементов;
Генерация графа пайплайна в формате DOT — визуализация структуры.

Эти инструменты критически важны при разработке продакшн-решений, но даже на уровне учебного курса они помогают быстрее понять, как работает gst-launch-1.0, почему элементы не соединяются, или откуда берётся задержка.

Включение логов с помощью `GST_DEBUG`

Когда пайплайн не запускается или работает нестабильно, первое, что нужно сделать — посмотреть, что происходит внутри. GStreamer предоставляет мощную систему отладочного вывода, активируемую через переменную окружения GST_DEBUG.

Как это работает

Переменная GST_DEBUG позволяет указать:

уровень детализации логов (от 0 до 6);
какие элементы или категории логов показывать.

Наиболее часто используется синтаксис:

GST_DEBUG=уровень команда

или более точно:

GST_DEBUG=имя_элемента:уровень команда

Уровни отладки

Уровень	Имя	Описание
0	ERROR	Только критические ошибки
1	WARNING	Предупреждения (например, проблемы с синхронизацией)
2	FIXME	Места, где что-то работает, но потенциально неправильно
3	INFO	Общая информация о создании элементов, состояниях
4	DEBUG	Подробные данные о работе пайплайна
5	LOG	Очень подробные логи (например, каждый буфер)
6	TRACE	Максимальная детализация (включая вызовы функций)

Пример использования

Допустим, вы запускаете пайплайн для RTSP-камеры, и он «зависает» или не показывает видео:

gst-launch-1.0 rtspsrc location=rtsp://192.168.1.100:554/stream ! decodebin ! videoconvert ! autovideosink

Чтобы понять, где проблема, включите отладку:

GST_DEBUG=3 gst-launch-1.0 rtspsrc location=rtsp://192.168.1.100:554/stream ! decodebin ! videoconvert ! autovideosink

На экране появится множество сообщений, например:

0:00:00.123456789 INFO                rtspsrc gstrtspsrc.c:1234:gst_rtspsrc_open: opening connection to rtsp://192.168.1.100:554/stream
0:00:00.123456789 INFO                rtspsrc gstrtspsrc.c:2345:gst_rtspsrc_send_cmd: sending DESCRIBE request

Эти строки покажут:

Удалось ли установить RTSP-соединение;
Получен ли SDP-описание потока;
Какие RTP-потоки обнаружены;
Как decodebin пытается подобрать декодер.

Полезные практики

Начинайте с GST_DEBUG=3 — этого обычно достаточно для диагностики большинства проблем.
Если нужно сузить фокус, используйте:
GST_DEBUG=rtspsrc:5,decodebin:4 gst-launch-... — только для конкретных элементов.
В сложных случаях можно направить логи в файл:
GST_DEBUG=3 gst-launch-1.0 ... 2> debug.log

Изучение элементов с помощью `gst-inspect-1.0`

Иногда вы видите элемент в пайплайне (например, videorate или capsfilter), но не знаете, какие у него есть свойства, входы/выходы или какие форматы он поддерживает. В таких случаях на помощь приходит утилита gst-inspect-1.0.

Что делает `gst-inspect-1.0`

Эта команда выводит полную информацию об элементе:

Назначение и краткое описание;
Доступные свойства (properties);
Пэды (pad'ы): входы (sink) и выходы (src);
Поддерживаемые caps (форматы);
Примеры использования.

Синтаксис

gst-inspect-1.0 имя_элемента

Пример: изучение `rtspsrc`

Выполним:

gst-inspect-1.0 rtspsrc

В выводе увидим:

Factory Details:
  Rank                     primary (256)
  Long-name                RTSP source
  Class                    Source/Network
  Description              Receive data as an RTSP client
  Author                   Wim Taymans <wim.taymans@gmail.com>

...

Ключевые разделы:

1. Свойства (Properties):

  latency           : Amount of ms to buffer (0 = no buffering, -1 = default)
                      flags: readable, writable
                      Integer. Range: -1 - 2147483647 Default: 2000

  location          : The RTSP URI to connect to
                      flags: readable, writable
                      String. Default: null

Здесь мы видим, что latency по умолчанию — 2000 мс, что объясняет, почему без указания latency=0 пайплайн может иметь большую задержку.

2. Пэды (Pad Templates):

  SRC template: src_%u
    Availability: Sometimes
    Capabilities:
      application/x-rtp
        media: video
        clock-rate: [ 1, 2147483647 ]
        encoding-name: (string)H264

Это означает, что rtspsrc создаёт динамические выходные пэды (src_0, src_1 и т.д.) для каждого RTP-потока, и каждый из них передаёт данные в формате application/x-rtp с видео H.264.

3. Примеры использования

В конце часто приводятся готовые строки gst-launch, например:

gst-launch-1.0 rtspsrc location=rtsp://example.com/stream ! rtpjitterbuffer ! rtpmp4gdepay ! aacparse ! avdec_aac ! audioconvert ! autoaudiosink

Это полезно для быстрого старта.

Визуализация пайплайна: генерация графа в DOT

Одна из самых мощных возможностей GStreamer — автоматическая генерация графа пайплайна в формате DOT (язык описания графов от Graphviz). Это особенно полезно, когда пайплайн сложный, содержит decodebin, compositor, или несколько веток.

Как это работает

GStreamer может автоматически создавать .dot-файлы, описывающие структуру пайплайна на каждом этапе его жизни: при создании, переходе в PAUSED, PLAYING и т.д.

Для этого используется переменная окружения:

GST_DEBUG_DUMP_DOT_DIR=/путь/к/папке

Пошаговая инструкция

Создайте папку для графов:

mkdir ~/gst-graphs

Установите переменную и запустите пайплайн:

GST_DEBUG_DUMP_DOT_DIR=~/gst-graphs gst-launch-1.0 rtspsrc location=rtsp://... ! decodebin ! videoconvert ! autovideosink

После запуска в папке ~/gst-graphs появятся файлы вида:

gst-dot.12345.PRE_LINK.dot
gst-dot.12345.POST_LINK.dot
gst-dot.12345.PRE_PLAYING.dot

Каждый файл соответствует определённому этапу:

PRE_LINK — до соединения элементов;
POST_LINK — после соединения, но до запуска;
PRE_PLAYING — перед переходом в состояние PLAYING.

Просмотр графа

Для визуализации .dot-файлов нужен Graphviz. Установите его:

sudo apt install graphviz

Затем преобразуйте файл в изображение:

dot -Tpng ~/gst-graphs/0.gst-dot.12345.POST_LINK.dot -o pipeline.png

Откройте pipeline.png — вы увидите наглядную схему вашего пайплайна.

Что можно увидеть на графе

Как decodebin развернулся в цепочку: h264parse → avdec_h264;
Где вставлены автоматические конвертеры (videoconvert);
Как соединены пэды;
Наличие скрытых queue, добавленных автоподбором;
Несколько веток (например, если есть аудио и видео).

Пример: диагностика автоподбора

Допустим, вы ожидаете, что видео будет идти напрямую, но на графе видите:

rtspsrc → rtph264depay → h264parse → queue → avdec_h264 → videoconvert → autovideosink

Вы не добавляли queue, но он есть. Это значит, что GStreamer вставил его автоматически — например, для многопоточности. Теперь вы понимаете, что эта очередь может добавлять задержку, и при необходимости можете управлять её параметрами:

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

Сводная таблица инструментов отладки

Инструмент	Команда / переменная	Когда использовать	Что даёт
`GST_DEBUG`	`GST_DEBUG=3`	Пайплайн не запускается, падает, зависает	Подробные логи по этапам инициализации, ошибки, предупреждения
`gst-inspect-1.0`	`gst-inspect-1.0 element`	Не знаете, как использовать элемент, какие у него свойства	Полная документация по элементу: пэды, caps, свойства, примеры
DOT-графы	`GST_DEBUG_DUMP_DOT_DIR=...`	Пайплайн сложный, неясно, как соединяются элементы, есть задержка	Визуальное представление структуры, включая автосозданные элементы и очереди

Заключение: почему эти инструменты важны

На первый взгляд, gst-launch-1.0 — это просто строка из элементов, соединённых восклицательными знаками. Но на самом деле за этой строкой скрывается сложный граф, динамически создаваемые элементы, автоподбор кодеков и буферизация на каждом этапе.

Инструменты отладки позволяют:

Превратить «чёрный ящик» в прозрачную систему;
Понять, почему пайплайн ведёт себя так, а не иначе;
Найти «узкие места» по задержке (например, лишние очереди);
Убедиться, что используется нужный декодер или формат;
Эффективно учиться и экспериментировать.

Даже простой вызов GST_DEBUG=3 или gst-inspect-1.0 может сэкономить часы на догадки. А визуализация графа — это не просто «красиво», а необходимый инструмент проектирования сложных медиапотоков.

Поэтому рекомендуется использовать эти инструменты с самого начала, даже в учебных примерах. Это формирует правильное понимание архитектуры GStreamer и помогает избегать типичных ошибок на более поздних этапах.

Включение логов с помощью GST_DEBUG​

Как это работает​

Уровни отладки​

Пример использования​

Полезные практики​

Изучение элементов с помощью gst-inspect-1.0​

Что делает gst-inspect-1.0​

Синтаксис​

Пример: изучение rtspsrc​

Ключевые разделы:​

Визуализация пайплайна: генерация графа в DOT​

Как это работает​

Пошаговая инструкция​

Просмотр графа​

Что можно увидеть на графе​

Пример: диагностика автоподбора​

Сводная таблица инструментов отладки​

Заключение: почему эти инструменты важны​

Включение логов с помощью `GST_DEBUG`

Как это работает

Уровни отладки

Пример использования

Полезные практики

Изучение элементов с помощью `gst-inspect-1.0`

Что делает `gst-inspect-1.0`

Синтаксис

Пример: изучение `rtspsrc`

Ключевые разделы:

Визуализация пайплайна: генерация графа в DOT

Как это работает

Пошаговая инструкция

Просмотр графа

Что можно увидеть на графе

Пример: диагностика автоподбора

Сводная таблица инструментов отладки

Заключение: почему эти инструменты важны