Recent evolutions in the GPAC log system

Introduction

A log is a way of keeping record of what’s happening when executing a software. The GPAC framework has log capabilities in order for you to see what’s going on when packaging (MP4Box), or playing (MP4Client, Osmo4) your favorite multimedia content!

The GPAC log system has been deeply modified these days, starting at SVN revision 3463. This article explains the features embedded in the new system and how to use it.

Overview

The GPAC log system is based on two orthogonal concepts:

  • tools: the theme of the log you want to listen to. For instance when playing a MPEG-TS file, you may want to hear about the container log; when player remote content, you may want to hear about the network log; when trying to find a deadlock (but there are obviously none in GPAC ;), you may want to hear about the mutex log. The complete list is provided below, in an appropriate section.
  • levels: the deepness of the log. You have to choose whether you want to know about errors only, or about any thing the developer thought right to signal for fellow developers.
/!\ In GPAC, you can choose which tools you want to hear, and for each tool you can set a level.

The general syntax is:

Concrete examples are given further in this article.

Available Tools

Available Levels

/!\ Note that these levels apply to GPAC, not to the content being processed. For instance GF_LOG_ERROR is intended to signal GPAC has encountered a serious error. On the contrary, if you read an MPEG-TS files containing some errors that are correctly handled by GPAC, you should use the GF_LOG_WARNING channel.

Setting the log

This section explains to the GPAC users the features of the default log implementation within the tools. If you’re a developper you may also want to read the next section.

Default values

The default GPAC implementation sets all the messages on, to the “warning” level. The only exception is the GF_LOG_CONSOLE being set to “info” so that messages output by the user can be seen (for example you asked to write a message from your script to help you debug it).

Setting tools and levels on MP4Client

MP4Client is the console-mode player of GPAC. Here is a screenshot of MP4Client executing with default logs:

In this example GPAC says a PID from the MPEG2-TS stream is not supported (and therefore won’t be decoded).

MP4Client features several options related to logging:

Here is an example, which sets all messages to the warning level (default level for all tools) except core, audio and mem that are set to the debug level, and container and sync that are set to the error level:

Other log options are:

Choosing an output channel

By default GPAC outputs its logs to stdout. However as you can see in the latest example from the previous section, MP4Client features a “-log-file” option:

This behaviour depends on the application. It’s up to you to implement this in your tools…

How to use the log

This section gives some hints to the GPAC developers about ways to customize their log system.

Calling the log

When you need to print a log message, call the GF_LOG macro as follows:

Where:

  • GF_LOG_LEVEL belongs to the level list above (GF_LOG_QUIET, …, GF_LOG_DEBUG)
  • GF_LOG_TOOL belongs to the tool list above (GF_LOG_CORE, …, GF_LOG_CONSOLE)
  • (MESSAGE): a message contained between parentheses and with the same formatting as printf.

For example:

Implementation details

The code lies within the src/utils/error.c source file.

The log system used in the GPAC open-source framework outputs to stdout.

Exported functions are:

Customizing your log

You simply need to call gf_log_set_callback() with your own log function. The type of the function is given as below:

 

 

3 thoughts on “Recent evolutions in the GPAC log system

  1. I am getting an error when trying to create DASH content:

    MP4Box: symbol lookup error: MP4Box: undefined symbol: gf_log_set_tool_level
    terminate called after throwing an instance of ‘std::out_of_range’
    what(): basic_string::substr
    Error: Unable to open MPD file!Aborted (core dumped)

    The line: “MP4Box: symbol lookup error: MP4Box: undefined symbol: gf_log_set_tool_level” pops up a few times until it eventually falls over. Is this the cause of my problem?

Comments are closed.