Category Archives: Features

MP4 demuxer examples

⚠ The content of this page may be outdated.
Please refer to this page for more up to date information: https://github.com/gpac/gpac/wiki/MP4-demuxer-examples

 

Dear followers,

At the request of some people, we have added to GPAC some sample applications demonstrating how to use GPAC to demux MP4 files. They are not full applications, just examples taking some MP4 files as input and displaying some information about the media samples contained in the file.

So far, we have added 3 sample applications:

  • a basic demuxer called ‘bmp4demux’ capable of reading and dispatching media access units from fragmented or non-fragmented MP4 files, progressively (i.e. while the file is being written);
  • a segment based demux called ‘segmp4demuxer‘ capable of dispatching media units from media segments, where the input data is framed.  This is what is used for the DASH support;
  • and a more advanced demuxer, called ‘fmp4demux’ capable of dispatching media units in streaming mode (i.e. reclaiming resources once media units have been dispatched), where the input data comes from fragmented mp4 but is not framed, i.e. the data in the buffer passed to the demuxer does not start or end at segment or fragment boundaries.

Continue reading MP4 demuxer examples

Deferred rendering in GPAC

⚠ The content of this page may be outdated.
Please refer to this page for more up to date information: https://github.com/gpac/gpac/wiki/Deferred-rendering-in-GPAC

 

Since revision 2028 of the source code, the GPAC player can render content in a special mode called “defer-debug”. In this mode, only the rectangular regions of the window that have changed since the previous frame are drawn in each frame. To enable this mode, you need to modify the GPAC configuration file (i.e. GPAC.cfg or .gpacrc), by setting the DrawMode to “defer-debug” in the Compositor section. Continue reading Deferred rendering in GPAC

DASH Streaming Support

NOTE: This post is not the most up-to-date documentation of DASH support in GPAC. For the latest information on DASH, check out these pages:

We have been updating the support for DASH Streaming (ISO/IEC 23009-1) in GPAC as of revision 3849. The update covers both content generation tools and player, and both DASH and HLS support.

For more details on what is DASH and HTTP streaming, please refer to this post. Continue reading DASH Streaming Support

Recent evolutions in the GPAC log system

⚠ The content of this page may be outdated.
Please refer to this page for more up to date information: https://github.com/gpac/gpac/wiki/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:

-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);

 

 

Some fun with multiview rendering on 3D screens

⚠ The content of this page may be outdated.
Please refer to this page for more up to date information: https://github.com/gpac/gpac/wiki/Some-fun-with-multiview-rendering-on-3D-screens

 

 

In the past months I have played with multi-views auto-stereoscopic display, and thought that it could be a nice feature for GPAC. This is still an on-going work, but results are already interesting. GPAC can now support various output type and view number, but requires OpenGL to do so.

Warning, multi-view rendering is a costly operation. The scene gets rendered multiple times, and you will need a decent graphic card to try that, especially support for VBOs to avoid sending the geometry data repeatedly, and OpenGL shaders for most screen configurations.

The output type is selected in GPAC configuration file by the following keys

[Compositor]
NumViews=2
ReverseViews=no
StereoType=None
InterleaverShader=/path/to/fragmentshader_sourcecode.glsl
ViewDistance=180
CameraLayout=Circular

NumViews specify the number of target views. It may be ignored depending on the stereo output type. ReverseViews instruct GPAC to inverse the views, e.g. ViewX becomes NumViews-ViewX.

StereoType can be one of the follwing:

  • None: regular single-view display
  • SideBySide: views are rendered side-by-side, from left to right
  • TopToBottom: views are rendered top-to-bottom, starting with the left
  • Anaglyph (*): views are rendered as anaglyph. Number of views in this mode is forced to 2.
  • Columns (*): views are rendered interleaved columns by columns. Number of views in this mode is forced to 2. Left view is mapped to even pixel X coordinate on the display window/screen.
  • Rows (*): views are rendered interleaved rows by rows by. Number of views in this mode is forced to 2. Left view is mapped to even pixel Y coordinate on the display window/screen.
  • Custom (*): views are rendered by the GLSL fragment shader source code specified by the InterleaverShader option.

(*): Requires OpenGL GLSL shader support.

 

When shaders are used, each view X in [1, NumViews] is exposed to the shader as:

 uniform sampler2D gfViewX

For example, the column interleaving in GPAC is done with a built-in shader whose code is:

uniform sampler2D gfView1;
uniform sampler2D gfView2;

void main(void) {
 if ( int( mod(gl_FragCoord.x, 2.0) ) == 0)
  gl_FragColor = texture2D(gfView1, gl_TexCoord[0].st);
 else
  gl_FragColor = texture2D(gfView2, gl_TexCoord[0].st);
}

CameraLayout defines how the camera is positioned in the 3D world. It can take the value OffAxis (default), Circular or Linear – you can get pretty good overviews of this on the web. ViewDistance specifies the nominal viewing distance of the autostereo display. GPAC will use that to compute each view’s camera position in the virtual world. I have started some experiments on automatic calibration of 3D models, but it is not yet fully tested and may results in too high disparity. Don’t worry, this can be adjusted at run-time: in MP4Client, use Alt+shift+UP/Down to modify the inter-occular distance (by default 6.8 cm)  and Alt+shift+UP/Down to modify the view distance.

 

Here are some videos showing some of these modes.

[youtube]http://www.youtube.com/watch?v=_8sZc3dL9ds[/youtube]

Original scene designed during the Triscope project, in which we built an auto-stereoscopic mobile prototype.

[youtube]http://www.youtube.com/watch?v=7bNHkuFBg0c[/youtube]

Anaglyph version of the Triscope demo.

[youtube]http://www.youtube.com/watch?v=6kzK54XiRXw[/youtube]

Side-by-Side version of the Triscope Demo.

Triscope Demo 5 views interleaved

Custom interleaving version of the Triscope Demo for a 5 views display.

The demo is written in BIFS, and uses a hardcoded proto (e.g. gpac-specific) node called DepthGroup for the 2D menu. This node allows to specify depth translation and scaling factors to a subtree, which are then cumulated when going down the subtree. We could also have used Transform3D nodes, but we didn’t want to have too many 3D matrices to handle (the original prototype platform was not that powerfull). To declare such a node in a BT file, you need to insert the following code before your scene:

EXTERNPROTO DepthGroup [
exposedField MFNode children []
exposedField SFInt32 _3d_type 4
exposedField SFFloat depth_gain 1.0
exposedField SFFloat depth_offset 0.0
 ] "urn:inet:gpac:builtin:DepthGroup"

You can ignore the _3d_type field, which was specific to the hardware part of the prototype.

The resulting depth value is scaled by a constant defined in GPAC configuration file:

[Compositor]
DepthScale=100

This is still very preliminary work, automatic scaling is planed in the near future.

Support for SVG and depth has also been investigated, but this work is not yet integrated in GPAC.

For images, we defined a new image format called PNGD. These are regular PNG files where the alpha channel is interpreted as the depth map of the RGB channels. These files can be played by GPAC whether in stereo-mode or not.

For video, we defined a new (not standard yet) MPEG-4 descriptor defining a video stream as carrying the depth map of another video stream. This is in-sync with approaches based on MPEG-C Part 3. You can find a sample BT file showing this here, then use MP4Box to produce the mp4 file.

The playback of video+depth or image+depth is in its early stage in GPAC, you will need a BIG machine and a recent graphics card to get good results. Don’t expect too much from high resolution video yet, they will likely overkill the player. The reason for this ? The video data is sent as as a point sprite, triangle strip elevation grid or vertex buffer, and this costs a lot (this will have to be improved in the future).

The way depth video is rendered is defined by the following option:

[Compositor]
DepthType=None

DepthType take the following value:

  • None: video is rendered as a flat rectangle
  • Points: video is rendered as a point sprite if GL_ARB_point_parameters extension is supported
  • Strips: video is rendered as a triangle strip. You may specify “Strips=V” as an option; this will perform two-pass rendering and V the cut-off value for the depth (expressed between 0 and 255)
  • VertexArray: video is rendered as a full vertex array, potentially cached if VBOs are supported.

The height of each vertex is taken from the depth map and multiplied by the DepthScale value.

Note that you don’t need stereo-rendering to play with this:

[youtube]http://www.youtube.com/watch?v=-AuaU1Eq5Xg[/youtube]

When playing depth+video or depth+image, GPAC will automatically switch to OpenGL rendering if the DepthType option is not None.

Thanks for reading, and, happy 3D’ing !!!