GPAC Configuration file documentation - version 0.4.0
Last Modified July 2005



Overview

Some applications in the GPAC framework use a configuration file shared among modules and reloadable at run time. Modules may use the configuration file as well (to avoid multiple config files). This doc attempts to provide explanations for the different options.

The config file is based on the win32 .ini file model, thus is ordered by sections and keys.

A section is declared as SectionName. Defined sections are:

General RecentFiles Systems Rendering Render2D Render3D Audio Video Network FontEngine Downloader Streaming MimeTypes StreamingCache XviD FFMPEG

A key is declared as keyName=value. The key value is not interpreted and always handled as ASCII text.

On Windows plateforms, this config file is called "GPAC.cfg" and is usually located in C:\\Program Files\\GPAC. Note that Osmo4 will always create a config file in its own directory when none is found.
On Windows CE plateform, this config file is called "GPAC.cfg" and is usually located in \\Program Files\\GPAC. Note that Osmo4 / CE will always create a config file in its own directory when none is found.
On Linux plateforms, this config file is called ".gpacrc" and is always located at the root of the user home directory (for ex, /home/jean/.gpacrc).


Note on module names:
Module names as given in the config file are names exported by each interface and not name of the physical library file (.dll, .so, ...). The physical file name can however be used to identify a module - it will then be replaced by the module name.

Section "General" Back to top

The General section of the config file holds player specific options. This section is not used by GPAC core engine.

ModulesDirectory [value: path to directory]
Specifies the path to modules directory. The MPEG-4 Systems engine cannot be loaded without modules. This option is used by all MP4Client on all platforms.
CacheDirectory [value: path to storage directory]
Specifies location of temp files. The user must have write access to this location. Although not used by applications, this is used by several modules.


Options defined for Osmo4 (Windows version and wxWidgets version):

Loop [value: "yes" "no"]
Specifies whether the presentation has to be restarted when done playing.

ConsoleOff [value: "yes" "no"]
Specifies whether application messages (script, buffering, download progress) are displayed in the console or not.

Browser [value: string]
Specifies prefered browser for WWW anchors and scene graph viewing - Only used by Osmo4/wxWidgets.

LookForSubtitles [value: "yes" "no"]
Specifies if Osmo4 shall look for subtitle files when opening a presentation.

PLEntry [value: positive integer]
Indicates active playlist entry when player was last closed. Playlist backup is:
  • "gpac_pl.m3u" on win32 platforms, stored in same directory as application
  • ".gpac_pl.m3u" on other platforms, stored in user home directory


    • Section "RecentFiles" Back to top

    The "RecentFiles" section of the config file holds last accessed files (hardcoded to no more than 20) in the last access order. The keys are the file names and no value is used. This section is only used by GUI clients (osmo4/wxOsmo4)


    Section "Systems" Back to top

    The "Systems" section of the config file holds all configuration options for the MPEG-4 Systems engine.

    Language [value: 3-char code from ISO 639-2]
    Specifies the user prefered language. This is used to select streams in case of alternate content in an audio object.

    AlwaysDrawBIFS [value: "yes" "no"]
    If set, late BIFS frame will still be drawn. If not set, the scene won't be redrawn untill BIFS streams are back in sync. This is by default off to keep better sync, but may be usefull when testing heavy content or slow renderers.

    ForceSingleClock [value: "yes" "no"]
    One big problem with MP4 files is that the notion of "duration" has been unclear for a long time, and most content available (audio-video files) specifiy a wrong BIFS duration. In such a case the movie cannot be controled/seeked into. Another problem with ISMA streaming is that BIFS/OD don't use the same clock as audio/video, thus seeking the main timeline does not seek AV media. Setting the ForceSingleClock will handle both cases by using a single timeline for all media streams and setting the duration to the one of the longest stream.

    ThreadingPolicy [value: "Free" "Single" "Multi"]
    Specifies how media decoders are to be threaded. "Free" lets decoders decide of their threading, "Single" means that all decoders are managed in a single thread performing scheduling and priority handling and "Multi" means that each decoder runs in its own thread.

    Priority [value: "low" "normal" "high" "real-time"]
    Specifies the priority of the decoders (priority is applied to decoder thread(s) regardless of threading mode).

    NoVisualThread [value: "yes" "no"]
    Specifies whether the visual rendering is done in the main codec manager or in a dedicated thread.

    DefAudioDec and DefVideoDec [value: string]
    Specifies which module to use by default for audio/video decoding. The string is the name of the module to be used (same considerations as other modules, cf introduction).

    codec_XX_XX [value: string]
    Allows to specify default media module (audio/video) per stream type and object type. This is usefull if you have more than one decoder for a given type (ex, XviD and FFMPEG for MPEG-4 visual SP). The syntax is:
    codec_AA_BB=modulename
    where AA is the hexadecimal MPEG-4 streamType value for the codec (04=visual, 05=audio) and BB is the hexadecimal MPEG-4 objectTypeIndication of the media (0x20 = MPEG-4 video, 0x40=MPEG-4 Audio, ...). The string is the name of the module to be used (same considerations as other modules, cf introduction).


    Section "Rendering" Back to top

    The "Rendering" section of the config file holds all configuration options for the logical rendering engine.

    RendererName [value: string]
    Specifies which renderer should be used. There are currently 2 renderers available in GPAC, "GPAC 2D Renderer" and "GPAC 3D Renderer". Renderers cannot be reloaded during a presentation, the GPAC client shall be shutdown and restarted.

    Raster2D [value: string]
    Specifies the 2D rasterizer to use for vectorial drawing. Same as above, this module cannot be reloaded during a presentation. This is used by the 2D renderer for all drawings and by the 3D renderer for text texturing and gradients compute.

    FrameRate [value: float]
    Specifies the simulation frame-rate of the presentation - this value is also used by the MPEG-4 Systems engine to determine when a BIFS frame is mature for decoding.

    AntiAlias [value: "None" "All" "Text"]
    Specifies antialiasing settings - whether the setting is applied or not depends on the graphics module / graphic card.
  • "None": no anti-aliasing

  • "Text": anti-aliasing for text only

  • "All": complete anti-aliasing


    • FastRender [value: "yes" "no"]
    Specifies whether rendering should target speed or quality - whether the setting is applied or not depends on the renderer, graphics module / graphic card.

    ForceSceneSize [value: "yes" "no"]
    Forces the scene to resize to the biggest bitmap available if no size info is given in the BIFS configuration.

    StressMode [value: "yes" "no"]
    Specifies that the renderer runs in worst case scenario, recomputing all vectorial paths, outline or display lists and reloading textures (sending them to graphics card) at each frame.

    BoundingVolume [value: "None" "Box" "AABB"]
    Specifies whether the bounding volume of an object shall be drawn or not. Note that the 2D renderer only uses rectangles as bounding volumes. The "AABB" value is used by the 3D renderer only, and specifies the object bounding-box tree shall be drawn.


    Section "Render2D" Back to top

    The "Render2D" section of the config file holds all configuration options for the 2D tile rendering engine and hardware.

    DirectRender [value: "yes" "no"]
    Specifies whether direct rendering should be used or not. In direct rendering mode, the screen is completely redrawn at each frame. In indirect rendering object positioning is tracked from frame to frame and dirty rectangles info is collected in order to redraw the minimal amount of the screen buffer. Whether the setting is applied or not depends on the graphics module (currently all modules handle both mode).

    ScalableZoom [value: "yes" "no"]
    Specifies whether scalable zoom should be used or not. When scalable zoom is enabled, resizing the output window will also recompute all vectorial objects. Otherwise only the final buffer is stretched.

    DisableYUV [value: "yes" "no"]
    Disables YUV hardware support (YUV hardware support may not be available for the current video output module).


    Section "Render3D" Back to top

    The "Render3D" section of the config file holds all configuration options for the 3D rendering engine and OpenGL hardware.

    RasterOutlines [value: "yes" "no"]
    Specifies that outlining shall be done through OpenGL pen width rather than vectorial outlining.

    PolygonAA [value: "yes" "no"]
    Specifies whether polygon antialiasing should be used in full antialiasing mode. If not set, only lines and points antialiasing are used.

    DisableBackFaceCulling [value: "yes" "no"]
    Specifies whether backface culling shall be disable or not. If not set, backface culling is performed.

    Wireframe [value: "WireNone" "WireOnly" "WireOnSolid"]
    Specifies wireframe drawing options:
  • "WireNone": objects are drawn as solid

  • "WireOnly": objects are drawn as wireframe only

  • "WireOnSolid": objects are drawn as solid and wireframe is then drawn


    • DisableRectExt [value: "yes" "no"]
    Specifies whether OpenGL rectangular texture extension (GL_EXT_texture_rectangle or GL_NV_texture_rectangle) shall be used or not.
  • "yes": textures whose dimensions are not power of two are rescaled except if hardware support non-power-of-two textures (GL_ARB_texture_non_power_of_two) natively.

  • "no": if extension is available, textures are used without rescaling. Note that in this case texture transformations are disabled.


    • EmulatePOW2 [value: "yes" "no"]
    Enables power of 2 emulation. Ignored if openGL rectangular texture extension is enabled.
  • "yes": video texture is not resized but emulated with padding. This usually speeds up video mapping on shapes but disables texture transformations.

  • "no": video is resized to a power of 2 texture when mapping to a shape.


    • BitmapCopyPixels [value: "yes" "no"]
    Specifies whether the bitmap node should be drawn with regular openGL texturing ("no") or through pixel copy routines ("yes"). This greatly impacts video rendering through bitmap depending on the graphics card. Some cards will have faster pixel copy routines that texture transfer ones, some won't.


    Section "Audio" Back to top

    The "Audio" section of the config file holds all configuration options for the audio rendering engine and hardware.

    DriverName [value: string]
    Specifies the driver to use for audio rendering. This driver cannot be reloaded at run-time, the complete system must be restarted.

    ForceConfig [value: "yes" "no"]
    Forces a given sound card configuration to be used. If not set the sound card will be setup to use 2 audio buffers of 1024 samples each. This may not work properly on some audio cards due to hardware latency, therefore forcing the config may be very usefull.

    NumBuffers [value: positive integer, 0 forbidden]
    When config is forced, specifies the number of audio buffers to allocate (audio buffers are played in ring).

    TotalDuration [value: positive integer, 0 forbidden]
    When config is forced, specifies the total audio buffer size in milliseconds. Be aware that the longer the audio buffer is, the longer the audio latency will be when pausing an audio object. The quality of fast forward audio playback will also be degradated when using large audio buffers.

    NoResync [value: "yes" "no"]
    Disables audio resynchronization: audio data is never dropped but may get out of sync.

    DisableMultiChannel [value: "yes" "no"]
    Disables audio multichannel output and always downmix to stereo. This may be usefull if the multichannel output behaves weirdly.

    DisableNotification [value: "yes" "no"]
    Disables usage of audio buffer notifications when supported (currently only DirectSound supports it). If DirectSound audio sounds weird try without notifications.

    Volume [value: integer (0-100)]
    Default audio volume used when launching GPAC.

    Pan [value: integer (0-100)]
    Default audio stereo balance used when launching GPAC - 0 for full left, 100 for full right, 50 for balanced.


    Section "Video" Back to top

    The "Video" section of the config file holds all configuration options for the video renderer and hardware.

    DriverName [value: string]
    Specifies the driver to use for video memory access. This driver cannot be reloaded at run-time, the complete system must be restarted.

    SwitchResolution [value: "yes" "no"]
    Specifies fullscreen resolution mode. If enabled, selects smallest video resolution larger than scene size, otherwise use current video resolution.


    Section "Network" Back to top

    The "Network" section of the config file holds all configuration options for the network used by modules and systems engine.

    AutoReconfigUDP [value: "yes" "no"]
    Specifies if network manager shall reconnect a scene if UDP is not present.

    DataTimeout [value: positive integer]
    Specifies timeout in ms befor initial media buffering aborts. Default terminal value is 20000 (20 seconds).

    UDPNotAvailable [value: "yes" "no"]
    Specifies if UDP traffic is not available. This is automatically set by the engine if AutoReconfigUDP is set.

    UDPTimeout [value: positive integer]
    Specifies timeout in ms for initial UDP detection. Once a UDP packet is recieved the timeout is ignored.

    BufferLength [value: positive integer]
    Specifies the length of the decoding buffer in milliseconds. The client will wait for the buffer to be filled before starting decoding. A module may decide to use a different value based on protocol and network jitters.

    RebufferLength [value: positive integer]
    Specifies rebuffering length of the decoding buffer in milliseconds. Whenever the decoding buffer fullness is less than this value, the object clock is paused and the stream rebuffered till BufferLength. Therefore a value of 0 means no rebuffering. A module may decide to use a different value based on protocol and network jitters.


    Section "FontEngine" Back to top

    The "FontEngine" section of the config file holds all configuration options for the font handling. The GPAC rendering module handles text through vectorial outline, allowing graphics module development without having to integrate text rendering which is always heavy work.

    DriverName [value: string]
    Specifies the driver to use for font handling. This driver cannot be reloaded at run-time, the complete system must be restarted.

    FontDirectory (value: path to TrueType (*.ttf, *.ttc) font directory]
    Specifies the directory where fonts are located - currently only one directory can be specified (however nothing stops a font module from using a private directory).

    TextureTextMode (value: "Never", "3D", "Always"]
    Specifies whether text shall be drawn to a texture and then rendered or directly rendered. Using textured text can improve text look in the 3D renderer and also improve text-on-video like content.

    FontSerif [value: string]}: specifies default SERIF font.
    FontSans [value: string]}: specifies default SANS font.
    FontFixed [value: string]}: specifies default fixed font.

    Note:
    The FreeType module uses this section to cache familly names to font file name associations.


    Section "Downloader" Back to top

    The "Downloader" section of the config file holds all configuration options for file downloading and caching.

    CleanCache [value: "yes" "no"]
    Specifies whether downloaded files shall be removed once used.

    RestartFiles [value: "yes" "no"]
    Specifies whether incompletely downloaded files shall be removed before redownloading.


    Section "Streaming" Back to top

    The "Streaming" section of the config file holds all configuration options for real-time streaming using IETF SDP/RTSP/RTP/RTCP protocols.

    DefaultPort [value: unsigned short]
    Specifies the default port to use when connecting to a server (ignored if a port is specified in the url) if the port is 80 or 8080 (HTTP), the client will connect to the RTSP server through an HTTP tunnel, and transport will take place on the RTSP connection.

    ReorderSize [value: positive integer]
    Size of the RTP reordering buffer - 0 means no reordering. Ignored when transport takes place on the RTSP connection. The bigger this value, the longer the reordering delay will be.

    RTPoverRTSP [value: "yes" "no"]
    Specifies whether RTP packets should be carried on the RTSP connection (TCP or UDP) when possible, or carried on UDP. If the connection port is an HTTP port, this value is assumed to be true.

    RTSPTimeout [value: positive integer]
    Specifies connection timeout with the server: an RTSP request is considered as failed when the timeout expires.

    FirstPacketDrop [value: positive integer]
    Specifies the sequence number of the first RTP packet to be droped - 0 means no packet drop. Used for packet drop simulation tests.

    PacketDropFrequency [value: positive integer]
    Specifies the frequency at which SL packets are droped. If value is 20, one packet every 20 recieved packets will be droped. Used for packet drop simulation tests.

    LogFile [value: filename]
    If set, specifies a file where RTSP traffic is logged - use "stdout" for stdout.


    Section "MimeTypes" Back to top

    This section is used to keep MIME types and file associations for GPAC modules.
    The format of the key is:
    mimeType="fileExt1 filexExt2 .. filexExtN" "MimeType description" ModuleName
    The description is used for GUI purposes (open file dialogs). You may modify the file extension list to support your own extensions. MIME Type is always checked when processing a remote ressource (eg http file) in order to load the appropriated modules. If MIME type is not available, provided extensions are first checked, then all input modules are queried.


    Section "StreamingCache" Back to top

    The "StreamingCache" section of the config file holds all configuration options for the streaming cache. Streaming cache allows for recording of live sources such as RTP/RTSP sessions and internet radios. This is currently just an experimental feature in GPAC.

    RecordDirectory [value: path]
    Specifies path for recorded files. Cached data is written directly to disk (no re-interleaving or similar processes). If not specified, the default cache directory (cf General) is used.

    BaseFileName [value: string]
    Specifies the base name for recorded files. If not present in configuration file, the service name (URL) is used.

    KeepExistingFiles [value: "yes" "no"]
    Specifies if cached files with same name should be kept or not. If not, an integer number is added to the cached file name, the higest number for the latest file.


    Section "XviD" Back to top

    The "XviD" section of the config file holds all configuration options for the XviD codec.

    PostProc [value: "FilmEffect" "Deblock_Y" "Deblock_UV"]
    Specifies filters to apply when decoding video. The string is a list of filters separated with a space character.
    "FilmEffect": xvid 1.0.0 filmEffect.
    "Deblock_Y": Y plane deblocking filter.
    "Deblock_UV": UV plane deblocking filter.

    Threaded [value "yes" "no"]
    Specifies whether the decoder should run in its own thread or not.


    Section "FFMPEG" Back to top

    The "FFMPEG" section of the config file holds all configuration options for the FFMPEG demuxer and decoder.

    DataBufferMS [value: positive integer]
    Specifies the amount of video/audio data (in milliseconds) to be bufferer before starting decoding. For developpers only.




    GPAC (C) 2001 - 2005 Jean Le Feuvre