Skip to content


jeanlf edited this page Jan 13, 2020 · 48 revisions

HOME » Filters » 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. 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.

-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)
-loop (int): loop execution of session, creating a session at each loop, mainly used for testing. If no value is given, loops forever
-runfor (int): run for the given amount of milliseconds
-stats: print stats after execution
-graph: print graph after execution
-k: enable keyboard interaction from command line
-r (string): enable reporting

  • r: runtime reporting
  • r=FA[,FB]: runtime reporting but only print given filters, eg r=mp4mxfor ISOBMFF muxer only
  • r=: only print final report

-seps (string, default: :=#,!@): set the default character sets used to seperate various arguments

  • the first char is used to seperate argument names
  • the second char, if present, is used to seperate names and values
  • the third char, if present, is used to seperate 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)

-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. 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
  • prompt: print the GPAC prompt help when running in interactive mode (see -k )
  • modules: print available modules
  • filters: print name of all available filters
  • filters:*: print name of all available filters, including meta filters
  • codecs: print the supported builtin codecs
  • props: print the supported builtin PID and packet properties
  • links: print possible connections between each supported filters.
  • links FNAME: print sources and sinks for filter FNAME (either builtin or JS filter)
  • FNAME: print filter FNAME info (multiple FNAME can be given). For meta-filters, use FNAME:INST, eg 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 and filter IO capabilities, -hx for expert options, -hh for all options and filter capbilities

-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. Reserved name 0 means a new profile, not stored to disk
-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
-uncache: revert all items in GPAC cache directory to their original name and server path
-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 !)

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, weight, src_cap_idx, dst_cap_idx)
-no-block: disable blocking mode of filters
-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 -> ] demux -> reframe -> decode -> encode -> reframe -> mux [ -> out]. Filter chains loaded for adaptation (eg 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-seperated list)
-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

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.

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 alias for each value listed, replacing in each clone with the corresponding argument
  • @{+a:b}: clones the alias for each value listed, replacing in each clone with 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 (eg @{n-1} is the before last argument)

Arguments not used by any aliases are kept on the command line, other ones are removed


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

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

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

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

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

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

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

The command gpac plist f1 f2 f3 expands to gpac aout vout plist: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.

HOME » Filters

GPAC Configuration

Configuration File
Global Options

Filters Overview

General Filters Concepts
gpac General Usage
Built-in Properties

Filters Help

Inspect packets (inspect)
Probe source (probe)
Compositor (compositor)
ISOBMFF/QT demuxer (mp4dmx)
MPEG-4 BIFS decoder (bifsdec)
MPEG-4 OD decoder (odfdec)
File input (fin)
BT/XMT/X3D loader (btplay)
HTTP input (httpin)
SVG loader (svgplay)
JPG/J2K/PNG/BMP reframer (rfimg)
PNG/JPG decoder (imgdec)
ADTS reframer (rfadts)
LATM reframer (rflatm)
MP3 reframer (rfmp3)
FAAD decoder (faad)
MAD decoder (maddec)
XVid decoder (xviddec)
OpenJPEG2000 decoder (j2kdec)
AC3 reframer (rfac3)
A52 decoder (a52dec)
AMR/EVRC reframer (rfamr)
OGG demuxer (oggdmx)
Vorbis decoder (vorbisdec)
Theora decoder (theoradec)
MPEG-2 TS demuxer (m2tsdmx)
UDP/TCP input (sockin)
OpenSVC decoder (osvcdec)
VideoToolBox decoder (vtbdec)
MPEG-4 LASeR decoder (lsrdec)
SAF demuxer (safdmx)
MPEG-DASH and HLS client (dashin)
CENC decryptor (cdcrypt)
CENC encryptor (cecrypt)
ISOBMFF/QT muxer (mp4mx)
QCP reframer (rfqcp)
H263 reframer (rfh263)
M1V/M2V/M4V reframer (rfmpgvid)
NHNT reader (nhntr)
NHML parser (nhmlr)
AVC/HEVC reframer (rfnalu)
MPEG PS demuxer (m2psdmx)
AVI demuxer (avidmx)
Subtitle loader (txtin)
TTXT/TX3G decoder (ttxtdec)
WebVTT decoder (vttdec)
RTP/RTSP/SDP input (rtpin)
File output (fout)
Raw AAC to LATM writer (uflatm)
ADTS writer (ufadts)
Media Reframer (reframer)
Stream to file (writegen)
AVC/HEVC to AnnexB writer (ufnalu)
QCP writer (writeqcp)
WebVTT writer (writevtt)
NHNT writer (nhntw)
NHML writer (nhmlw)
VobSub demuxer (vobsubdmx)
AVI muxer (avimx)
Audio output (aout)
M4V writer (ufm4v)
Audio resampler (resample)
Video output (vout)
Video crop (vcrop)
Video flip (vflip)
RAW video reframer (rfrawvid)
PCM reframer (rfpcm)
JPG encoder (jpgenc)
PNG encoder (pngenc)
Audio/Video rewinder (rewind)
Sources concatenator (flist)
MPEG-2 TS muxer (m2tsmx)
DASH and HLS segmenter (dasher)
HEVC tile aggregator (tileagg)
pipe input (pin)
pipe output (pout)
GSF Muxer (gsfmx)
GSF Demuxer (gsfdmx)
UDP/TCP output (sockout)
AV1/IVF/VP9 reframer (rfav1)
IVF/OBU/annexB writer (ufobu)
ATSC input (atscin)
RTP Streamer (rtpout)
RTSP Server (rtspout)
HTTP Server (httpout)
HEVC tile spliter (hevcsplit)
HEVC Tile merger (hevcmerge)
FLAC reframer (rfflac)
ProRes reframer (rfprores)
MPEG Transport Stream splitter (tssplit)
FFMPEG demuxer (ffdmx)
FFMPEG decoder (ffdec)
FFMPEG AV Capture (ffavin)
FFMPEG video rescaler (ffsws)
FFMPEG encoder (ffenc)
FFMPEG muxer (ffmx)
FFMPEG AVFilter (ffavf)
JavaScript filter (jsf)
OpenHEVC decoder (ohevcdec)

Clone this wiki locally
You can’t perform that action at this time.