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:

-logs log_args: sets log tools and levels, formatted as a
                ':'-separated list of toolX[:toolZ]@levelX

Concrete examples are given further in this article.

Available Tools

GF_LOG_CORE      (core)     : log message from the core library
                              (init, threads, network calls, etc)
GF_LOG_CODING    (coding)   : log message from a raw media parser
                              (BIFS, LASeR, A/V formats)
GF_LOG_CONTAINER (container): log message from a bitstream parser
                              (IsoMedia, MPEG-2 TS, OGG, ...)
GF_LOG_NETWORK   (network)  : log message from the network/service
                              stack (messages & co)
GF_LOG_RTP       (rtp)      : log message from the RTP/RTCP stack
                              (TS info) and packet structure & hinting (debug)
GF_LOG_AUTHOR    (author)   : log message from authoring subsystem
                              (file manip, import/export)
GF_LOG_SYNC      (sync)     : log message from the sync layer of
                              the terminal
GF_LOG_CODEC     (codec)    : log message from a codec
GF_LOG_PARSER    (parser)   : log message from any XML parser
                              (context loading, etc)
GF_LOG_MEDIA     (media)    : log message from the terminal/compositor,
                              indicating media object state
GF_LOG_SCENE     (scene)    : log message from the scene graph/
                              scene_manager (handling of nodes and
                              attribute modif, DOM core)
GF_LOG_SCRIPT    (script)   : log message from the scripting engine
                              APIs - does not cover alert() in the
                              script code itself
GF_LOG_INTERACT  (interact) : log message from event handling
GF_LOG_COMPOSE   (compose)  : log message from compositor
GF_LOG_CACHE     (cache)    : log for video object cache
GF_LOG_MMIO      (mmio)     : log message from multimedia I/O devices
                              (audio/video input/output, ...)
GF_LOG_RTI       (rti)      : log for runtime info (times, memory,
                              CPU usage)
GF_LOG_SMIL      (smil)     : log for SMIL timing and animation
GF_LOG_MEMORY    (mem)      : log for memory tracker
GF_LOG_AUDIO     (audio)    : log for audio compositor
GF_LOG_MODULE    (module)   : generic Log for modules
GF_LOG_MUTEX     (mutex)    : log for threads and mutexes
GF_LOG_CONSOLE   (console)  : log for all messages coming from
                              GF_Terminal or script alert()

GF_LOG_ALL       (all)      : all previously listed logs

Available Levels

GF_LOG_QUIET   (quiet)  : disable all Log message
GF_LOG_ERROR   (error)  : log message describes an error
GF_LOG_WARNING (warning): log message describes a warning
GF_LOG_INFO    (info)   : log message is informational (state, etc..)
GF_LOG_DEBUG   (debug)  : log message is a debug info

/!\ 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:

-logs log_args: sets log tools and levels, formatted as a
                ':'-separated list of toolX[:toolZ]@levelX

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:

      -logs core:audio:mem@debug:container:sync@error

Other log options are:

-strict-error:  exit when the player reports its first error

-log-file file: sets output log file. Also works with -lf

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:

-log-file file: sets output log file. Also works with -lf

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:

GF_LOG(GF_LOG_LEVEL, GF_LOG_TOOL, (MESSAGE));

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:

GF_LOG(GF_LOG_INFO, GF_LOG_CONSOLE, ("%s %s\n", servName,
                                         evt->message.message));

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:

/*log exits at first error assignment*/
void gf_log_set_strict_error(Bool strict);

/*gets string-formated log tools*/
char *gf_log_get_tools_levels();

/*log modules assignment*/
void gf_log_set_tool_level(u32 tool, u32 level);

/*assigns a user-defined callback for printing log messages*/
gf_log_cbk gf_log_set_callback(void *usr_cbk, gf_log_cbk cbk);

/*checks if a given tool is logged for the given level*/
Bool gf_log_tool_level_on(u32 log_tool, u32 log_level);

/*set log tools and levels according to the log_tools_levels string*/
GF_Err gf_log_set_tools_levels(const char *log_tools_levels);

/*modify log tools and levels*/
GF_Err gf_log_modify_tools_levels(const char *val);

/*set log level for a given tool*/
void gf_log_set_tool_level(u32 tool, u32 level);

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:

typedef void (*gf_log_cbk)(void *cbck, u32 log_level, u32 log_tool,
              const char* fmt, va_list vlist);