Skip to content

Global options

GPAC Core Options

libgpac core options:

-noprog: disable progress messages
-quiet: disable all messages, including errors
-proglf: use new line at each progress messages
-strict-error,-se: exit after the first error is reported
-store-dir (string): set storage directory
-mod-dirs (string list): set additional module directories as a semi-colon ; separated list
-js-dirs (string list): set javascript directories
-no-js-mods (string list): disable javascript module loading
-ifce (string): set default multicast interface (default is ANY), either an IP address or a device name as listed by gpac -h net. Prefix '+' will force using IPv6 for dual interface
-lang (string): set preferred language
-cfg,-opt (string): get or set configuration file value. The string parameter can be formatted as:
section:key=val: set the key to a new value
section:key=null, section:key: remove the key
section=null: remove the section
no argument: print the entire configuration file
section: print the given section
section:key: print the given key in section (section can be set to *)- *:key: print the given key in all sections

-no-save: discard any changes made to the config file upon exit
-mod-reload: unload / reload module shared libs when no longer used
-for-test: disable all creation/modification dates and GPAC versions in files
-old-arch: enable compatibility with pre-filters versions of GPAC
-ntp-shift (int): shift NTP clock by given amount in seconds
-bs-cache-size (int, default: 512): cache size for bitstream read and write from file (0 disable cache, slower IOs)
-no-check: disable compliance tests for inputs (ISOBMFF for now). This will likely result in random crashes
-unhandled-rejection: dump unhandled promise rejections
-startup-file (string): startup file of compositor in GUI mode
-docs-dir (string): default documents directory (for GUI on iOS and Android)
-last-dir (string): last working directory (for GUI)
-no-poll: disable poll and use select for socket groups
-no-tls-rcfg: disable automatic TCP to TLS reconfiguration
-no-fd: use buffered IO instead of file descriptor for read/write - this can speed up operations on small files

-no-mx: disable all mutexes, threads and semaphores (do not use if unsure about threading used)
-netcap (string): set packet capture and filtering rules formatted as [CFG][RULES]. Each -netcap argument will define a configuration
[CFG] is an optional comma-separated list of:
id=ID: ID (string) for this configuration. If NULL, configuration will apply to all sockets not specifying a netcap ID
src=F: read packets from F, as produced by GPAC or a pcap or pcapng file
dst=F: output packets to F (no pcap/pcapng support), cannot be set if src is set
loop[=N]: loop capture file N times, or forever if N is not set or negative
nrt: disable real-time playback
[RULES] is an optional list of [OPT,OPT2...] with OPT in:
m=N: set rule mode - N can be r for reception only (default), w for send only or rw for both
s=N: set packet start range to N
e=N: set packet end range to N (only used for r and f rules)
n=N: set number of packets to drop to N - not set, 0 or 1 means single packet
r=N: random drop one packet every N
f=N: drop first packet every N
p=P: local port number to filter, if not set the rule applies to all packets
o=N: patch packet instead of droping (always true for TCP), replacing byte at offset N (0 is first byte, <0 for random)
v=N: set patch byte value to N (hexa) or negative value for random (default)


This will record packets to dump.gpc


-netcap=src=dump.gpc,id=NC1 -i session1.sdp:NCID=NC1 -i session2.sdp
This will read packets from dump.gpc only for session1.sdp and let session2.sdp use regular sockets


This will use regular network interface and drop packets 100 to 119 on port 1234 and patch one random packet every 200 starting from packet 500, setting byte 10 to FE

-cache (string): cache directory location
-proxy-on: enable HTTP proxy
-proxy-name (string): set HTTP proxy address
-proxy-port (int, default: 80): set HTTP proxy port
-maxrate (int): set max HTTP download rate in bits per sec. 0 means unlimited
-no-cache: disable HTTP caching
-offline-cache: enable offline HTTP caching (no re-validation of existing resource in cache)
-clean-cache: indicate if HTTP cache should be clean upon launch/exit
-cache-size (int, default: 100M): specify cache size in bytes
-tcp-timeout (int, default: 5000): time in milliseconds to wait for HTTP/RTSP connect before error
-req-timeout (int, default: 10000): time in milliseconds to wait on HTTP/RTSP request before error (0 disables timeout)
-no-timeout: ignore HTTP 1.1 timeout in keep-alive
-broken-cert: enable accepting broken SSL certificates
-user-agent,-ua (string): set user agent name for HTTP/RTSP
-user-profileid (string): set user profile ID (through X-UserProfileID entity header) in HTTP requests
-user-profile (string): set user profile filename. Content of file is appended as body to HTTP HEAD/GET requests, associated Mime is text/xml
-query-string (string): insert query string (without ?) to URL on requests
-dm-threads: force using threads for async download requests rather than session scheduler
-cte-rate-wnd (int, default: 20): set window analysis length in milliseconds for chunk-transfer encoding rate estimation
-cred (string): path to 128 bits key for credential storage
-no-h2: disable HTTP2
-no-h2c: disable HTTP2 upgrade (i.e. over non-TLS)
-h2-copy: enable intermediate copy of data in nghttp2 (default is disabled but may report as broken frames in wireshark)
-dbg-edges: log edges status in filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status, weight, src_cap_idx, dst_cap_idx)
-full-link: throw error if any PID in the filter graph cannot be linked
-no-dynf: disable dynamically loaded filters
-no-block (Enum, default: no): disable blocking mode of filters
no: enable blocking mode
fanout: disable blocking on fan-out, unblocking the PID as soon as one of its destinations requires a packet
* all: disable blocking

-no-reg: disable regulation (no sleep) in session
-no-reassign: disable source filter reassignment in PID graph resolution
-sched (Enum, default: free): set scheduler mode
free: lock-free queues except for task list (default)
lock: mutexes for queues when several threads
freex: lock-free queues including for task lists (experimental)
flock: mutexes for queues even when no thread (debug mode)
* direct: no threads and direct dispatch of tasks whenever possible (debug mode)

-max-chain (int, default: 6): set maximum chain length when resolving filter links. Default value covers for [ in -> ] dmx -> reframe -> decode -> encode -> reframe -> mx [ -> out]. Filter chains loaded for adaptation (e.g. pixel format change) are loaded after the link resolution. Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually
-max-sleep (int, default: 50): set maximum sleep time slot in milliseconds when regulation is enabled
-threads (int): set N extra thread for the session. -1 means use all available cores
-no-probe: disable data probing on sources and relies on extension (faster load but more error-prone)
-no-argchk: disable tracking of argument usage (all arguments will be considered as used)
-blacklist (string): blacklist the filters listed in the given string (comma-separated list). If first character is '-', this is a whitelist, i.e. only filters listed in the given string will be allowed
-no-graph-cache: disable internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (lower memory usage but slower)
-no-reservoir: disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more
-buffer-gen (int, default: 1000): default buffer size in microseconds for generic pids
-buffer-dec (int, default: 1000000): default buffer size in microseconds for decoder input pids
-buffer-units (int, default: 1): default buffer size in frames when timing is not available
-gl-bits-comp (int, default: 8): number of bits per color component in OpenGL
-gl-bits-depth (int, default: 16): number of bits for depth buffer in OpenGL
-gl-doublebuf: enable OpenGL double buffering
-glfbo-txid (int): set output texture ID when using glfbo output. The OpenGL context shall be initialized and gf_term_process shall be called with the OpenGL context active
-video-output (string): indicate the name of the video output module to use (see gpac -h modules). The reserved name glfbo is used in player mode to draw in the OpenGL texture identified by glfbo-txid. In this mode, the application is responsible for sending event to the compositor
-audio-output (string): indicate the name of the audio output module to use
-font-reader (string): indicate name of font reader module
-font-dirs (string): indicate comma-separated list of directories to scan for fonts
-rescan-fonts: indicate the font directory must be rescanned
-wait-fonts: wait for SVG fonts to be loaded before displaying frames
-webvtt-hours: force writing hour when serializing WebVTT
-charset (string): set charset when not recognized from input. Possible values are:
utf8: force UTF-8
utf16: force UTF-16 little endian
utf16be: force UTF-16 big endian
other: attempt to parse anyway

-rmt: enable profiling through Remotery. A copy of Remotery visualizer is in gpac/share/vis, usually installed in /usr/share/gpac/vis or Program Files/GPAC/vis
-rmt-port (int, default: 17815): set remotery port
-rmt-reuse: allow remotery to reuse port
-rmt-localhost: make remotery only accepts localhost connection
-rmt-sleep (int, default: 10): set remotery sleep (ms) between server updates
-rmt-nmsg (int, default: 10): set remotery number of messages per update
-rmt-qsize (int, default: 131072): set remotery message queue size in bytes
-rmt-log: redirect logs to remotery (experimental, usually not well handled by browser)
-rmt-ogl: make remotery sample opengl calls
-m2ts-vvc-old: hack for old TS streams using 0x32 for VVC instead of 0x33
-piff-force-subsamples: hack for PIFF PSEC files generated by 0.9.0 and 1.0 MP4Box with wrong subsample_count inserted for audio
-vvdec-annexb: hack for old vvdec+libavcodec supporting only annexB format
-heif-hevc-urn: use HEVC URN for alpha and depth in HEIF instead of MPEG-B URN (HEIF first edition)
-boxdir (string): use box definitions in the given directory for XML dump