| gpac(1) | GPAC | gpac(1) |
gpac - GPAC command-line filter session manager
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) or of
libgpac (see gpac -hx core)
- 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)
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, .I -o, -dst and .I -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:
The following libgpac core options allow customizing the filter session:
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.
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 .I -users option.
By default, this file does not exist until at least one user has been configured.
The .I 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 descibing
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.
GPAC uses a configuration file to modify default options of
libgpac and filters. This file is called GPAC.cfg and is located:
- on Windows platforms, in C:UsersODatar in C:Program FilesGPAC.
- on iOS platforms, in a .gpac folder in the app storage directory.
- on Android platforms, in /sdcard/GPAC/ if this directory exists, otherwise
in /data/data/io.gpac.gpac/GPAC.
- on other platforms, in a $HOME/.gpac/.
Applications in GPAC can also specify a different configuration
file through the .I -p profile option. EX gpac -p=foo []
This will load configuration from $HOME/.gpac/foo/GPAC.cfg, creating it if
needed.
The reserved name 0 is used to disable configuration file writing.
The configuration file is structured in sections, each made of one
or more keys:
- section foo is declared as [foo]
- key bar with value N is declared as bar=N0 The key value N is not
interpreted and always handled as ASCII text.
By default the configuration file only holds a few system specific
options and directories. It is possible to serialize the entire set of
options to the configuration file, using .I -wc .I -wf.
This should be avoided as the resulting configuration file size will be quite
large, hence larger memory usage for the applications.
The options specified in the configuration file may be overridden by the
values in restrict.cfg file located in GPAC share system directory (e.g.
/usr/share/gpac or C:Program FilesGPAC), if present; this allows enforcing
system-wide configuration values.
Note: The methods describe in this section apply to any application in GPAC
transferring their arguments to libgpac. This is the case for gpac and
MP4Box.
The options from libgpac core can also be assigned though the
config file from section core using option name without initial dash as key
name.
Example
[core]
threads=2
Setting this in the config file is equivalent to using -threads=2.
The options specified at prompt overrides the value of the config file.
It is possible to alter the default value of a filter option by
modifying the configuration file. Filter foo options are stored in section
[filter@foo], using option name and value as key-value pair. Options
specified through the configuration file do not take precedence over options
specified at prompt or through alias.
Example
[filter@rtpin]
interleave=yes
This will force the rtp input filter to always request RTP over
RTSP by default.
To generate a configuration file with all filters options serialized, use .I
-wf.
It is possible to specify options global to multiple filters using
--OPTNAME=VAL. Global options do not override filter options but take
precedence over options loaded from configuration file.
This will set option OPTNAME, when present, to VAL in any loaded filter.
Example
--buffer=100 -i file vout aout
This is equivalent to specifying vout:buffer=100 aout:buffer=100.
Example
--buffer=100 -i file vout aout:buffer=10
This is equivalent to specifying vout:buffer=100 aout:buffer=10.
Warning: This syntax only applies to regular filter options. It cannot be used
with builtin shortcuts (gfreg, enc, ...).
Meta-filter options can be set in the same way using the syntax
--OPT_NAME=VAL.
Example
--profile=Baseline -i file.cmp -o dump.264
This is equivalent to specifying -o dump.264:profile=Baseline.
For both syntaxes, it is possible to specify the filter registry
name of the option, using --FNAME:OPTNAME=VAL or --FNAME@OPTNAME=VAL.
In this case the option will only be set for filters which are instances of
registry FNAME. This is used when several registries use same option names.
Example
--flist@timescale=100 -i plist1 -i plist2 -o live.mpd
This will set the timescale option on the playlists filters but not on the dasher filter.
You can independently log different tools involved in a
session.
log_args is formatted as a colon (':') separated list of
toolX[:toolZ]@levelX
levelX can be one of:
* quiet: skip logs
* error: logs only error messages
* warning: logs error+warning messages
* info: logs error+warning+info messages
* debug: logs all messages
toolX can be one of:
* core: libgpac core
* mutex: log all mutex calls
* mem: GPAC memory tracker
* module: GPAC modules (av out, font engine, 2D rasterizer)
* filter: filter session debugging
* sched: filter session scheduler debugging
* codec: codec messages (used by encoder and decoder filters)
* coding: bitstream formats (audio, video, scene)
* container: container formats (ISO File, MPEG-2 TS, AVI, ...) and
multiplexer/demultiplexer filters
* network: TCP/UDP sockets and TLS
* http: HTTP traffic
* cache: HTTP cache subsystem
* rtp: RTP traffic
* dash: HTTP streaming logs
* route: ROUTE (ATSC3) debugging
* media: messages from generic filters and reframer/rewriter filters
* parser: textual parsers (svg, xmt, bt, ...)
* mmio: I/O management (AV devices, file, pipes, OpenGL)
* audio: audio renderer/mixer/output
* script: script engine except console log
* console: script console log
* scene: scene graph and scene manager
* compose: composition engine (2D, 3D, etc)
* ctime: media and SMIL timing info from composition engine
* interact: interaction messages (UI events and triggered DOM events and
VRML route)
* rti: run-time stats of compositor
* all: all tools logged - other tools can be specified afterwards.
The special keyword ncl can be set to disable color logs.
The special keyword strict can be set to exit at first error.
Example
-logs=all@info:dash@debug:ncl
This moves all log to info level, dash to debug level and
disable color logs
Filters are configurable processing units consuming and producing
data packets. These packets are carried between filters through a data
channel called PID. A PID is in charge of allocating/tracking data packets,
and passing the packets to the destination filter(s). A filter output PID
may be connected to zero or more filters. This fan-out is handled internally
by GPAC (no such thing as a tee filter in GPAC).
Note: When a PID cannot be connected to any filter, a warning is thrown and
all packets dispatched on this PID will be destroyed. The session may
however still run, unless .I -full-link is set.
Each output PID carries a set of properties describing the data it delivers (e.g. width, height, codec, ...). Properties can be built-in (see gpac -h props ), or user-defined. Each PID tracks its properties changes and triggers filter reconfiguration during packet processing. This allows the filter chain to be reconfigured at run time, potentially reloading part of the chain (e.g. unload a video decoder when switching from compressed to uncompressed sources).
Each filter exposes a set of argument to configure itself, using property types and values described as strings formatted with separators. This help is given with default separator sets :=#,@ to specify filters, properties and options. Use .I -seps to change them.
* boolean: formatted as yes,true,1 or no,false,0
* enumeration (for filter arguments only): must use the syntax given in the
argument description, otherwise value 0 (first in enum) is assumed.
* 1-dimension (numbers, floats, ints...): formatted as value[unit], where unit
can be k,K (x 1000) or m,M (x 1000000) or g,G (x 1000000000) or sec (x 1000)
or min (x 60000). +I means max float/int/uint value, -I min float/int/uint
value.
* fraction: formatted as num/den or num-den or num, in which case the
denominator is 1 if num is an integer, or 1000000 if num is a floating-point
value.
* unsigned 32 bit integer: formatted as number or hexadecimal using the format
0xAABBCCDD.
* N-dimension (vectors): formatted as DIM1xDIM2[xDIM3[xDIM4]] values, without
unit multiplier.
* For 2D integer vectors, the following resolution names can be used: 360,
480, 576, 720, 1080, hd, 2k, 2160, 4k, 4320, 8k
* string: formatted as:
* `value`: copies value to string.
* `file@FILE`: load string from local FILE (opened in binary mode).
* `bxml@FILE`: binarize XML from local FILE and set property type to data -
see https://wiki.gpac.io/NHML-Format.
* data: formatted as:
* `size@address`: constant data block, not internally copied; size gives the
size of the block, address the data pointer.
* `0xBYTESTRING`: data block specified in hexadecimal, internally copied.
* `file@FILE`: load data from local FILE (opened in binary mode).
* `bxml@FILE`: binarize XML from local FILE - see
https://wiki.gpac.io/NHML-Format.
* `b64@DATA`: load data from base-64 encoded DATA.
* pointer: pointer address as formatted by %p in C.
* string lists: formatted as val1,val2[,...]. Each value can also use
file@FILE syntax.
* integer lists: formatted as val1,val2[,...]
Note: The special characters in property formats (0x,/,-,+I,-I,x) cannot be
configured.
Each filter is declared by its name, with optional filter
arguments appended as a list of colon-separated name=value pairs. Additional
syntax is provided for:
* boolean: value can be omitted, defaulting to true (e.g. :noedit). Using !
before the name negates the result (e.g. :!moof_first)
* enumerations: name can be omitted, e.g. :disp=pbo is equivalent to :pbo.
When string parameters are used (e.g. URLs), it is recommended to
escape the string using the keyword gpac.
Example
filter:ARG=http://foo/bar?yes:gpac:opt=VAL
This will properly extract the URL.
Example
filter:ARG=http://foo/bar?yes:opt=VAL
This will fail to extract it and keep :opt=VAL as part of the URL.
The escape mechanism is not needed for local source, for which file existence
is probed during argument parsing. It is also not needed for builtin
protocol handlers (avin://, video://, audio://, pipe://)
For tcp:// and udp:// protocols, the escape is not needed if a trailing / is
appended after the port number.
Example
-i tcp://127.0.0.1:1234:OPT
This will fail to extract the URL and options.
Example
-i tcp://127.0.0.1:1234/:OPT
This will extract the URL and options.
Note: one trick to avoid the escape sequence is to declare the URLs option at
the end, e.g. f1:opt1=foo:url=http://bar, provided you have only one URL
parameter to specify on the filter.
It is possible to disable option parsing (for string options) by
duplicating the separator.
Example
filter::opt1=UDP://IP:PORT/:someopt=VAL::opt2=VAL2
This will pass UDP://IP:PORT/:someopt=VAL to opt1 without inspecting it, and VAL2 to opt2.
Source and sink filters do not need to be addressed by the filter
name, specifying src= or dst= instead is enough. You can also use the syntax
-src URL or -i URL for sources and -dst URL or -o URL for destination, this
allows prompt completion in shells.
Example
"src=file.mp4" or "-src file.mp4" or "-i
file.mp4"
This will find a filter (for example fin) able to load file.mp4.
The same result can be achieved by using fin:src=file.mp4.
Example
"dst=dump.yuv" or "-dst dump.yuv" or "-o
dump.yuv"
This will dump the video content in dump.yuv. The same result can be achieved by using fout:dst=dump.yuv.
Specific source or sink filters may also be specified using filterName:src=URL or filterName:dst=URL.
The src= and dst= syntaxes can also be used in alias for dynamic argument cloning (see gpac -hx alias).
There is a special option called gfreg which allows specifying
preferred filters to use when handling URLs.
Example
src=file.mp4:gfreg=ffdmx,ffdec
This will use ffdmx to read file.mp4 and ffdec to decode it.
This can be used to test a specific filter when alternate filter chains are
possible.
By default filters chain will be resolved without any
decoding/encoding if the destination accepts the desired format. Otherwise,
decoders/encoders will be dynamically loaded to perform the conversion,
unless dynamic resolution is disabled. There is a special shortcut filter
name for encoders enc allowing to match a filter providing the desired
encoding. The parameters for enc are:
* c=NAME: identifies the desired codec. NAME can be the GPAC codec name or the
encoder instance for ffmpeg/others
* b=UINT, rate=UINT, bitrate=UINT: indicates the bitrate in bits per second
* g=UINT, gop=UINT: indicates the GOP size in frames
* pfmt=NAME: indicates the target pixel format name (see properties (-h props)
) of the source, if supported by codec
* all_intra=BOOL: indicates all frames should be intra frames, if supported by
codec
Other options will be passed to the filter if it accepts generic
argument parsing (as is the case for ffmpeg).
The shortcut syntax c=TYPE (e.g. c=aac:opts) is also supported.
Example
gpac -i dump.yuv:size=320x240:fps=25
enc:c=avc:b=150000:g=50:cgop=true:fast=true -o raw.264
This creates a 25 fps AVC at 175kbps with a gop duration of 2 seconds, using closed gop and fast encoding settings for ffmpeg.
The inverse operation (forcing a decode to happen) is possible
using the reframer filter.
Example
gpac -i file.mp4 reframer:raw=av -o null
This will force decoding media from file.mp4 and trash (send to null) the result (doing a decoder benchmark for example).
When a filter uses an option defined as a string using the same
separator character as gpac, you can either modify the set of separators, or
escape the separator by duplicating it. The options enclosed by duplicated
separator are not parsed. This is mostly used for meta filters, such as
ffmpeg, to pass options to sub-filters such as libx264 (cf x264opts
parameter).
Example
f:a=foo:b=bar
This will set option a to foo and option b to bar on the filter.
Example
f::a=foo:b=bar
This will set option a to foo:b=bar on the filter.
Example
f:a=foo::b=bar:c::d=fun
This will set option a to foo, b to bar:c and the option d to fun on the filter.
Each filter exposes one or more sets of capabilities, called
capability bundle, which are property type and values that must be matched
or excluded by connecting PIDs.
To check the possible sources and destination for a filter FNAME, use gpac -h
links FNAME
The filter graph resolver uses this information together with the PID properties to link the different filters.
Link directives, when provided, specify which source a filter can
accept connections from.
They do not specify which destination a filter can connect to.
When no link instructions are given (see below), the default
linking strategy used is either implicit mode (default in gpac) or complete
mode (if .I -cl is set).
Each PID is checked for possible connection to all defined filters, in their
declaration order.
For each filter DST accepting a connection from the PID, directly or with
intermediate filters:
- if DST filter has link directives, use them to allow or reject PID
connection.
- otherwise, if complete mode is enabled, allow connection..
- otherwise (implicit mode):
- if DST is not a sink and is the first matching filter with no link
directive, allow connection.
- otherwise, if DST is not a sink and is not the first matching filter with
no link directive, reject connection.
- otherwise (DST is a sink) and no previous connections to a non-sink filter,
allow connection.
In all linking modes, a filter can prevent being linked to a
filter with no link directives by setting RSID option on the filter.
This is typically needed when dynamically inserting/removing filters in an
existing session where some filters have no ID defined and are not desired
for the inserted chain.
Example
gpac -i file.mp4 c=avc -o output
With this setup in implicit mode:
- if the file has a video PID, it will connect to enc but not to output. The
output PID of enc will connect to output.
- if the file has other PIDs than video, they will connect to output, since
this enc filter accepts only video.
Example
gpac -cl -i file.mp4 c=avc -o output
With this setup in complete mode:
- if the file has a video PID, it will connect both to enc and to output, and
the output PID of enc will connect to output.
- if the file has other PIDs than video, they will connect to output.
Furthermore in implicit mode, filter connections are restricted to
filters defined between the last source and the sink(s).
Example
gpac -i video1 reframer:saps=1 -i video2 ffsws:osize=128x72 -o output
This will connect:
- video1 to reframer then reframer to output but will prevent reframer to
ffsws connection.
- video2 to ffsws then ffsws to output but will prevent video2 to reframer
connection.
Example
gpac -i video1 -i video2 reframer:saps=1 ffsws:osize=128x72 -o output
This will connect video1 AND video2 to reframer->ffsws->output
The implicit mode allows specifying linear processing chains (no
PID fan-out except for final output(s)) without link directives, simplifying
command lines for common cases.
Warning: Argument order really matters in implicit mode!
Example
gpac -i file.mp4 c=avc c=aac -o output
If the file has a video PID, it will connect to c=avc but not to
output. The output PID of c=avc will connect to output.
If the file has an audio PID, it will connect to c=aac but not to output. The
output PID of c=aac will connect to output.
If the file has other PIDs than audio or video, they will connect to
output.
Example
gpac -i file.mp4 ffswf=osize:128x72 c=avc resample=osr=48k c=aac -o output
This will force:
- SRC(video)->ffsws->enc(video)->output and prevent
SRC(video)->output, SRC(video)->enc(video) and ffsws->output
connections which would happen in complete mode.
- SRC(audio)->resample->enc(audio)->output and prevent
SRC(audio)->output, SRC(audio)->enc(audio) and resample->output
connections which would happen in complete mode.
Link between filters may be manually specified. The syntax is an @
character optionally followed by an integer (0 if omitted).
This indicates that the following filter specified at prompt should be linked
only to a previous listed filter.
The optional integer is a 0-based index to the previous filter declarations, 0
indicating the previous filter declaration, 1 the one before the previous
declaration, ...).
If @@ is used instead of @, the optional integer gives the filter index
starting from the first filter (index 0) specified in command line.
Several link directives can be given for a filter.
Example
fA fB @1 fC
This indicates that fC only accepts inputs from fA.
Example
fA fB fC @1 @0 fD
This indicates that fD only accepts inputs from fB and fC.
Example
fA fB fC ... @@1 fZ
This indicates that fZ only accepts inputs from fB.
The @ link directive is just a quick shortcut to set the following
filter arguments:
* FID=name: assigns an identifier to the filter
* SID=name1[,name2...]: sets a list of filter identifiers, or sourceIDs,
restricting the list of possible inputs for a filter.
Example
fA fB @1 fC
This is equivalent to fA:FID=1 fB fC:SID=1.
Example
fA:FID=1 fB fC:SID=1
This indicates that fC only accepts input from fA, but fB might
accept inputs from fA.
Example
fA:FID=1 fB:FID=2 fC:SID=1 fD:SID=1,2
This indicates that fD only accepts input from fA and fB and fC
only from fA
Note: A filter with sourceID set cannot get input from filters with no
IDs.
A sourceID name can be further extended using fragment identifier
(# by default):
* name#PIDNAME: accepts only PID(s) with name PIDNAME
* name#TYPE: accepts only PIDs of matching media type. TYPE can be audio,
video, scene, text, font, meta
* name#TYPEN: accepts only N (1-based index) PID of matching type from source
(e.g. video2 to only accept second video PID)
* name#TAG=VAL: accepts the PID if its parent filter has no tag or a tag
matching VAL
* name#P4CC=VAL: accepts only PIDs with builtin property of type P4CC and
value VAL.
* name#PName=VAL: same as above, using the builtin name corresponding to the
property.
* name#AnyName=VAL: same as above, using the name of a non built-in property.
* name#Name=OtherPropName: compares the value with the value of another
property of the PID. The matching will fail if the value to compare to is
not present or different from the value to check. The property to compare
with shall be a built-in property.
If the property is not defined on the PID, the property is matched. Otherwise,
its value is checked against the given value.
The following modifiers for comparisons are allowed (for any
fragment format using =):
* name#P4CC=!VAL: accepts only PIDs with property NOT matching VAL.
* name#P4CC-VAL: accepts only PIDs with property strictly less than VAL (only
for 1-dimension number properties).
* name#P4CC+VAL: accepts only PIDs with property strictly greater than VAL
(only for 1-dimension number properties).
A sourceID name can also use wildcard or be empty to match a
property regardless of the source filter.
Example
fA fB:SID=*#ServiceID=2
fA fB:SID=#ServiceID=2
This indicates to match connection between fA and fB only for PIDs
with a ServiceID property of 2.
These extensions also work with the LINK @ shortcut.
Example
fA fB @1#video fC
This indicates that fC only accepts inputs from fA, and of type
video.
Example
gpac -i img.heif @#ItemID=200 vout
This indicates to connect to vout only PIDs with ItemID property
equal to 200.
Example
gpac -i vid.mp4 @#PID=1 vout
This indicates to connect to vout only PIDs with ID property equal
to 1.
Example
gpac -i vid.mp4 @#Width=640 vout
This indicates to connect to vout only PIDs with Width property
equal to 640.
Example
gpac -i vid.mp4 @#Width-640 vout
This indicates to connect to vout only PIDs with Width property
less than 640
Example
gpac -i vid.mp4 @#ID=ItemID#ItemNumber=1 vout
This will connect to vout only PID with an ID property equal to ItemID property (keep items, discard tracks) and an Item number of 1 (first item).
Multiple fragment can be specified to check for multiple PID
properties.
Example
gpac -i vid.mp4 @#Width=640#Height+380 vout
This indicates to connect to vout only PIDs with Width property equal to 640 and Height greater than 380.
Warning: If a PID directly connects to one or more explicitly
loaded filters, no further dynamic link resolution will be done to connect
it to other filters with no sourceID set. Link directives should be
carefully setup.
Example
fA @ reframer fB
If fB accepts inputs provided by fA but reframer does not, this
will link fA PID to fB filter since fB has no sourceID.
Since the PID is connected, the filter engine will not try to solve a link
between fA and reframer.
An exception is made for local files: by default, a local file
destination will force a remultiplex of input PIDs from a local file.
Example
gpac -i file.mp4 -o dump.mp4
This will prevent direct connection of PID of type file to dst file.mp4, remultiplexing the file.
The special option nomux is used to allow direct connections
(ignored for non-sink filters).
Example
gpac -i file.mp4 -o dump.mp4:nomux
This will result in a direct file copy.
This only applies to local files destination. For pipes, sockets
or other file outputs (HTTP, ROUTE):
- direct copy is enabled by default
- nomux=0 can be used to force remultiplex
Filters may be assigned to a sub-session using :FS=N, with N a
positive integer.
Filters belonging to different sub-sessions may only link to each-other:
- if explicitly allowed through sourceID directives (@ or SID)
- or if they have the same sub-session identifier
This is mostly used for implicit mode in gpac: each first source
filter specified after a sink filter will trigger a new sub-session.
Example
gpac -i in1.mp4 -i in2.mp4 -o out1.mp4 -o out2.mp4
This will result in both inputs multiplexed in both outputs.
Example
gpac -i in1.mp4 -o out1.mp4 -i in2.mp4 -o out2.mp4
This will result in in1 mixed to out1 and in2 mixed to out2, these last two filters belonging to a different sub-session.
Unless explicitly disabled (see .I -max-chain), the filter engine
will resolve implicit or explicit (LINK) connections between filters and
will allocate any filter chain required to connect the filters. In doing so,
it loads new filters with arguments inherited from both the source and the
destination.
Example
gpac -i file.mp4:OPT -o file.aac -o file.264
This will pass the :OPT to all filters loaded between the source
and the two destinations.
Example
gpac -i file.mp4 -o file.aac:OPT -o file.264
This will pass the :OPT to all filters loaded between the source
and the file.aac destination.
Note: the destination arguments inherited are the arguments placed AFTER the
dst= option.
Example
gpac -i file.mp4 fout:OPTFOO:dst=file.aac:OPTBAR
This will pass the :OPTBAR to all filters loaded between file.mp4
source and file.aac destination, but not OPTFOO.
Arguments inheriting can be stopped by using the keyword gfloc: arguments
after the keyword will not be inherited.
Example
gpac -i file.mp4 -o file.aac:OPTFOO:gfloc:OPTBAR -o file.264
This will pass :OPTFOO to all filters loaded between file.mp4
source and file.aac destination, but not OPTBAR
Arguments are by default tracked to check if they were used by the filter
chain, and a warning is thrown if this is not the case.
It may be useful to specify arguments which may not be consumed depending on
the graph resolution; the specific keyword gfopt indicates that arguments
after the keyword will not be tracked.
Example
gpac -i file.mp4 -o file.aac:OPTFOO:gfopt:OPTBAR -o file.264
This will warn if OPTFOO is not consumed, but will not track OPTBAR.
A filter may be assigned a name (for inspection purposes, not inherited) using :N=name option. This name is not used in link resolution and may be changed at runtime by the filter instance.
A filter may be assigned a tag (any string) using :TAG=name option. This tag does not need to be unique, and can be used to exclude filter in link resolution. Tags are not inherited, therefore dynamically loaded filters never have a tag.
Destination URLs can be dynamically constructed using templates.
Pattern $KEYWORD$ is replaced in the template with the resolved value and
$KEYWORD%%0Nd$ is replaced in the template with the resolved integer, padded
with up to N zeros if needed.
KEYWORD is case sensitive, and may be present multiple times in the string.
Supported KEYWORD:
* num: replaced by file number if defined, 0 otherwise
* PID: ID of the source PID
* URL: URL of source file
* File: path on disk for source file; if not found, use URL if set, or PID
name otherwise
* Type: name of stream type of PID (video, audio ...)
* p4cc=ABCD: uses PID property with 4CC value ABCD
* pname=VAL: uses PID property with name VAL
* cts, dts, dur, sap: uses properties of first packet in PID at template
resolution time
* OTHER: locates property 4CC for the given name, or property name if no 4CC
matches.
$$ is an escape for $
Templating can be useful when encoding several qualities in one
pass.
Example
gpac -i dump.yuv:size=640x360 vcrop:wnd=0x0x320x180 c=avc:b=1M @2 c=avc:b=750k
-o dump_$CropOrigin$x$Width$x$Height$.264:clone
This will create a cropped version of the source, encoded in AVC at 1M, and a full version of the content in AVC at 750k. Outputs will be dump_0x0x320x180.264 for the cropped version and dump_0x0x640x360.264 for the non-cropped one.
When a filter accepts a single connection and has a connected
input, it is no longer available for dynamic resolution. There may be cases
where this behavior is undesired. Take a HEIF file with N items and do:
Example
gpac -i img.heif -o dump_$ItemID$.jpg
In this case, only one item (likely the first declared in the
file) will connect to the destination.
Other items will not be connected since the destination only accepts one input
PID.
There is a special option clone allowing filters to be cloned with the same
arguments. The cloned filters have the same ID as the original one.
Example
gpac -i img.heif -o dump_$ItemID$.jpg:clone
In this case, the destination will be cloned for each item, and
all will be exported to different JPEGs thanks to URL templating.
Example
gpac -i vid.mpd c=avc:FID=1:clone -o transcode.mpd:SID=1
In this case, the encoder will be cloned for each video PIDs in the source, and the destination will only use PIDs coming from the encoders.
When implicit linking is enabled, all filters are by default
clonable. This allows duplicating the processing for each PIDs of the same
type.
Example
gpac -i dual_audio resample:osr=48k c=aac -o dst
The resampler filter will be cloned for each audio PID, and the
encoder will be cloned for each resampler output.
You can explicitly deactivate the cloning instructions:
Example
gpac -i dual_audio resample:osr=48k:clone=0 c=aac -o dst
The first audio will connect to the resample filter, the second to the enc filter and the resample output will connect to a clone of the enc filter.
There can be cases where the number of desired outputs depends on
the source content, for example dumping a multiplex of N services into N
files. When the destination involves multiplexing the input PIDs, the :clone
option is not enough since the multiplexer will always accept the input
PIDs.
To handle this, it is possible to use a PID property name in the sourceID of a
filter with the value * or an empty value. In this case, whenever a new PID
with a new value for the property is found, the filter with such sourceID
will be dynamically cloned.
Warning: This feature should only be called with a single property set to *
(or empty) per source ID, results are undefined otherwise.
Example
gpac -i source.ts -o file_$ServiceID$.mp4:SID=*#ServiceID=*
gpac -i source.ts -o file_$ServiceID$.mp4:SID=#ServiceID=
In this case, each new ServiceID value found when connecting PIDs to the destination will create a new destination file.
Cloning in implicit linking mode applies to output as well:
Example
gpac -i dual_audio -o dst_$PID$.aac
Each audio track will be dumped to aac (potentially reencoding if needed).
It is possible to define properties on output PIDs that will be
declared by a filter. This allows tagging parts of the graph with different
properties than other parts (for example ServiceID). The syntax is the same
as filter option, and uses the fragment separator to identify properties,
e.g. #Name=Value.
This sets output PIDs property (4cc, built-in name or any name) to the given
value. Value can be omitted for boolean (defaults to true, e.g. :#Alpha).
Non built-in properties are parsed as follows:
- file@FOO will be declared as string with a value set to the content of FOO.
- bxml@FOO will be declared as data with a value set to the binarized content
of FOO.
- FOO will be declared as string with a value set to FOO.
- TYPE@FOO will be parsed according to TYPE. If the type is not recognized,
the entire value is copied as string. See gpac -h props for defined
types.
User-assigned PID properties on filter fA will be inherited by all
filters dynamically loaded to solve fA -> fB connection.
If fB also has user-assigned PID properties, these only apply starting from fB
in the chain and are not inherited by filters between fA and fB.
Warning: Properties are not filtered and override the properties
of the filter's output PIDs, be careful not to break the session by
overriding core properties such as width/height/samplerate/... !
Example
gpac -i v1.mp4:#ServiceID=4 -i v2.mp4:#ServiceID=2 -o dump.ts
This will multiplex the streams in dump.ts, using ServiceID 4 for PIDs from v1.mp4 and ServiceID 2 for PIDs from v2.mp4.
PID properties may be conditionally assigned by checking other PID
properties. The syntax uses parenthesis (not configurable) after the
property assignment sign:
#Prop=(CP=CV)VAL
This will assign PID property Prop to VAL for PIDs with property CP equal to
CV.
#Prop=(CP=CV)VAL,(CP2=CV2)VAL2
This will assign PID property Prop to VAL for PIDs with property CP equal to
CV, and to VAL2 for PIDs with property CP2 equal to CV2.
#Prop=(CP=CV)(CP2=CV2)VAL
This will assign PID property Prop to VAL for PIDs with property CP equal to
CV and property CP2 equal to CV2.
#Prop=(CP=CV)VAL,()DEFAULT
This will assign PID property Prop to VAL for PIDs with property CP equal to
CV, or to DEFAULT for other PIDs.
The condition syntax is the same as source ID fragment syntax.
Note: When set, the default value (empty condition) always matches the PID,
therefore it should be placed last in the list of conditions.
Example
gpac -i source.mp4:#MyProp=(audio)"Super Audio",(video)"Super
Video"
This will assign property MyProp to Super Audio for audio PIDs and
to Super Video for video PIDs.
Example
gpac -i source.mp4:#MyProp=(audio1)"Super Audio"
This will assign property MyProp to Super Audio for first audio
PID declared.
Example
gpac -i source.mp4:#MyProp=(Width+1280)HD
This will assign property MyProp to HD for PIDs with property Width greater than 1280.
It is possible to use a file to define options of a filter, by
specifying the target file name as an option without value, i.e.
:myopts.txt.
Warning: Only local files are allowed.
An option file is a simple text file containing one or more options or PID
properties on one or more lines.
- A line beginning with "//" is a comment and is ignored (not
configurable).
- A line beginning with ":" indicates an escaped option (the entire
line is parsed as a single option).
Options in an option file may point to other option files, with a maximum
redirection level of 5.
An option file declaration (filter:myopts.txt) follows the same inheritance
rules as regular options.
Example
gpac -i source.mp4:myopts.txt:foo=bar -o dst
Any filter loaded between source.mp4 and dst will inherit both myopts.txt and foo options and will resolve options and PID properties given in myopts.txt.
Some specific keywords are replaced when processing filter
options.
Warning: These keywords do not apply to PID properties. Multiple keywords
cannot be defined for a single option.
Defined keywords:
* $GSHARE: replaced by system path to GPAC shared directory (e.g.
/usr/share/gpac)
* $GJS: replaced by the first path from global share directory and paths set
through .I -js-dirs that contains the file name following the macro, e.g.
$GJS/source.js
* $GDOCS: replaced by system path to:
- application document directory for iOS
- EXTERNAL_STORAGE environment variable if present or /sdcard otherwise for
Android
- user home directory for other platforms
* $GLANG: replaced by the global config language option .I -lang
* $GUA: replaced by the global config user agent option .I -user-agent
* $GINC(init_val[,inc]): replaced by init_val and increment init_val by inc
(positive or negative number, 1 if not specified) each time a new filter
using this string is created.
The $GINC construct can be used to dynamically assign numbers in
filter chains:
Example
gpac -i source.ts tssplit @#ServiceID= -o dump_$GINC(10,2).ts
This will dump first service in dump_10.ts, second service in dump_12.ts, etc...
As seen previously, the following options may be set on any
filter, but are not visible in individual filter help:
* FID: filter identifier
* SID: filter source(s) (string value)
* N=NAME: filter name (string value)
* FS: sub-session identifier (unsigned int value)
* RSID: require sourceID to be present on target filters (no value)
* TAG: filter tag (string value)
* FBT: buffer time in microseconds (unsigned int value)
* FBU: buffer units (unsigned int value)
* FBD: decode buffer time in microseconds (unsigned int value)
* clone: filter cloning flag (no value)
* nomux: enable/disable direct file copy (no value)
* gfreg: preferred filter registry names for link solving (string value)
* gfloc: following options are local to filter declaration, not inherited (no
value)
* gfopt: following options are not tracked (no value)
* gpac: argument separator for URLs (no value)
The buffer control options are used to change the default
buffering of PIDs of a filter:
- FBT controls the maximum buffer time of output PIDs of a filter
- FBU controls the maximum number of packets in buffer of output PIDs of a
filter when timing is not available
- FBD controls the maximum buffer time of input PIDs of a decoder filter,
ignored for other filters
If another filter sends a buffer requirement messages, the maximum value of FBT (resp. FBD) and the user requested buffer time will be used for output buffer time (resp. decoding buffer time).
These options can be set:
* per filter instance: fA reframer:FBU=2
* per filter class for the run: --reframer@FBU=2
* in the GPAC config file in a per-filter section: [filter@reframer]FBU=2
The default values are defined by the session default parameters -buffer-gen, buffer-units and -buffer-dec.
GPAC comes with a set of built-in filters in libgpac. It may also load external filters in dynamic libraries, located in default module folder or folders listed in .I -mod-dirs option. The files shall be named gf_* and shall export a single function RegisterFilter returning a filter register - see libgpac documentation for more details.
Built-in property types
Built-in properties for PIDs and packets listed as Name (4CC
type FLAGS): description
FLAGS can be D (droppable - see GSF multiplexer filter help), P (packet
property)
Authors: GPAC developers, see git repo history (-log)
For bug reports, feature requests, more information and source code, visit
https://github.com/gpac/gpac
build: 2.2-rev655-g65430e305-master
Copyright: (c) 2000-2022 Telecom Paris distributed under LGPL v2.1+ -
http://gpac.io
gpac-filters(1),MP4Box(1)
| 2019 | gpac |