Gstreamer: Tips and Tricks for Effective Debugging

Sometimes things won’t go as expected and the error messages retrieved from the bus (if any) just don’t provide enough information. Luckily, GStreamer ships with massive amounts of debug information, which usually hint what the problem might be.

How to print the debug log

Gstreamer provides the GST_DEBUG environment variable, which is used to set the log level, and based on that, it will display the messages. We will understand what the values are and how they behave.

1. GST_DEBUG=0 (none -- No debug information is output. )
2. GST_DEBUG=1 (ERROR -- Logs all fatal errors.)
3. GST_DEBUG=2 (WARNING -- Logs all warnings.)
4. GST_DEBUG=3 (FIXME -- Logs all "fixme" messages.)
5. GST_DEBUG=4 (INFO -- Logs all informational messages.)
6. GST_DEBUG=5 (DEBUG -- Logs all debug messages.)
7. GST_DEBUG=6 (LOG -- Logs all log messages)
8. GST_DEBUG=7 (TRACE -- Logs all trace messages.)
9. GST_DEBUG=8 (MEMDUMP -- Logs all memory dump messages.)

GST_DEBUG in more detail analysis

Let say, I have this pipeline like below

gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=640,height=480 ! videoconvert ! autovideosink        

Adding your own debug information

User can use following defined gstreamer logging functions macros

1. GST_ERROR()
2. GST_WARNING()
3. GST_INFO()
4. GST_LOG()
5. GST_DEBUG()

above, Function macros can be use similar as printf() in C and they use the default category. To change the category to something more meaningful, add these two lines at the top of your code:

And then this one after you have initialized GStreamer with gst_init():

This registers a new category (this is, for the duration of your application: it is not stored in any file), and sets it as the default category for your code. See the documentation for GST_DEBUG_CATEGORY_INIT().

Generate a graph to debug the Gstreamer pipeline

For those cases where your pipeline starts to grow too large and you lose track of what is connected with what, GStreamer has the capability to output graph files. These are .dot files, readable with free programs like GraphViz, that describe the topology of your pipeline, along with the caps negotiated in each link.

Steps to generate graph:

# create a file pipeline.dot which may contain below content
$ cat pipeline.dot
GST_DEBUG_DUMP_DOT_DIR=./
GST_DEBUG_DUMP_DOT_FORMAT=png
GST_DEBUG_DUMP_DOT_NO_STATE_CHANGE=1
GST_DEBUG=dots:7

# Run the streaming Pipeline which you want to generate graphs (for example)
$ GST_DEBUG_DUMP_DOT_DIR=. gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! fbdevsink

# Check *.dot file created or not like below
$ ls
0.00.00.126758112-gst-launch.NULL_READY.dot    
0.00.00.541197514-gst-launch.PAUSED_PLAYING.dot  
0.00.02.547670185-gst-launch.PAUSED_READY.dot
0.00.00.129257976-gst-launch.READY_PAUSED.dot  
0.00.02.543631848-gst-launch.PLAYING_PAUSED.dot

# Convert these DOT files to png to view the graphs
$ dot -Tpng 0.00.00.126758112-gst-launch.NULL_READY.dot -o 0.00.00.126758112-gst-launch.NULL_READY.png
$ dot -Tpng 0.00.00.129257976-gst-launch.READY_PAUSED.dot -o 0.00.00.129257976-gst-launch.READY_PAUSED.png
$ dot -Tpng 0.00.00.541197514-gst-launch.PAUSED_PLAYING.dot -o 0.00.00.541197514-gst-launch.PAUSED_PLAYING.png
$ dot -Tpng 0.00.02.543631848-gst-launch.PLAYING_PAUSED.dot -o 0.00.02.543631848-gst-launch.PLAYING_PAUSED.png
$ dot -Tpng 0.00.02.547670185-gst-launch.PAUSED_READY.dot -o 0.00.02.547670185-gst-launch.PAUSED_READY.png

$ ls
0.00.00.126758112-gst-launch.NULL_READY.png 
0.00.00.541197514-gst-launch.PAUSED_PLAYING.png  
0.00.02.547670185-gst-launch.PAUSED_READY.png
0.00.00.129257976-gst-launch.READY_PAUSED.png 
0.00.02.543631848-gst-launch.PLAYING_PAUSED.png        

As I have used the below Gstreamer pipeline, check the pipeline graphs for all the details related to this that have been displayed.

Pipeline: gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! fbdevsink

Graph:

This article shows (1) how to get more debug information from GStreamer using the GST_DEBUG environment variable. (2) How to print your own debug information into the GStreamer log with the GST_ERROR() macro and relatives. (3) How to get pipeline graphs with the GST_DEBUG_DUMP_DOT_DIR environment variable. I hope this will help while working with gstreamer command line pipelines. Stay tuned for custom app development based on gstreamer.