General Usage of gpac

Usage: gpac [options] FILTER [LINK] FILTER [...]   
gpac is GPAC's command line tool for setting up and running filter chains.  
  
_FILTER_: a single filter declaration (e.g., `-i file`, `-o dump`, `inspect`, ...), see [gpac -h doc](filters_general#filter-declaration-filter).  
_[LINK]_: a link instruction (e.g., `@`, `@2`, `@2#StreamType=Visual`, ...), see [gpac -h doc](filters_general#explicit-links-between-filters-link).  
_[options]_: one or more option strings, each starting with a `-` character.  

    - an option using a single `-` indicates an option of gpac (see [gpac -hx](gpac_general#h)) or of libgpac (see [gpac -hx core](core_options))  
    - an option using `--` indicates a global filter or meta-filter (e.g. FFmpeg) option, e.g. `--block_size=1000` or `--profile=Baseline` (see [gpac -h doc](core_config#global-filter-options))  

    
Filter declaration order may impact the link resolver which will try linking in declaration order. Most of the time for simple graphs, this has no impact. However, for complex graphs with no link declarations, this can lead to different results.    
Options do not require any specific order, and may be present anywhere, including between link statements or filter declarations.    
Boolean values do not need any value specified. Other types shall be formatted as `opt=val`, except [-i](#i), `-src`, [-o](#o), `-dst` and [-h](#h) options.  
  
The session can be interrupted at any time using `ctrl+c`, which can also be used to toggle global reporting.  
  
The possible options for gpac are:  
  
<div markdown class="option">
<a id="ltf">__-ltf__</a>:      load test-unit filters (used for for unit tests only)  
</div>
<div markdown class="option">
<a id="sloop">__-sloop__</a> (int): loop execution of session, creating a session at each loop, mainly used for testing. If no value is given, loops forever  
</div>
<div markdown class="option">
<a id="runfor">__-runfor__</a> (int): run for the given amount of milliseconds, exit with full session flush  
</div>
<div markdown class="option">
<a id="runforf">__-runforf__</a> (int): run for the given amount of milliseconds, exit with fast session flush  
</div>
<div markdown class="option">
<a id="runforx">__-runforx__</a> (int): run for the given amount of milliseconds and exit with no cleanup  
</div>
<div markdown class="option">
<a id="runfors">__-runfors__</a> (int): run for the given amount of milliseconds and exit with segfault (tests)  
</div>
<div markdown class="option">
<a id="runforl">__-runforl__</a> (int): run for the given amount of milliseconds and wait forever at end (tests)  
</div>
<div markdown class="option">
<a id="stats" data-level="basic">__-stats__</a>: print stats after execution  
</div>
<div markdown class="option">
<a id="graph" data-level="basic">__-graph__</a>: print graph after execution  
</div>
<div markdown class="option">
<a id="qe">__-qe__</a>:        enable quick exit (no mem cleanup)  
</div>
<div markdown class="option">
<a id="k">__-k__</a>:          enable keyboard interaction from command line  
</div>
<div markdown class="option">
<a id="r" data-level="basic">__-r__</a> (string): enable reporting  

- r: runtime reporting  
- r=FA[,FB]: runtime reporting but only print given filters, e.g. `r=mp4mx` for ISOBMFF multiplexer only  
- r=: only print final report  
</div>
  
<div markdown class="option">
<a id="seps">__-seps__</a> (string, default: __:=#,!@__): set the default character sets used to separate various arguments  

- the first char is used to separate argument names  
- the second char, if present, is used to separate names and values  
- the third char, if present, is used to separate fragments for PID sources  
- the fourth char, if present, is used for list separators (_sourceIDs_, _gfreg_, ...)  
- the fifth char, if present, is used for boolean negation  
- the sixth char, if present, is used for LINK directives (see [filters help (-h doc)](filters_general))  
</div>
  
<div markdown class="option">
<a id="i" data-level="basic">__-i__</a>,__-src__ (string): specify an input file - see [filters help (-h doc)](filters_general)  
</div>
  
<div markdown class="option">
<a id="o" data-level="basic">__-o__</a>,__-dst__ (string): specify an output file - see [filters help (-h doc)](filters_general)  
</div>
  
<div markdown class="option">
<a id="ib">__-ib__</a> (string): specify an input file to wrap as GF_FileIO object (testing of GF_FileIO)  
</div>
<div markdown class="option">
<a id="ibx">__-ibx__</a> (string): specify an input file to wrap as GF_FileIO object without caching (testing of GF_FileIO)  
</div>
<div markdown class="option">
<a id="ob">__-ob__</a> (string): specify an output file to wrap as GF_FileIO object (testing of GF_FileIO)  
</div>
<div markdown class="option">
<a id="cl">__-cl__</a>:        force complete mode when no link directive are set - see [filters help (-h doc)](filters_general)  
</div>
  
<div markdown class="option">
<a id="sid">__-sid__</a>:      force source IDs to be present when attempting to link - see [filters help (-h doc)](filters_general)  
</div>
  
<div markdown class="option">
<a id="step">__-step__</a>:    test step mode in non-blocking session  
</div>
<div markdown class="option">
<a id="h" data-level="basic">__-h__</a>,__-help,-ha,-hx,-hh__ (string): print help. Use `-help` or `-h` for basic options, `-ha` for advanced options, `-hx` for expert options and `-hh` for all.    
_Note: The `@` character can be used in place of the `*` character. String parameter can be:_  

- empty: print command line options help  
- doc: print the general filter info  
- alias: print the gpac alias syntax  
- log: print the log system help  
- core: print the supported libgpac core options. Use -ha/-hx/-hh for advanced/expert options  
- cfg: print the GPAC configuration help  
- net: print network interfaces  
- prompt: print the GPAC prompt help when running in interactive mode (see [-k](gpac_general/#k) )  
- modules: print available modules  
- module NAME: print info and options of module `NAME`  
- creds: print credential help  
- filters: print name of all available filters  
- filters:*: print name of all available filters, including meta filters  
- codecs: print the supported builtin codecs - use `-hx` to include unmapped codecs (ffmpeg, ...)  
- formats: print the supported formats (`-ha`: print filter names, `-hx`: include meta filters (ffmpeg,...), `-hh`: print mime types)  
- protocols: print the supported protocol schemes (`-ha`: print filter names, `-hx`: include meta filters (ffmpeg,...), `-hh`: print all)  
- props: print the supported builtin PID and packet properties  
- props PNAME: print the supported builtin PID and packet properties mentioning `PNAME`  
- colors: print the builtin color names and their values  
- layouts: print the builtin CICP audio channel layout names and their values  
- links: print possible connections between each supported filters (use -hx to view src->dst cap bundle detail)  
- links FNAME: print sources and sinks for filter `FNAME` (either builtin or JS filter)  
- defer: print defer mode help  
- FNAME: print filter `FNAME` info (multiple FNAME can be given)  

    - For meta-filters, use `FNAME:INST`, e.g. `ffavin:avfoundation`  
    - Use `*` to print info on all filters (_big output!_), `*:*` to print info on all filters including meta filter instances (_really big output!_)  
    - By default only basic filter options and description are shown. Use `-ha` to show advanced options capabilities, `-hx` for expert options, `-hh` for all options and filter capabilities including on filters disabled in this build  

- FNAME.OPT: print option `OPT` in filter `FNAME`  
- OPT: look in filter names and options for `OPT` and suggest possible matches if none found. Use `-hx` to look for keyword in all option descriptions  
  
</div>
  
<div markdown class="option">
<a id="p">__-p__</a> (string): use indicated profile for the global GPAC config. If not found, config file is created. If a file path is indicated, this will load profile from that file. Otherwise, this will create a directory of the specified name and store new config there. The following reserved names create a temporary profile (not stored on disk):  

- 0: full profile  
- n: null profile disabling shared modules/filters and system paths in config (may break GUI and other filters)  

Appending `:reload` to the profile name will force recreating a new configuration file  
</div>
  
<div markdown class="option">
<a id="alias">__-alias__</a> (string): assign a new alias or remove an alias. Can be specified several times. See [alias usage (-h alias)](#using-aliases)  
</div>
<div markdown class="option">
<a id="aliasdoc">__-aliasdoc__</a> (string): assign documentation for a given alias (optional). Can be specified several times  
</div>
<div markdown class="option">
<a id="uncache">__-uncache__</a>: revert all items in GPAC cache directory to their original name and server path  
</div>
<div markdown class="option">
<a id="js">__-js__</a> (string): specify javascript file to use as controller of filter session  
</div>
<div markdown class="option">
<a id="wc">__-wc__</a>:        write all core options in the config file unless already set  
</div>
<div markdown class="option">
<a id="we">__-we__</a>:        write all file extensions in the config file unless already set (useful to change some default file extensions)  
</div>
<div markdown class="option">
<a id="wf">__-wf__</a>:        write all filter options in the config file unless already set  
</div>
<div markdown class="option">
<a id="wfx">__-wfx__</a>:      write all filter options and all meta filter arguments in the config file unless already set (_large config file !_)  
</div>
<div markdown class="option">
<a id="xopt">__-xopt__</a>:    unrecognized options and filters declaration following this option are ignored - used to pass arguments to GUI  
</div>
  
<div markdown class="option">
<a id="creds">__-creds__</a> (string): setup credentials as used by servers  
</div>
<div markdown class="option">
<a id="rv">__-rv__</a>:        return absolute value of GPAC internal error instead of 1 when error  
</div>
  
    
The following libgpac core options allow customizing the filter session:  
    
<div markdown class="option">
<a id="dbg-edges">__-dbg-edges__</a>: log edges status in filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status(disable_depth), weight, src_cap_idx -> dst_cap_idx)  
</div>
<div markdown class="option">
<a id="full-link">__-full-link__</a>: throw error if any PID in the filter graph cannot be linked  
</div>
<div markdown class="option">
<a id="no-dynf">__-no-dynf__</a>: disable dynamically loaded filters  
</div>
<div markdown class="option">
<a id="no-block">__-no-block__</a> (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  
</div>
  
<div markdown class="option">
<a id="no-reg">__-no-reg__</a>: disable regulation (no sleep) in session  
</div>
<div markdown class="option">
<a id="no-reassign">__-no-reassign__</a>: disable source filter reassignment in PID graph resolution  
</div>
<div markdown class="option">
<a id="sched">__-sched__</a> (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)  
</div>
  
<div markdown class="option">
<a id="max-chain">__-max-chain__</a> (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  
</div>
<div markdown class="option">
<a id="max-sleep">__-max-sleep__</a> (int, default: __50__): set maximum sleep time slot in milliseconds when regulation is enabled  
</div>
<div markdown class="option">
<a id="step-link">__-step-link__</a>: load filters one by one when solvink a link instead of loading all filters for the solved path  
</div>
<div markdown class="option">
<a id="threads">__-threads__</a> (int): set N extra thread for the session. -1 means use all available cores  
</div>
<div markdown class="option">
<a id="no-probe">__-no-probe__</a>: disable data probing on sources and relies on extension (faster load but more error-prone)  
</div>
<div markdown class="option">
<a id="no-argchk">__-no-argchk__</a>: disable tracking of argument usage (all arguments will be considered as used)  
</div>
<div markdown class="option">
<a id="blacklist">__-blacklist__</a> (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  
</div>
<div markdown class="option">
<a id="no-graph-cache">__-no-graph-cache__</a>: disable internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (lower memory usage but slower)  
</div>
<div markdown class="option">
<a id="no-reservoir">__-no-reservoir__</a>: disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more  
</div>
<div markdown class="option">
<a id="buffer-gen">__-buffer-gen__</a> (int, default: __1000__): default buffer size in microseconds for generic pids  
</div>
<div markdown class="option">
<a id="buffer-dec">__-buffer-dec__</a> (int, default: __1000000__): default buffer size in microseconds for decoder input pids  
</div>
<div markdown class="option">
<a id="buffer-units">__-buffer-units__</a> (int, default: __1__): default buffer size in frames when timing is not available  
</div>