NAME¶
GPAC - MPEG-4 Systems Framework and Software Development Kit
DESCRIPTION¶
GPAC stands (does it ?) for GPAC Project on Advanced Content. It is an
implementation of the MPEG-4 Systems standard written in ANSI C. GPAC provides
tools for media playback, vector graphics and 3D rendering, MPEG-4 authoring
and distribution. This man page is about configuration of the GPAC framework
version 0.5.0.
INTRODUCTION¶
Some applications in the GPAC framework use a configuration file shared among
modules and reloadable at run time. This file is located in the user home
directory and called ".gpacrc".
The configuration file is based on the win32 .ini file model, ordered by
sections and keys.
A section is declared as
[SectionName] , a key is declared as
keyName=value , the key value is not interpreted and always handled as
ASCII text. Plugins may use the configuration file as well (to avoid multiple
files).
Note on plugin names: Plugin names as given in the configuration 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
plugin, it will be replaced by the interface name if the plugin was
successfully loaded.
SECTION General¶
The "General" section holds generic, OS and player specific options.
This section is not used by the GPAC Framework.
- ModulesDirectory (value: path)
- path to modules (plugins) location. The client cannot be
loaded without modules. This option is used by all GPAC clients on all
platforms
- CacheDirectory (value: path)
- specifies location of temp files. This must be the absolute
path to a directory with write access. Although not used by applications,
this is used by several plugins.
The following options are defined for Osmo4/wxWidgets player.
- 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: unsigned int)
- indicates active playlist entry when player was last
closed. Playlist backup is ".gpac_pl.m3u", stored in user home
directory.
- StartupFile value: filename)
- specifies file to load upon startup of osmo4/MP4Client. If
not specified, no file is loaded.
- NoMIMETypeFetch (value: yes, no)
- specifies if the player has to check for mime type when
following hyperlinks, or only follow links of known extensions.
- LogFile (value: filename)
- specifies where to output GPAC's log. By default, the logs
are written to stdout. Note that GPAC may be compiled without log support.
This is not used by MP4Client.
- LogLevel (value: none, error, warning, info,
debug)
- specifies the level of the log. By default, no log is
performed.
- LogTools (value: a ':'-separated list of the following
values)
- specifies which set of tools from GPAC should be logged.
Available tools are:
core: libgpac core events.
coding: bitstream formats (audio, video, scene).
container: container formats (ISO File, MPEG-2 TS, AVI, ...).
network: network data exept RTP trafic.
rtp: rtp, rtcp and rtsp trafic.
author : authoring tools (hint, import, export).
sync: terminal sync layer.
codec: terminal codec messages.
parser: scene parsers (svg, xmt, bt) and other.
media: terminal media object management.
scene: scene graph and scene manager.
script: scripting engine messages.
compose: composition engine (events, etc).
render: renderng engine (2D, 3D, etc).
service: network service management.
mmio: Audio/Video HW I/O management.
SECTION RecentFiles¶
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.
SECTION Systems¶
The "Systems" section holds all configuration options for the MPEG-4
Systems engine. The following options are defined:
- 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 until BIFS streams are back in sync. This is by
default off to keep better sync, but may be changed 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/seek 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.
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).
- hardcoded_protos (value: list of strings separated by
space)
- holds a list list of EXTERNPROTO URLs (NO OD_ID !!!)
implemented in hard in the renderer - for development only.
- NoVisualThread (value: yes, no)
- specifies whether the visual rendering is done in the main
codec manager or in a dedicated thread.
- DefAudioDec, DefVideoDec (value: string)
- Specifies which plugin to use by default for audio/video
decoding. Example, "DefVideoDec=name". The name given is the
name of the plugin to be used (same considerations as other plugins, cf
above).
- codec_XX_XX (value: string)
- Allows to specify default media plugin (audio/video) per
stream type and object type. This is usefull if you have more than one
decoder for a given type. The syntax is codec_AA_BB=pluginname
where AA is the hexadecimal MPEG-4 streamType value for the codec
(0x04=visual, 0x05=audio) and BB is the hexadecimal MPEG-4
objectTypeIndication of the media (0x20 = MPEG-4 video, 0x40=MPEG-4 Audio,
...). The name given is the name of the plugin to be used (same
considerations as other plugins, cf above).
SECTION Rendering¶
The "Rendering" section holds all configuration options for the
logical rendering engines, whether 2D or 3D. The following options are
defined:
- 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 at run-time,
the complete system must be restarted.
- Raster2D (value: string)
- specifies the 2D rasterizer to use for vectorial drawing.
Used by 2D renderer (for everything) and 3D renderer (for textured text
and gradients).
- 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 plugin/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 graphics
plugin/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, meshes, outlines 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¶
The "Render2D" section holds all configuration options for the 2D tile
rendering engine. The following options are defined:
- 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 plugin (currently all plugins 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.
SECTION Render3D¶
The "Render3D" section holds all configuration options for the 3D
openGL rendering engine. The following options are defined:
- 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.
- 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.
If "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
If "no" and extension is available, textures are used without
rescaling. Note that in this case texture transformation are
disabled.
- EmulatePOW2 (value: yes, no)
- enables power of 2 emulation. Ignored if openGL rectangular
texture extension is enabled.
if set, video texture is not resized but emulated with padding. This usually
speeds up video mapping on shapes but disables texture transformations.
if not set, 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¶
The "Audio" section holds all configuration options for the audio
rendering engine and hardware. Note that most options depend on the driver
used and may be ignored by the driver. The following options are defined:
- 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: integer, 0 forbidden)
- When config is forced, specifies the number of audio
buffers to allocate (audio buffers are played in ring if possible,
otherwise a single audio buffer is allocated).
- TotalDuration (value: 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.
Note: The SDL audio plugin does not use the TotalDuration and num
buffers in the same way, it just computes the desired audio buffer size
with this settings and picks the next power of 2 size for audio buffer
size. It does not use ring buffers either.
- NoResync (value: yes, no)
- Disables audio resynchronization: audio clock is never
adjusted and A/V sync may get broken
- 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. Ignored on other platforms than
Win32/DX.
- DriverName (value: string)
- specifies the driver to use for audio rendering.
- Volume (value: integer, range 0-100)
- specifies the default audio volume used when launching
GPAC.
- Pan (value: integer, range 0-100)
- specifies the default audio stereo balance used when
launching GPAC - 0 for full left, 100 for full right, 50 for
balanced.
SECTION Video¶
The "Video" section holds all configuration options for the video
renderer and hardware. The following options are defined:
- DisableYUV (value: yes, no) - used by 2D renderer
only
- disables YUV hardware support (YUV hardware support may not
be available for the current plugin).
- SwitchResolution (value: yes, no)
- if enabled, selects smallest video resolution larger than
scene size, otherwise use current video resolution.
- DriverName (value: string)
- specifies the driver to use for video memory access.
SECTION Network¶
The "Network" section holds all configuration options for the network
used by plugins and systems engine. The following options are defined:
- AutoReconfigUDP (value: yes, no)
- specifies if network manager shall reconnect a scene if UDP
traffic is blocked.
- DataTimeout (value: unsigned int)
- specifies timeout in milliseconds befor initial buffering
aborts. Default terminal value is 20000 (20 seconds).
- UDPNotAvailable (value: yes, no)
- specifies that UDP traffic is not available (usually set by
GPAC)
- UDPTimeout (value: unsigned int)
- specifies timeout in milliseconds for initial UDP
detection. Once a UDP packet is recieved the timeout is ignored.
- BufferLength (value: unsigned int)
- specifies the default length of the decoding buffer in
milliseconds. The client will wait for the buffer to be filled before
starting decoding. A plugin may decide to use a different value based on
protocol and network jitters.
- RebufferLength (value: unsigned int)
- 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 plugin may
decide to use a different value based on protocol and network
jitters.
SECTION FontEngine¶
The "FontEngine" section holds all configuration options for the font
handling. The GPAC rendering module handles text through vectorial outline,
allowing graphics plugin development without having to integrate text
rendering which is always heavy work. The following options are defined:
- DriverName (value: string)
- specifies the driver to use for font handling.
- FontDirectory (value: path)
- specifies the directory where fonts are located - currently
only one directory can be specified (however nothing stops a font plugin
from using a private directory). If the directory is invalid or does not
contain fonts, text may be unavailable in GPAC.
- 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 plugin uses this section to maintain associations
between font names and truetype font file names. This greatly speeds up font
selection at run-time.
SECTION Downloader¶
The "Downloader" section 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.
- MaxRate (value: positive integer)
- specifies a maximum data rate in kilo bits per seconds for
file downloading. This is used for simulation purposes. A value of 0 means
no rate restriction.
- UserAgent (value: string)
- specifies an alternate user agent (default one is
"GPAC $VERSION").
SECTION HTTPProxy¶
The "HTTPProxy" section of the config file holds configuration option
for HTTP proxy adressing. Currently only one proxy can be enabled, and no URI
selection is done
- Enabled (value: yes, no)
- specifies whether the proxy should be used or not when
downloading files.
- Name (value: string)
- specifies the proxy name (IP address or resolved name)
without protocol identifier (eg, no "http://"). If not present,
the proxy is disabled.
- Port (value: positive integer)
- Specifies the port to use with the proxy. If no port is
specified, the default HTTP port (80) is used.
SECTION Streaming¶
The "Streaming" section 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: integer)
- size of the RTP reordering buffer - 0 means no reordering.
Ignored when transport takes place on the RTSP connection
- 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: unsigned int)
- specifies connection timeout with the server: an RTSP
request is considered as failed when the timeout expires.
- FirstPacketDrop (value: unsigned int)
- specifies the first SL packet to be droped - 0 means no
packet drop. Used for packet drop simulation tests.
- PacketDropFrequency (value: unsigned int)
- 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.
SECTION MimeTypes¶
This section is used to keep MIME types and file associations for GPAC plugins.
The format of the key is:
mimeType="fileExt1 filexExt2 ..
filexExtN" MimeType description PluginName
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 plugins. If MIME type is not available, provided extensions are
first checked, then all input plugins are queried.
SECTION MimeTypes¶
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 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 SAXLoader¶
The "SAXLoader" section holds all configuration options for XML SAX
parsing of SVG, XMT and X3D files.
Progressive (value: string)¶
specifies XML parsing mode used by the loader. Supported modes are:
yes: SAX parsing is used with progressive loading of the document.
no: SAX parsing is used, document will first be completely downloaded.
DOM: DOM parsing is used, document will first be completely downloaded. Only
supported by libXML2 plugin, otherwise handled as "no".
- MaxDuration (value positive integer)
- specifies the maximum amount of time the SAX parser should
spent loading a portion of the document. Only used in SAX Progressive
mode.
SECTION XviD¶
The "XviD" section holds all configuration options for the XviD codec.
PostProc (value: string)¶
specifies filters to apply when decoding video. The string is a list of filters
separated with a space character. Filters supported are:
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¶
The "FFMPEG" section holds all configuration options for the FFMPEG
demuxer and codec.
DataBufferMS (value: unsigned int)¶
specifies the amount of video/audio data (in milliseconds) to be bufferer before
starting decoding. For developpers only.
Section ISOReader¶
The "ISOReader" section holds all configuration options for the ISO
Media file demuxer.
IgnoreMPEG-4ForBrands (value: Full 4CC or 4CC pattern (abc*
ab*))¶
ignores all MPEG-4 systems tracks and IOD for files showing the listed brands in
their compatible brand list.
CREATING THE CONFIGURATION FILE¶
- If not found, a default configuration file is created when
launching MP4Client or Osmo4. In this process the font directory and the
cache directory must be entered at prompt. The file is located in the user
home directory and called ".gpacrc"
FILES¶
GPAC Configuration File: ~/.gpacrc
AUTHORS¶
Jean Le Feuvre <jeanlf@users.sourceforge.net> - GPAC (c) 2000-2005
SEE ALSO¶
MP4Client(1),
MP4Box(1)