GPAC Usage

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.
[LINK]: a link instruction (e.g., @, @2, @2#StreamType=Visual, ...), see gpac -h doc.
[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, -src, -o, -dst and -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:

-mem-track: enable memory tracker

-mem-track-stack: enable memory tracker with stack dumping

-ltf: load test-unit filters (used for for unit tests only)

-sloop (int): loop execution of session, creating a session at each loop, mainly used for testing, breaking at first error. If no value is given, loops forever

-runfor (int): run for the given amount of milliseconds, exit with full session flush

-runforf (int): run for the given amount of milliseconds, exit with fast session flush

-runforx (int): run for the given amount of milliseconds and exit with no cleanup

-runfors (int): run for the given amount of milliseconds and exit with segfault (tests)

-runforl (int): run for the given amount of milliseconds and wait forever at end (tests)

-stats: print stats after execution

-graph: print graph after execution

-qe: enable quick exit (no mem cleanup)

-k: enable keyboard interaction from command line

-r (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

-seps (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))

-i,-src (string): specify an input file - see filters help (-h doc)

-o,-dst (string): specify an output file - see filters help (-h doc)

-ib (string): specify an input file to wrap as GF_FileIO object (testing of GF_FileIO)

-ibx (string): specify an input file to wrap as GF_FileIO object without caching (testing of GF_FileIO)

-ob (string): specify an output file to wrap as GF_FileIO object (testing of GF_FileIO)

-cl: force complete mode when no link directive are set - see filters help (-h doc)

-sid: force source IDs to be present when attempting to link - see filters help (-h doc)

-step: test step mode in non-blocking session

-h,-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 )
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

-p (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

-alias (string): assign a new alias or remove an alias. Can be specified several times. See alias usage (-h alias)

-aliasdoc (string): assign documentation for a given alias (optional). Can be specified several times

-cache-info: show cache info. Argument can be:

absent: the entire cache is inspected
B: filter entries created after B, with B a number of seconds prior to now or a date (0 means now)
B;C: filter entries created after B but before C, with B and C either a number of seconds prior to now or a date
- If B is 0, min time is UTC=0
- If C is 0, max time is now

The argument syntax is the same for all cache options

-cache-unflat: revert all items in GPAC cache directory to their original name and server path

-cache-list: list entries in cache

-cache-clean (int): clean cache

-js (string): specify javascript file to use as controller of filter session

-wc: write all core options in the config file unless already set

-we: write all file extensions in the config file unless already set (useful to change some default file extensions)

-wf: write all filter options in the config file unless already set

-wfx: write all filter options and all meta filter arguments in the config file unless already set (large config file !)

-xopt: unrecognized options and filters declaration following this option are ignored - used to pass arguments to GUI

-creds (string): setup credentials as used by servers

-rv: return absolute value of GPAC internal error instead of 1 when error

The following libgpac core options allow customizing the filter session:

-dbg-edges: 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)

-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

-step-link: load filters one by one when solvink a link instead of loading all filters for the solved path

-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

-check-props: check known property types upon assignment and PID vs packet types upon fetch (in test mode, exit with error code 5 if mismatch)

Using Aliases¶

The gpac command line can become quite complex when many sources or filters are used. In order to simplify this, an alias system is provided.

To assign an alias, use the syntax gpac -alias="NAME VALUE".

NAME: shall be a single string, with no space.
VALUE: the list of argument this alias replaces. If not set, the alias is destroyed

When parsing arguments, the alias will be replace by its value.
Example

gpac -alias="output aout vout"

This allows later audio and video playback using gpac -i src.mp4 output

Aliases can use arguments from the command line. The allowed syntaxes are:

@{a}: replaced by the value of the argument with index a after the alias
@{a,b}: replaced by the value of the arguments with index a and b
@{a:b}: replaced by the value of the arguments between index a and b
@{-a,b}: replaced by the value of the arguments with index a and b, inserting a list separator (comma by default) between them
@{-a:b}: replaced by the value of the arguments between index a and b, inserting a list separator (comma by default) between them
@{+a,b}: clones the parent word in the alias for a and b, replacing this pattern in each clone by the corresponding argument
@{+a:b}: clones the parent word in the alias for each argument between index a and b, replacing this pattern in each clone by the corresponding argument

The specified index can be:

forward index: a strictly positive integer, 1 being the first argument after the alias
backward index: the value 'n' (or 'N') to indicate the last argument on the command line. This can be followed by -x to rewind arguments (e.g. @{n-1} is the before last argument)

Before solving aliases, all option arguments are moved at the beginning of the command line. This implies that alias arguments cannot be options.
Arguments not used by any aliases are kept on the command line, other ones are removed

Example

-alias="foo src=@{N} dst=test.mp4"

The command gpac foo f1 f2 expands to gpac src=f2 dst=test.mp4 f1
Example

-alias="list: inspect src=@{+:N}"

The command gpac list f1 f2 f3 expands to gpac inspect src=f1 src=f2 src=f3
Example

-alias="list inspect src=@{+2:N}"

The command gpac list f1 f2 f3 expands to gpac inspect src=f2 src=f3 f1
Example

-alias="plist aout vout flist:srcs=@{-,N}"

The command gpac plist f1 f2 f3 expands to gpac aout vout flist:srcs="f1,f2,f3"

Alias documentation can be set using gpac -aliasdoc="NAME VALUE", with NAME the alias name and VALUE the documentation.
Alias documentation will then appear in gpac help.

User Credentials¶

Some servers in GPAC can use user-based and group-based authentication.
The information is stored by default in the file users.cfg located in the GPAC profile directory.
The file can be overwritten using the -users option.

By default, this file does not exist until at least one user has been configured.

The creds option allows inspecting or modifying the users and groups information. The syntax for the option value is:

show or no value: prints the users.cfg file
reset: deletes the users.cfg file (i.e. deletes all users and groups)
NAME: show information of user NAME
+NAME: adds user NAME
+NAME:I1=V1[,I2=V2]: sets info I1 with value V1 to user NAME. The info name password resets password without prompt.
-NAME: removes user NAME
_NAME: force password change of user NAME
@NAME: show information of group NAME
@+NAME[:u1[,u2]]: adds group NAME if not existing and adds specified users to group
@-NAME:u1[,u2]: removes specified users from group NAME
@-NAME: removes group NAME

By default all added users are members of the group users.
Passwords are not stored, only a SHA256 hash is stored.

Servers using authentication rules can use a configuration file instead of a directory name.
This configuration file is organized in sections, each section name describing a directory.
Example

[somedir]  
ru=foo  
rg=bar

The following keys are defined per directory, but may be ignored by the server depending on its operation mode:

ru: comma-separated list of user names with read access to the directory
rg: comma-separated list of group names with read access to the directory
wu: comma-separated list of user names with write access to the directory
wg: comma-separated list of group names with write access to the directory
mcast: comma-separated list of user names with multicast creation rights (RTSP server only)
filters: comma-separated list of filter names for which the directory is valid. If not found or all, applies to all filters

Rights can be configured on sub-directories by adding sections for the desired directories.
Example

[d1]  
rg=bar  
[d1/d2]  
ru=foo

With this configuration:

the directory d1 will be readable by all members of group bar
the directory d1/d2 will be readable by user foo only

Servers in GPAC currently only support the Basic HTTP authentication scheme, and should preferably be run over TLS.

Defer test mode¶

This mode can be used to test loading filters one by one and asking for link resolution explicitly.
This is mostly used to reproduce how sessions are build in more complex applications.

The options rl, pi, pl and pd allow addressing a filter by index F in a list.

if the option is suffixed with an x (e.g. rlx=), F=0 means the last filter in the list of filters in the session
otherwise, F=0 means the last filter declared before the option

The relink options -rl and -rlx always flush the session (run until no more tasks are scheduled).
The last run can be omitted.

Example

gpac -dl -np -i SRC reframer -g -rl -g inspect -g -rl

This will load SRC and reframer, print the graph (no connection), relink SRC, print the graph (connection to reframer), insert inspect, print the graph (no connection), relink reframer and run. No play event is sent here.
Example

gpac -dl -np -i SRC reframer inspect:deep -g -rl=2 -g -rl -se

This will load SRC, reframer and inspect, print the graph (no connection), relink SRC, print the graph (connection to reframer), print the graph (no connection), relink reframer, send play and run.

Linking can be done once filters are loaded, using the syntax @F@SRC or @@F@SRC:

@F indicates the destination filter using a 0-based index F starting from the last laoded filter, e.g. @0 indicates the last loaded filter.
@@F indicates the target filter using a 0-based index F starting from the first laoded filter, e.g. @@1 indicates the second loaded filter.
@SRCor @@SRC: same syntax as link directives

Sources MUST be set before relinking outputs using (-rl)[].
Example

gpac -dl -i SRC F1 F2 [...] @1@2 @0@2

This will set SRC as source to F1 and SRC as source to F2 after loading all filters.

The following options are used in defer mode:

-dl: enable defer linking mode for step-by-step graph building tests

-np: prevent play event from sinks

-rl[=F] (string): relink outputs of filter F (default 1)

-wl[=F] (string): same as -rl but does not flush session)

-pi=[+|-][F[:i]] (string): print PID properties (all or of index i) of filter F (default 0)

if prefixed with -: only list PIDs
if prefixed with +: also print PID info

-pl=[+][F[:i]]@NAME (string): probe filter chain from filter F (default 0) to the given filter NAME:

if prefixed with +: print all known chains and their priorities

-pd=[F[:i]] (string): print possible PID destinations (all or of index i) of filter F (default 0)

ENCRYPT

General Usage of gpac¶

Using Aliases¶

User Credentials¶

Defer test mode¶