How to Use Gstreamer Debug Viewer

What is the GStreamer Debug Viewer

GStreamer Debug Viewer, or gst-debug-viewer, is a GUI tool to ease the process of inspecting and analyzing debug logs produced by GStreamer applications.

Installation

Dependencies

Mac OSX

brew install pygobject3 cmake json-glib

Ubuntu / Debian Based

sudo apt install cmake

Install

GST_VERSION=`gst-launch-1.0 --gst-version | awk -F'[ .]' '{print $5 "." $6}'`
git clone https://github.com/GStreamer/gst-devtools -b $GST_VERSION
cd gst-devtools

## Disable everything except gst-debug-viewer

echo "Your gstreamer version is $GST_VERSION"

# Gst 1.17 and newer
meson build -Dvalidate=disabled -Dgtk_doc=disabled -Dintrospection=disabled -Dtests=disabled -Dnls=disabled
# Gst 1.16 and lower
meson build -Dvalidate=false -Dgtk_doc=disabled -Dintrospection=disabled -Dtests=disabled -Dnls=disabled

# Build and install
ninja -C build
sudo ninja -C build install

Basic Usage

First create a debug trace. For example test.log using the following pipe:

GST_DEBUG_FILE=test.log GST_DEBUG=4 gst-launch-1.0 videotestsrc num-buffers=150 ! queue ! fakesink

Finally just start gst-debug-viewer with the file as the argument.

gst-debug-viewer test.log

Alternatively, you may open the GUI and load the file from there.

Functionality

Main View

1 Overall Timeline: Shows the appearance of debug messages over time. The red translucent box is the current message view. The green plot is the density of the messages.
2 Current View Timeline: Shows the timeline of the debug messages in the current view. The connectors assign each message to it's actual position in time. The connector color shows independent threads.
3 Time Column: Shows the process time at which the message was logged
3.5 Level Column: Shows the message level (ERROR,WARNING,FIXME,INFO,DEBUG,LOG,TRACE)
4 Category Column: Shows the debug message category
5 Code Column: Shows the file and line number where the message was logged
6 Function Column: Shows the function name where the message was logged
7 Object Column: Shows the name of the GstObject that logged the message, if any. (This is why you want to use GST_INFO_OBJECT instead of GST_INFO).
8 Message Column: Shows the actual debug content
9 Message Box: A cleaner view showing only the time and message content.

These are the default columns, you can add (or remove) additional ones by going to

View->Columns

Filters

The power of the viewer comes from the fact that you can easily filter the current view. To do so:

Select a message you are interested
Open the filter menu by either:
1. Right click on the message or
2. Open View

Set base time: Sets the time of this message as 0. Previous messages will have negative times. Useful for checking time differences.
Hide log level: Hides all messages that share the same level as this message
Hide this log level and above: Hides all messages that have the same level or above
Show only log level: Hides messages that have levels different to the one in this message
Hide log category: Hides all messages that share the same category as this message
Show only log category: Hides all messages with different categories as the one in this message
Hide thread: Hide messages logged from the same thread as this message
Show only thread: Hides messages logged from threads different than the one in this message
Hide object: Hides all message that were logged by the same object as this message
Show only object: Hides all messages that were logged by objects different than the one in this messages
Hide function: Hides all messages that were logged from the same function as this message
Show only function: Hides all messages that were logged from a function other than the one in this message
Hide filename: Hides all messages that were logged from the same filename as this message
Show only filename: Hides all messages that were logged from a filename other than the one in this message
Hide lines before this point: Hides messages above this one
Hide lines after this point: Hides messages below this one
Show hidden lines: Reset filters

Searching

Searching is another indispensable feature. You may press CTRL+f to perform search. This remains true for Mac OSX, it is CTRL not CMD.

❯