22 February 2018 by Phillip Johnston • Last updated 15 December 2021

I’ve been working with GStreamer quite a bit recently. I often find it difficult to visualize the pipelines I’m working with, especially for complex pipelines involving multiple video streams. I’ve been manually creating my own pipeline graphs to keep the details straight. However, maintaining these graphs is time consuming and error-prone.

Recently I discovered that GStreamer has a debugging feature that automatically generates pipeline graphs. The generated graphs are not as beautiful as my painstakingly-created custom graphs, but automatic and instantaneous graph generation wins every time. I also discovered that the GStreamer pipeline graphs reveal hidden elements that are created under the hood, giving me a more comprehensive view of the pipelines I’m working with.

Table of Contents:

1. Dependencies
2. Generating GStreamer Pipeline Graphs
   1. GStreamer Application Macros
3. Converting Pipeline dot Files to PDF
   1. Bulk Conversion Script
4. An Example Pipeline
5. Further Reading

Dependencies

Before we can get started, we’ll need to cover our dependency situation. I’m assuming you already have GStreamer installed on your system (otherwise this guide is of no use to you).

The only dependency we’ll need to install is Graphviz. GStreamer will generate .dot files for our pipeline, and we’ll use Graphviz to convert those .dot files into an image or PDF.

If you’re on Linux, simply run:

sudo apt-get install graphviz

If you’re using OSX, you can install Graphviz using brew:

brew install graphviz

One point to note: the program that is installed with the Graphviz package is called dot, not graphviz.

Generating GStreamer Pipeline Graphs

Regardless of whether you’re using gst-launch-1.0 or a GStreamer application, the first thing we’ll need to do is define the GST_DEBUG_DUMP_DOT_DIR environment variable. GStreamer uses this environment variable as the output location for the generated pipeline graphs.

You can either define this globally with export:

export GST_DEBUG_DUMP_DOT_DIR=build/pipeline/

Or you can also define it during the application invocation:

GST_DEBUG_DUMP_DOT_DIR=/tmp gst-launch-1.0 {…}

GST_DEBUG_DUMP_DOT_DIR=/tmp ./custom_application

If the directory does not exist, GStreamer will not create it. You’ll need to do that on your own.

If you’re using gst-launch-1.0, that’s all you need to do – pipeline graphs will be generated during every state change.

GStreamer Application Macros

If you’re using a custom GStreamer application, you’ll need to use GStreamer debug macros to trigger pipeline generation.

For instance, to see a complete pipeline graph, add the following macro invocation at the point in your application where your pipeline elements have been created and linked:

GST_DEBUG_BIN_TO_DOT_FILE(pipeline, GST_DEBUG_GRAPH_SHOW_ALL, "pipeline")

You can use the GST_DEBUG_BIN_TO_DOT_FILE() and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS() macros to trigger pipeline graph output at desired points.

Pipeline Graph Output

If you’re using gst-launch-1.0, a new pipeline graph will be generated on each pipeline state change. This can be especially helpful if you want to see how your pipeline evolves during caps negotiation.

Here’s a list of files that were generated by gst-launch-1.0 using the example pipeline:

0.00.00.328088000-gst-launch.NULL_READY.dot
0.00.00.330350000-gst-launch.READY_PAUSED.dot
0.00.02.007860000-gst-launch.PAUSED_PLAYING.dot
0.00.05.095596000-gst-launch.PLAYING_PAUSED.dot
0.00.05.104625000-gst-launch.PAUSED_READY.dot

If you are using a custom GStreamer app, pipeline files will only be triggered based on your invocation of the GST_DEBUG_BIN_TO_DOT_FILE() macros. Perhaps a single pipeline graph will be generated if you follow the recommendation above. Multiple graphs will only be generated if you invoke the macro multiple times.

Converting Pipeline dot Files to PDF

Now that we have the generated pipeline graphs, we need to convert them to a graphical format.

We’ll use the dot command like this, and the general form will be:

dot -T{format} input_file > output_file

I like to use PDFs for my pipeline graphs, as I can actually zoom in and read the text without artifacts. To convert our pipeline graphs to PDF files, I use the following command:

dot -Tpdf 0.00.05.104625000-gst-launch.PAUSED_READY.dot > pipeline_PAUSED_READY.pdf

Graphviz supports a variety of output types, so don’t feel constrained to a PDF! Select the type that works best for you.

Bulk Conversion Script

Since I often use gst-launch-1.0 for pipeline testing, I want to convert pipeline graphs in bulk. Here’s a script that I use to convert all pipeline files in a directory:

#!/bin/sh

MESON_BUILD_ROOT="${MESON_BUILD_ROOT:-build}"
INPUT_DIR="${INPUT_DIR:-$MESON_BUILD_ROOT/pipeline}"

if [ -d "$INPUT_DIR" ]; then
    DOT_FILES=`find build/pipeline -name "*.dot"`
    for file in $DOT_FILES
    do
        dest=`sed s/.dot/.pdf/ <<< "$file"`
        dot -Tpdf $file > $dest
    done
else
    echo "Input directory $INPUT_DIR does not exist"
fi

You can eliminate MESON_BUILD_ROOT in your own script and supply your own INPUT_DIR. If you prefer a different file type, simply change the -Tpdf argument and the .pdf portion of the sed command.

An Example Pipeline

Here’s an example GStreamer pipeline and a resulting pipeline graph.

I use the pipeline below to test changes to the framerate plugin that I am working on. In order to generate pipeline graphs, I added GST_DEBUG_DUMP_DOT_DIR to the gst-launch-1.0 invocation:

GST_DEBUG_DUMP_DOT_DIR=$MESON_BUILD_ROOT/pipeline gst-launch-1.0 -e --gst-plugin-path=$MESON_BUILD_ROOT \
    videotestsrc is-live=1 \
    ! 'video/x-raw, format=(string)I420, framerate=(fraction)15/1, width=(int)480, height=(int)360' \
    ! framerate passthrough = 1\
    ! 'video/x-raw, framerate=(fraction)30/1' \
    ! x264enc \
    ! 'video/x-h264, stream-format=(string)byte-stream' \
    ! h264parse \
    ! matroskamux \
    ! filesink location=$MESON_BUILD_ROOT/test.mkv

GStreamer produces five pipeline graphs for this plugin, covering the five state changes:

0.00.00.328088000-gst-launch.NULL_READY.dot
0.00.00.330350000-gst-launch.READY_PAUSED.dot
0.00.02.007860000-gst-launch.PAUSED_PLAYING.dot
0.00.05.095596000-gst-launch.PLAYING_PAUSED.dot
0.00.05.104625000-gst-launch.PAUSED_READY.dot

Here’s our rendered PAUSED_READY.dot pipeline: 

Further Reading

• GStreamer Debugging Tools
• GST_DEBUG_BIN_TO_DOT_FILE
• GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS
• GStreamer
• Graphviz
• Graphviz Output Formats
• Dot Language