gpac(1)

📦

version 26.02.0 · 5 versions

26.02.0 · fedora 44 (latest)
26.07.0-unstable-2026-08 · nixos 26.05, nixpkgs unstable
2.0.0 · ubuntu jammy
2.4.0 · epel 10, epel 9, fedora 43
2.2.1 · ubuntu noble

🌸 gpac(1) 🌸

okay bestie, welcome to the GPAC manual page, section 1 of 1 — the command-line filter session manager herself. GPAC ships this whole thing, and we're gonna walk through every single flag like it's a group chat debrief. 💅

✨ NAME ✨

gpac — GPAC's command-line filter session manager. She's the one who sets up and runs your filter chains, no cap. 👑

🦋 SYNOPSIS 🦋

gpac [options]FILTER[LINK]FILTER[...]

gpac is GPAC's command line tool for setting up and running filter chains. That's the whole vibe.

FILTER — a single filter declaration, like -i file, -o dump, inspect, whatever you need. Full tea is in gpac -h doc.
[LINK] — a link instruction, e.g. @, @2, @2#StreamType=Visual, ... again, gpac -h doc has the deets.
[options] — one or more option strings, and each one starts with a - character.
- an option using a single - indicates an option of gpac (peep gpac -hx) or of libgpac (peep gpac -hx core)
- an option using -- indicates a global filter or meta-filter (e.g. FFmpeg) option, like --block_size=1000 or --profile=Baseline (see gpac -h doc)

💜 DESCRIPTION 💜

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. So like... order matters sometimes, iykyk. 🙈

Options do not require any specific order, and may be present anywhere — including between link statements or filter declarations. Chaotic? Yes. Allowed? Also yes. ✨

Boolean values do not need any value specified.</> Other types shall be formatted as opt=val, except -i, -src, -o, -dst and -h options. Those five are the exceptions, periodt.

💀 The session can be interrupted at any time using ctrl+c, which can also be used to toggle global reporting. Yes, the same key does both. Main character multitasking energy.

The possible options for gpac are:

🌈 OPTIONS 🌈

-mem-track — enable the memory tracker 🔍
-mem-track-stack — enable the 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, and it breaks at the first error. If no value is given, it loops forever. 🔁
-eloop (int) — same as sloop but does not break if there's an error
-runfor (int) — run for the given amount of milliseconds, then exit with a full session flush
-runforf (int) — run for the given amount of milliseconds, then exit with a 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 the end (tests) 🧘
-stats — print stats after execution 📊
-graph — print the graph after execution 🕸️
-qe — enable quick exit (no mem cleanup)
-k — enable keyboard interaction from the command line ⌨️
-r (string) — enable reporting
- r: runtime reporting
- r=FA[,FB]: runtime reporting but only print the given filters, e.g. r=mp4mx for ISOBMFF multiplexer only
- r=: only print the 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 a GF_FileIO object (testing of GF_FileIO)
-ibx (string) — specify an input file to wrap as a GF_FileIO object without caching (testing of GF_FileIO)
-ob (string) — specify an output file to wrap as a GF_FileIO object (testing of GF_FileIO)
-cl — force complete mode when no link directive is 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 a 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 the indicated profile for the global GPAC config. If not found, the config file is created. If a file path is indicated, this will load the profile from that file. Otherwise, this will create a directory of the specified name and store the 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 the GPAC cache directory to their original name and server path
-cache-list — list entries in cache
-cache-clean (int) — clean cache 🧹
-js (string) — specify a javascript file to use as controller of filter session (can be set multiple times for multiple scripts)
-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

🧚 libgpac core options 🧚

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

and that's part 1, bestie — more coming, don't go anywhere 🫶

-sched (Enum, default: free) — sets the scheduler mode. so many vibes to choose from, pick ur fighter 🥊
- free: lock-free queues except for task list (this is the default on most platforms)
- lock: mutexes for queues when several threads (default on arm64/aarch64)
- freex: lock-free queues including for task lists (experimental 👀 handle with care)
- 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) — sets the maximum chain length when resolving filter links. the default value covers for [ in -> ] dmx -> reframe -> decode -> encode -> reframe -> mx [ -> out]. filter chains loaded for adaptation (like a pixel format change, bestie) are loaded after the link resolution. Setting this to 0 disables dynamic link resolution entirely — meaning you will have to specify the entire chain manually, no shortcuts, no autopilot 💀
-max-sleep (int, default: 50) — sets the maximum sleep time slot in milliseconds when regulation is enabled 😴
-step-link — load filters one by one when solving a link instead of loading all filters for the solved path. baby steps, we love a gradual approach 🐣
-threads (int) — set N extra thread for the session. -1 means use all available cores. go big or go home, periodt 🔥
-no-probe — disables data probing on sources and relies on extension instead (faster load but more error-prone — highkey a gamble, lowkey worth it sometimes 🙈)
-no-argchk — disables tracking of argument usage (all arguments will be considered as used). nothing gets flagged as unused, everything's invited to the party 🎉
-blacklist (string) — blacklist the filters listed in the given string (a comma-separated list). If the first character is -, this flips into a whitelist, i.e. only filters listed in the given string will be allowed. rude girl summer vs. exclusive guest list, ur call 💅
-no-graph-cache — disables internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (lower memory usage but slower — the classic tradeoff, no cap ⚖️)
-no-reservoir — disables memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more. choosing violence against ur allocator fr fr 😭
-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, it exits with error code 5 if there's a mismatch. she's checking receipts and she WILL call it out 🕵️

✨ Using Aliases ✨

okay so the gpac command line can become quite complex when lots of sources or filters are in play. to simplify all that chaos, an alias system is provided. it's giving quality of life 🫶

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 replaced 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. cute, documented, iconic 📝

🔐 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. protect ur data bestie, wrap it in TLS like it's a lil scarf 🧣

🧪 Defer test mode 🧪

This mode can be used to test loading filters one by one and asking for link resolution explicitly. It is mostly used to reproduce how sessions are built 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 loaded filter, e.g. @0 indicates the last loaded filter.
@@F indicates the target filter using a 0-based index F starting from the first loaded filter, e.g. @@1 indicates the second loaded filter.
@SRC or @@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)
-f — flush session until no more tasks
-g — print graph
-s — print stats
-se — send PLAY event from sinks (only done once)
-m (string) — print message

🌸 Configuration file 🌸

Okay bestie, listen up, because GPAC has a whole little config file situation going on. It uses a configuration file to modify the default options of libgpac and its filters, and it's literally called GPAC.cfg. Where does it live? Depends on your platform, and the list is giving ✨multi-platform chaos✨:

on Windows platforms, in C:UsersO0Datar, 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 -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=N

The key value N is not interpreted and always handled as ASCII text. Just vibes, no parsing. 💅

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 -wc and -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.

🧁 Core options

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. And the options specified at prompt overrides the value of the config file. Prompt wins, always. 🏆

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 -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. So no accidental cross-talk, periodt. 💅

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.

💖 libgpac core options:

-tmp (string) — specify directory for temporary file creation instead of OS-default temporary file management
-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)
-xml-max-csize (int, default: 100k) — maximum XML content or attribute size
-users (string) — authentication configuration file for users and groups
-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 (GPAC or pcap/pcapng file), 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=K: set rule mode - K can be r for reception only (default), w for send only or rw for both
s=K: set packet start range to K
e=K: set packet end range to K - only used for r and f rules, 0 or not set means rule apply until end
n=K: set number of packets to drop to K - not set, 0 or 1 means single packet
r=K: random drop n packet every K
f=K: drop first n packets every K
d=K: reorder n packets after the next K packets, can be used with f or r rules
p=K: filter packets on port K only, if not set the rule applies to all packets
o=K: patch packet instead of dropping (always true for TCP), replacing byte at offset K (0 is first byte, <0 for random)
v=K: set patch byte value to K (hexa) or negative value for random (default)
S=K: same as s but adds number of capture file reload/loop
E=K: same as e but adds number of capture file reload/loop

Example

-netcap=dst=dump.gpc

This will record packets to dump.gpc

Example

-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

Example

-netcap=[p=1234,s=100,n=20][r=200,s=500,o=10,v=FE]

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 (string) — set HTTP proxy server address and port (if no protocol scheme is set, use same as target)
-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 maximum cache size on disk in bytes
-cache-check (int, default: 60) — cache clean interval in seconds, 0 only clean cache at startup
-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
-ca-bundle (string) — path to a custom CA certificates bundle file
-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) — bestie, hand it a filename and it becomes ur user profile. The file's contents get appended as the body of HTTP HEAD/GET requests, and the associated Mime is text/xml. Slay.
-query-string (string) — shove a query string into the URL of requests. Note: without the ?, babe, just the string itself.
-dm-threads — forces threads to be used for async download requests instead of the session scheduler. it's giving "I'll do it myself" 💅
-cte-rate-wnd (int, default: 20) — sets the window analysis length, in milliseconds, for chunk-transfer encoding rate estimation. tiny window, big math energy 🔥
-cred (string) — path to a 128 bits key for credential storage. keep that key safe, queen 🔐
-no-h2 — disable HTTP2. bye bestie 👋
-no-h2c — disable HTTP2 upgrade (i.e. over non-TLS). no glow-up for you ✨
-h2-copy — enable intermediate copy of data in nghttp2 (default is disabled but may report as broken frames in wireshark). so like, off by default, but wireshark might start accusing u of broken frames 🙈
-curl — use CURL instead of the GPAC HTTP stack. different stack, same drama 💀
-h3 (Enum, default: auto) — set HTTP/3 mode. the options are:
- no: disable HTTP/3
- first: force trying first with HTTP/3
- auto: connect using HTTP 1 or 2 and use HTTP/3 for next request(s) if announced
- only: only use HTTP/3
-h3-trace — trace QUIC and HTTP3. so u can watch the packets do their lil dance 🦋
-dbg-edges — log edges status in the filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status(disable_depth), weight, src_cap_idx -> dst_cap_idx). debug girlies, this one's for u 👑
-full-link — throw error if any PID in the filter graph cannot be linked. no ghost PIDs allowed, periodt.
-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 naps. ever. 😴🚫
-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 on most platforms)
- lock: mutexes for queues when several threads (default on arm64/aarch64)
- 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) — sets the maximum chain length when resolving filter links. The 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 — and then u will have to specify the entire chain manually. no shortcuts, bestie 😤
-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. (yes, "solvink" — the manpage said it, so I said it 💀)
-threads (int) — set N extra thread for the session. -1 means use all available cores. go big or go home 🔥
-no-probe — disable data probing on sources and relies on extension (faster load but more error-prone). speedrun mode, but risky 🏃‍♀️
-no-argchk — disable tracking of argument usage (all arguments will be considered as used). nothing to see here, everything's fine ✨
-blacklist (string) — blacklist the filters listed in the given string (comma-separated list). If the first character is -, this is a whitelist, i.e. only filters listed in the given string will be allowed. plot twist, the dash flips the whole meaning 🎭
-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). trade-offs, always trade-offs 💅
-no-reservoir — disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more. your RAM stays light, ur allocator starts spiraling 😭
-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. that's a whole second, babe 🍓
-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). the vibe check, but for properties 👀
-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. two buffers, double the drama, double the slay 💖
-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. don't skip that step, bestie 🫶
-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 .I 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. font shopping spree 🎀
-rescan-fonts — indicate the font directory must be rescanned.
-wait-fonts — wait for SVG fonts to be loaded before displaying frames. patience is a virtue, queen 🧚
-webvtt-hours — force writing hour when serializing WebVTT. hour girlies rise 🕐
-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
-srt-forced — enable SRT with forced subtitles extensions.
-rmt — enable remote monitoring webserver.
-rmt-port (int, default: 6363) — set rmt ws port.
-rmt-localhost — make rmt ws only accepts localhost connection. no strangers allowed 🙅‍♀️
-rmt-sleep (int, default: 10) — set rmt ws sleep (ms) between server updates.
-rmt-cert (string) — rmt ws: certificate file in PEM format to use for TLS mode.
-rmt-pkey (string) — rmt ws: private key file in PEM format to use for TLS mode. keep this one SECRET 🔐
-userws-port (int, default: 6364) — set user ws port.
-userws-localhost — make userws ws only accepts localhost connection.
-userws-sleep (int, default: 10) — set userws sleep (ms) between server updates.
-userws-cert (string) — userws: certificate file in PEM format to use for TLS mode.
-userws-pkey (string) — userws: private key file in PEM format to use for TLS mode.
-diso-nosize — skip box size info when dumping ISOBMFF.
-m2ts-vvc-old — hack for old TS streams using 0x32 for VVC instead of 0x33. legacy mess, but we respect it 💀
-piff-force-subsamples — hack for PIFF PSEC files generated by 0.9.0 and 1.0 MP4Box with wrong subsample_count inserted for audio. ancient bugs, still haunting us 👻
-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.
-no-mabr-patch — disable GPAC parsing of patched isom boxes from mabr (will behave like most browsers/players). fitting in with the crowd, lowkey 🫶
-no-cdrf — disable cdrf sample dep.

📝 libgpac logs options ✨

-noprog — disable progress messages. no lil loading bars for u 🚫
-quiet — disable all messages, including errors. silence. total silence. even the errors get ghosted 💀
-log-file,-lf (string) — set output log file.
-log-clock,-lc — log time in micro sec since start time of GPAC before each log line except for app tool.
-log-utc,-lu — log UTC time in ms before each log line except for app tool.
-logs (string) — set log tools and levels.

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
strict: exit if error for this log tool and use default log level if tool

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 on any tool.

levelX can accept the suffix +strict to force strict error only for the given log tool(s).

Example

-logs=all@info:dash@debug:ncl

This moves all log to info level, dash to debug level and disable color logs. the glow-up, but for ur terminal 🌈

-proglf — use new line at each progress messages.
-log-dual,-ld — output to both file and stderr. why choose one when u can have both 💅

🌸 Overview 🌸

Okay bestie, listen up, because this is the whole ✨vibe✨ of GPAC. Filters are these configurable little processing units that eat data packets and spit data packets back out. And those packets get carried between filters through a data channel called a PID. A PID is the one in charge of allocating and tracking all the data packets, and then handing them off to the destination filter(s). One filter output PID can be connected to zero or more filters — and this fan-out is handled internally by GPAC. So there is literally no such thing as a tee filter in GPAC, periodt. 💅

⚠️ 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 -full-link is set. 😭

Every output PID carries a set of properties describing the data it delivers (think width, height, codec, ...). Properties can be built-in (see gpac -h props), or user-defined. And the way each PID tracks its property changes and triggers filter reconfiguration during packet processing? Iconic. It means the filter chain can be reconfigured at run time, potentially reloading part of the chain (e.g. unload a video decoder when switching from compressed to uncompressed sources). Main character energy fr fr. 👑

Each filter exposes a set of arguments 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. Wanna change them? Use -seps. 🎀

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/xmlformats/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/xmlformats/NHML-Format.
- b64@DATA: load data from base-64 encoded DATA.
- FMT@val: load values from val (comma-separated list) with FMT being u8, s8, u16, s16, u32, s32, u64, s64, flt, dbl, hex or str.
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.

Numbers and fraction can be expressed as THH:MM:SS.ms, TMM:SS.ms, THH:MM:SS or TMM:SS, translated into milliseconds. 🕐

💅 Filter declaration [FILTER] 💅

🦋 Generic declaration 🦋

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. :allt). 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. Slay.

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 schemes not using a server path, e.g. tcp:// and udp://, 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 locally disable option parsing (usefull 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 🌈

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).

⭐ Forcing specific filters ⭐

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.

🧚 Specifying encoders and decoders 🧚

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. Ate. 🔥

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).

💜 Escaping option separators 💜

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). This can also be used to escape a list value containing the comma separator character. 🌸

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.

Example

f:list=a,b1,,b2,c

This will set list values to a, b1,b2, and c.

🔗 Filter linking [LINK] 💫

okay so every filter out here exposes one or more sets of capabilities, and we call those a capability bundle — they're property type + values that have to be matched or excluded by the PIDs that connect in. no cap, bestie.

wanna see the possible sources and destinations for a filter FNAME? just ask:

gpac -h links FNAME

the filter graph resolver takes that info, pairs it up with the PID properties, and links your filters together. that's the whole vibe check. 💅

so what do link directives do? when you hand them over, they say which source a filter can accept connections from. that's it. they do not say which destination a filter can connect to. read that again, it matters. 👑

✨ Default filter linking ✨

when you don't give any link instructions (see below for those), the default linking strategy is either implicit mode (the default in gpac) or complete mode (if -cl is set).

every PID gets checked for a possible connection to all the defined filters, in their declaration order.

for each filter DST that accepts a connection from the PID — directly or with intermediate filters — here's the tea:

if DST filter has link directives, use them to allow or reject the PID connection.
otherwise, if complete mode is enabled, allow the connection.
otherwise (implicit mode):
- if DST is not a sink and is the first matching filter with no link directive, allow the connection.
- otherwise, if DST is not a sink and is not the first matching filter with no link directive, reject the connection.
- otherwise (DST is a sink) and there are no previous connections to a non-sink filter, allow the connection.

in all linking modes, a filter can stop itself from being linked to a filter with no link directives by setting the RSID option on that filter. this is typically needed when you're dynamically inserting/removing filters in an existing session where some filters have no ID defined and you don't want them in the inserted chain. 🚫

heads up: a filter with RSID set is not clonable. no cap.

Example

gpac -i file.mp4 c=avc -o output

with this setup in implicit mode:

if the file has a video PID, it'll 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'll connect to output, since this enc filter only accepts 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'll 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'll 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 it will prevent the reframer → ffsws connection.
video2 to ffsws, then ffsws to output, but it will prevent the video2 → 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. slay.

the implicit mode lets you specify linear processing chains (no PID fan-out except for the final output(s)) without link directives, which simplifies command lines for the common cases. it's giving convenience. ✨

⚠️ 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'll 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'll 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'll 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.

🎀 Quick links 🎀

you can also manually specify links between filters, if that's your thing. the syntax is an @ character, optionally followed by an integer (0 if you omit it).

this means the following filter specified at the prompt should be linked only to a previously listed filter. 💖

the optional integer is a 0-based index to the previous filter declarations — 0 is the previous filter declaration, 1 is the one before the previous declaration, and so on and so on.

if you use @@ instead of @, the optional integer gives the filter index starting from the first filter (index 0) specified in the command line.

several link directives can be given for one filter. go off. 🔥

Example

fA fB @1 fC

this means fC only accepts inputs from fA.

Example

fA fB fC @1 @0 fD

this means fD only accepts inputs from fB and fC.

Example

fA fB fC ... @@1 fZ

this means fZ only accepts inputs from fB.

💜 Complex links 💜

the @ link directive is just a quick little shortcut that sets the following filter arguments:

FID=name: assigns an identifier to the filter.
SID=name1[,name2...]: sets a list of filter identifiers, aka 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 means 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 means 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 extended even further using a 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 the N (1-based index) PID of matching type from the source (e.g. video2 to only accept the second video PID).
name#TAG=VAL: accepts the PID if its parent filter has no tag or a tag matching VAL.
name#ITAG=VAL: accepts the PID if its parent filter has no inherited tag or an inherited tag matching VAL.
name#P4CC=VAL: accepts only PIDs with a 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 isn't 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 a wildcard, or just be empty, to match a property regardless of the source filter. 🦋

Example

fA fB:SID=*#ServiceID=2
fA fB:SID=#ServiceID=2

this means match the 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 means fC only accepts inputs from fA, and of type video.

Example

gpac -i img.heif @#ItemID=200 vout

this means connect to vout only PIDs with ItemID property equal to 200.

Example

gpac -i vid.mp4 @#PID=1 vout

this means connect to vout only PIDs with ID property equal to 1.

Example

gpac -i vid.mp4 @#Width=640 vout

this means connect to vout only PIDs with Width property equal to 640.

Example

gpac -i vid.mp4 @#Width-640 vout

this means 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 the PID with an ID property equal to the ItemID property (keep items, discard tracks) and an Item number of 1 (first item).

multiple fragments can be specified to check for multiple PID properties. 👑

Example

gpac -i vid.mp4 @#Width=640#Height+380 vout

this means 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 set up, fr fr.

Example

fA @ reframer fB

if fB accepts inputs provided by fA but reframer does not, this will link the fA PID to the fB filter since fB has no sourceID. and 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 a direct connection of a PID of type file to the dst file.mp4, remultiplexing the file instead.

the special option nomux is used to allow direct connections (it's 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.

🌈 Sub-session tagging 🌈

filters can 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. 💜

Arguments inheriting 🎀

Unless you literally turn it off (peep -max-chain), the filter engine is out here doing the most: it resolves implicit and explicit (LINK) connections between your filters and allocates any filter chain needed to connect them. And when it loads those new filters, it hands them arguments inherited from both the source and the destination. Bestie behaviour honestly.

Example 💖

gpac -i file.mp4:OPT -o file.aac -o file.264

This passes the :OPT to every single filter loaded between the source and the two destinations.

Example ✨

gpac -i file.mp4 -o file.aac:OPT -o file.264

This passes the :OPT to all the filters loaded between the source and the file.aac destination.

Note: the destination arguments that get inherited are the arguments placed AFTER the dst= option.

Example 🌸

gpac -i file.mp4 fout:OPTFOO:dst=file.aac:OPTBAR

This passes the :OPTBAR to all filters loaded between the file.mp4 source and the file.aac destination — but not OPTFOO.

You can stop the inheriting at any point using the keyword gfloc: — anything after that keyword does not get inherited.

Example 🦋

gpac -i file.mp4 -o file.aac:OPTFOO:gfloc:OPTBAR -o file.264

This passes :OPTFOO to all filters loaded between the file.mp4 source and the file.aac destination, but not OPTBAR.

Arguments are tracked by default, so the engine can check whether the filter chain actually used them — and it'll throw a warning if it didn't. Sometimes you've got arguments that may or may not get consumed depending on how the graph resolves, and for that the keyword gfopt is your girl: arguments after it will not be tracked.

Example 💅

gpac -i file.mp4 -o file.aac:OPTFOO:gfopt:OPTBAR -o file.264

This warns if OPTFOO isn't consumed, but won't track OPTBAR.

A filter can also get itself a name (purely for inspection vibes, it does not inherit) using the :N=name option. That name isn't used in link resolution at all and the filter instance can just change it at runtime. Slay, flexible.

A filter can be given a tag (any string you want) using :TAG=name. Tags don't need to be unique, and you can use them to exclude a filter during link resolution. Tags are not inherited, so dynamically loaded filters never have a tag.

A filter can also be given an inherited tag (any string) using :ITAG=name. These ones do inherit, and they're typically used to track dynamically loaded filters. Iconic.

URL templating 🌈

Destination URLs can be built dynamically with templates. The pattern $KEYWORD$ gets replaced with the resolved value, and $KEYWORD%%0Nd$ gets replaced with the resolved integer, padded with up to N zeros if needed.

KEYWORD is case sensitive, and it can show up multiple times in the string. Supported KEYWORDs, bestie:

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 ...)
OType — same as Type but uses original type when stream is encrypted (e.g. move from crypt to video)
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 your escape for $. And for shells that auto-replace $$ with $, you can use the syntax $;$ to express $$.

Templating is a whole mood when you're 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

This creates a cropped version of the source, encoded in AVC at 1M, plus a full version of the content in AVC at 750k. The outputs will be dump_0x0x320x180.264 for the cropped one and dump_0x0x640x360.264 for the non-cropped one. Literally so satisfying.

Cloning filters 💀

When a filter accepts a single connection and already has a connected input, it's no longer available for dynamic resolution. Sometimes that's just not the vibe you want. Take a HEIF file with N items and do:

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. The other items won't connect at all, because the destination only accepts one input PID.

Example 🍓

gpac -i img.heif -o dump_$ItemID$.jpg

In this case, the destination gets cloned for each item, and they all get exported to different JPEGs thanks to URL templating. Chef's kiss.

Example 🧚

gpac -i vid.mpd c=avc:FID=1 -o transcode.mpd:SID=1

Here the encoder gets cloned for each video PID in the source, and the destination only uses PIDs coming from the encoders.

When implicit linking is on, all filters are clonable by default. That's what lets you duplicate the processing for each PID of the same type.

Example 💜

gpac -i dual_audio resample:osr=48k c=aac -o dst

The resampler filter gets cloned for each audio PID, and the encoder gets cloned for each resampler output.

And you can explicitly deactivate the cloning instructions if you want:

gpac -i dual_audio resample:osr=48k:clone=0 c=aac -o dst

Now the first audio connects to the resample filter, the second one goes to the enc filter, and the resample output connects to a clone of the enc filter. Chaotic but valid.

Templating filter chains 🫶

Sometimes the number of outputs you want depends on the source content — like dumping a multiplex of N services into N files. When the destination involves multiplexing the input PIDs, the :clone option alone isn't enough, because the multiplexer will always accept the input PIDs. Annoying.

To handle this, you can use a PID property name in the sourceID of a filter with the value * or an empty value. Whenever a new PID shows up with a new value for that property, the filter with such sourceID gets dynamically cloned. Boom.

Warning: this feature should only be called with a single property set to * (or empty) per source ID. Results are undefined otherwise. Do not test fate, bestie.

Example ⭐

gpac -i source.ts -o file_$ServiceID$.mp4:SID=*#ServiceID=*
gpac -i source.ts -o file_$ServiceID$.mp4:SID=#ServiceID=

Here, each new ServiceID value found while connecting PIDs to the destination creates a new destination file.

Cloning in implicit linking mode applies to output as well:

gpac -i dual_audio -o dst_$PID$.aac

Each audio track gets dumped to aac (potentially reencoding if needed).

Assigning PID properties 💖

You can define properties on output PIDs that a filter will declare. This is how you tag parts of the graph with different properties than other parts (say, ServiceID). The syntax is the same as a filter option, and it uses the fragment separator to identify properties, e.g. #Name=Value.

This sets the output PIDs property (4cc, built-in name, or literally any name) to the given value. The value can be omitted for a boolean (it defaults to true, e.g. :#Alpha).

Non built-in properties get parsed like this:

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 isn't recognized, the entire value is copied as string. See gpac -h props for the defined types.

User-assigned PID properties on filter fA get inherited by all filters dynamically loaded to solve the fA -> fB connection. But if fB also has user-assigned PID properties, those only apply starting from fB in the chain and are not inherited by the filters between fA and fB. Keep that in mind.

Warning: properties are not filtered and they 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/... ! Seriously, don't.

Example 🔥

gpac -i v1.mp4:#ServiceID=4 -i v2.mp4:#ServiceID=2 -o dump.ts

This multiplexes the streams in dump.ts, using ServiceID 4 for PIDs from v1.mp4 and ServiceID 2 for PIDs from v2.mp4.

PID properties can also be assigned conditionally by checking other PID properties. The syntax uses parenthesis (not configurable, sorry) after the property assignment sign:

#Prop=(CP=CV)VAL

This assigns PID property Prop to VAL for PIDs with property CP equal to CV.

#Prop=(CP=CV)VAL,(CP2=CV2)VAL2

This assigns 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 assigns 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 assigns PID property Prop to VAL for PIDs with property CP equal to CV, or to DEFAULT for the other PIDs.

The condition syntax is the same as the source ID fragment syntax.

Note: when set, the default value (empty condition) always matches the PID, so it should be placed last in the list of conditions.

Example 🌸

gpac -i source.mp4:#MyProp=(audio)"Super Audio",(video)"Super Video"

This assigns 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 assigns property MyProp to Super Audio for the first audio PID declared.

Example 🦋

gpac -i source.mp4:#MyProp=(Width+1280)HD

This assigns property MyProp to HD for PIDs with property Width greater than 1280.

The property value can use templates with these keywords:

$GINC(init[,inc]) or @GINC(...) — replaced by integer for each new output PID of the filter (see the specific filter options for details on syntax)
PROP (enclosed between $ or @) — replaced by the serialized value of property PROP (name or 4CC) of the PID, or with an empty string if there's no such property

Example ✨

gpac -i source.ts:#ASID=$PID$

This assigns the DASH AdaptationSet ID to the PID ID value.

Example 👑

gpac -i source.ts:#RepresentationID=$ServiceID$

This assigns the DASH Representation ID to the PID ServiceID value.

A property can also be removed by not specifying any value at all. Conditional removal is possible using the syntax above.

Example 🍓

gpac -i source.ts:#FOO=

This removes the FOO property on the output PID. Gone, deleted, no notes.

🌸 Using option files 🌸

okay bestie, plot twist: you can put all your filter options in a file instead of typing them inline. Just hand over the target file name as an option with no value, like :myopts.txt. iconic, right?

⚠️ Warning: Only local files are allowed. no network shenanigans, periodt.

An option file is just a plain little text file holding one or more options or PID properties, spread over one or more lines. the rules:

A line starting with // is a comment and gets ignored (and nope, it's not configurable).
A line starting with : means an escaped option — the entire line gets parsed as a single option.

And yes, options inside an option file can point at other option files, with a maximum redirection level of 5. we're not doing infinite recursion here 💅

An option file declaration (filter:myopts.txt) follows the exact 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. slay, inheritance 💖

🦋 Ignoring filters at run-time 🦋

There's a special option called ccp and it lets you swap filters out for an identity filter at run-time, based on the input codec ID. lowkey a glow-up for your pipeline.

The option is a list of codec IDs to check. For encoder filters, an empty list reuses the encoder codec type.

When the PID codec ID matches one of the specified codecs, the filter gets replaced with a reframer filter with single PID input and the same name and ID. same energy, new body ✨

Example

-i src c=avc:b=1m:ccp -o mux

This will replace the encoder filter with a reframer if the input PID is in AVC|H264 format, or uses the encoder for other visual PIDs.

Example

-i src c=avc:b=1m:ccp=avc,hevc -o mux

This will replace the encoder filter with a reframer if the input PID is in AVC|H264 or HEVC format, or uses the encoder for other visual PIDs.

Example

-i src cecrypt:cfile=drm.xml:ccp=aac -o mux

This will replace the encryptor filter with a reframer if the input PID is in AAC format, or uses the encryptor for other PIDs. no cap 🫶

Some special keywords get swapped out when filter options are processed. very main character behaviour.

⚠️ Warning: These keywords do not apply to PID properties. And you can't stack multiple keywords on a single option — one per option, bestie.

The defined keywords, babes:

$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 -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
$GCFG — replaced by system path to folder containing GPAC config
$GLANG — replaced by the global config language option -lang
$GUA — replaced by the global config user agent option -user-agent
$GINC(init_val[,inc]) — replaced by init_val, and increments init_val by inc (a positive or negative number, 1 if not specified) each time a new filter using this string is created.

The $GINC construct is how you dynamically assign numbers in filter chains:

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... obsessed with this actually 😭

As seen previously, the following options may be set on any filter, but they 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)
ITAG — filter inherited 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 — explicitly enable/disable 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)
ccp — filter replacement control (string list value)
NCID — ID of netcap configuration to use (string)
LT — set additionnal log tools and levels for the filter usin same syntax as -logs, e.g. :LT=filter@debug (string value)
DBG — debug missing input PID property (=pid), missing input packet property (=pck) or both (=all)

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).

The options FBT, FBU, FBD and DBG 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.

🌈 External filters 🌈

GPAC comes with a set of built-in filters in libgpac. But bestie, it can also load external filters in dynamic libraries — located in the default module folder or folders listed in the -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. that's the whole vibe 💫

👑 GPAC Built-in properties 👑

✨ Built-in property types ✨

sint — signed 32 bit integer
uint — unsigned 32 bit integer
lsint — signed 64 bit integer
luint — unsigned 32 bit integer
bool — boolean
frac — 32/32 bit fraction
lfrac — 64/64 bit fraction
flt — 32 bit float number
dbl — 64 bit float number
v2di — 2D 32-bit integer vector
v2d — 2D 64-bit float vector
v3di — 3D 32-bit integer vector
v4di — 4D 32-bit integer vector
str — UTF-8 string
mem — data buffer
cstr — const UTF-8 string
cmem — const data buffer
ptr — 32 or 64 bit pointer
strl — UTF-8 string list
uintl — unsigned 32 bit integer list
sintl — signed 32 bit integer list
v2il — 2D 32-bit integer vector list
4cc — Four character code
4ccl — four-character codes list
pfmt — raw pixel format
afmt — raw audio format
cprm — color primaries, string or int value from ISO/IEC 23091-2
ctfc — color transfer characteristics, string or int value from ISO/IEC 23091-2
cmxc — color matrix coefficients, string or int value from ISO/IEC 23091-2
alay — channel layout configuration, string or int value from ISO/IEC 23091-3

🎀 Built-in properties for PIDs and packets 🎀

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).

ID (PIDI, uint, ) — Stream ID
ESID (ESID, uint, D) — MPEG-4 ESID of PID
ItemID (ITID, uint, ) — ID of image item in HEIF, same value as ID
ItemNumber (ITIX, uint, ) — Number (1-based) of image item in HEIF, in order of declaration in file
TrackNumber (PIDX, uint, ) — Number (1-based) of track in order of declaration in file
ServiceID (PSID, uint, D) — ID of parent service
ClockID (CKID, uint, D) — ID of clock reference PID
DependencyID (DPID, uint, ) — ID of layer depended on
SubLayer (DPSL, bool, ) — PID is a sublayer of the stream depended on rather than an enhancement layer
PlaybackMode (PBKM, uint, D) — Playback mode supported:
- 0: no time control
- 1: play/pause/seek,speed=1
- 2: play/pause/seek,speed>=0
- 3: play/pause/seek, reverse playback
Scalable (SCAL, bool, ) — Scalable stream
TileBase (SABT, bool, ) — Tile base stream
TileID (PTID, uint, ) — ID of the tile for hvt1/hvt2 PIDs
Language (LANG, cstr, ) — Language code: ISO639 2/3 character code or RFC 4646
ServiceName (SNAM, str, D) — Name of parent service, signled as PID info
ServiceProvider (SPRO, str, D) — Provider of parent service, signled as PID info
StreamType (PMST, uint, ) — Media stream type
StreamSubtype (PSST, 4cc, D) — Media subtype 4CC (auxiliary, pic sequence, etc ..), matches ISOM handler type
ISOMSubtype (PIST, 4cc, D) — ISOM media subtype 4CC (avc1 avc2...)
OrigStreamType (POST, uint, ) — Original stream type before encryption
CodecID (POTI, uint, ) — Codec ID (MPEG-4 OTI or ISOBMFF 4CC)
InitialObjectDescriptor (PIOD, bool, ) — PID is declared in the IOD for MPEG-4
Unframed (PFRM, bool, ) — The media data is not framed, i.e. each packet is not a complete AU/frame or is not in internal format (e.g. annexB for avc/hevc, adts for aac)
UnframedAU (PFRF, bool, ) — The unframed media still has correct AU boundaries: one packet is one full AU, but the packet format might not be the internal one (e.g. annexB for avc/hevc, adts for aac)
LATM (LATM, bool, ) — Media is unframed AAC in LATM format
USRT (USRT, bool, ) — Media is unframed SRT, header is in payload with 0 start time
Duration (PDUR, lfrac, ) — Media duration
EstimatedDuration (EDUR, bool, ) — Media duration is an estimated duration based on rate
NumFrames (NFRM, uint, D) — Number of frames in the stream
FrameOffset (FRMO, uint, D) — Index of first frame in the stream (used for reporting)
ConstantFrameSize (CFRS, uint, ) — Size of the frames for constant frame size streams
TimeshiftDepth (PTSD, frac, D) — Depth of the timeshift buffer
TimeshiftTime (PTST, dbl, D) — Time in the timeshift buffer in seconds — changes are signaled through PID info (no reconfigure)
TimeshiftState (PTSS, uint, D) — State of timeshift buffer: 0 is OK, 1 is underflow, 2 is overflow — changes are signaled through PID info (no reconfigure)
Timescale (TIMS, uint) — the media timescale, periodt ⏱️ a timestamp delta of N is literally N/timescale seconds.
ProfileLevel (PRPL, uint, D) — profile and level indication, the little "who dis" of the stream 💅
DecoderConfig (DCFG, mem) — the decoder configuration data. that's it, that's the bytes 🫶
DecoderConfigEnhancement (ECFG, mem) — decoder configuration data of the enhancement layer(s) 👑 also used by 3GPP/Apple text streams to give the full sample description table used in SDP.
DSISuperset (DCFS, bool) — the decoder config is a superset of the previous decoder config ✨ we're building up, not sideways.
DecoderConfigIndex (ICFG, uint) — the 1-based index of decoder config for ISO base media files. yes bestie, 1-based, not 0-based 🙈 do not come for me.
SampleRate (AUSR, uint) — audio sample rate 🎵
SamplesPerFrame (FRMS, uint) — number of audio samples in one coded frame.
NumChannels (CHNB, uint) — number of audio channels 🌈
BPS (ABPS, uint) — number of bits per sample in the compressed source.
ChannelLayout (CHLO, luint) — channel layout mask.
AudioFormat (AFMT, afmt) — audio sample format.
AudioPlaybackSpeed (ASPD, dbl, D) — audio playback speed, only used for audio output reconfiguration.
Delay (MDLY, lsint) — delay of presentation compared to composition timestamps, in media timescale. A positive value imply holding (delaying) the stream. A negative value imply skipping the beginning of stream.
CTSShift (MDTS, uint) — CTS offset to apply in case of negative ctts.
SkipPriming (ASKP, bool) — audio priming shall not to be removed when initializing decoding. it stays, no takebacks 💀
Width (WIDT, uint) — visual width (video / text / graphics).
Height (HEIG, uint) — visual height (video / text / graphics).
PixelFormat (PFMT, pfmt) — pixel format.
PixelFormatWrapped (PFMW, pfmt) — the underlying pixel format of the video stream if the pixel format is an external GL texture 🎨 it's giving wrapped-gift energy.
Stride (VSTY, uint) — image or Y/alpha plane stride.
StrideUV (VSTC, uint) — UV plane or U/V planes stride.
BitDepthLuma (YBPS, uint) — bit depth for luma components.
BitDepthChroma (CBPS, uint) — bit depth for chroma components.
FPS (VFPF, frac) — video framerate 🔥
Interlaced (VILC, bool) — the video is interlaced.
SAR (PSAR, frac) — sample (i.e. pixel) aspect ratio. careful babes: negative values mean no SAR and removal of info in containers ⚠️
MaxWidth (MWID, uint) — maximum width (video / text / graphics) of all enhancement layers.
MaxHeight (MHEI, uint) — maximum height (video / text / graphics) of all enhancement layers.
ZOrder (VZIX, sint) — z-order of the video, from 0 (first) to max int (last). stacking order, main character goes last 👑
TransX (VTRX, sint) — horizontal translation of the video (positive towards right).
TransY (VTRY, sint) — vertical translation of the video (positive towards up).
TransXRight (VTRx, sint) — horizontal offset of the video from right (positive towards right), for cases where the reference width is unknown.
TransYTop (VTRy, sint) — vertical translation of the video (0 is top, positive towards down), for cases where the reference height is unknown.
Hidden (HIDE, bool) — this PID is hidden in visual/audio rendering 🙈 not invited to the render party.
CropOrigin (VCXY, v2di) — position in source window; X,Y indicate coordinates in source (0,0 for top-left).
OriginalSize (VOWH, v2di) — original resolution of the video.
SRD (SRDI, v4di) — position and size of the video in the referential given by SRDRef.
SRDRef (SRDR, v2di) — width and height of the SRD referential.
SRDMap (SRDM, uintl) — mapping of input videos in the reconstructed video, expressed as {Ox,Oy,Ow,Oh,Dx,Dy,Dw,Dh} per input, with:
- Ox,Oy,Ow,Oh: position and size of the input video (usually matching its SRD property), expressed in the output referential given by SRDRef
- Dx,Dy,Dw,Dh: position and size of the input video in the reconstructed output, expressed in the output referential given by SRDRef
Alpha (VALP, bool) — the video in this PID is an alpha map 🦋
Mirror (VMIR, uint) — mirror mode, as a bit mask with flags 0: no mirror, 1: along Y-axis, 2: along X-axis.
Rotate (VROT, uint) — video rotation as value*90 degree anti-clockwise.
ClapW (CLPW, frac) — width of clean aperture in luma pixels.
ClapH (CLPH, frac) — height of clean aperture in luma pixels.
ClapX (CLPX, frac) — horizontal offset of clean aperture center in luma pixels, 0 at image center.
ClapY (CLPY, frac) — vertical offset of clean aperture center in luma pixels, 0 at image center.
NumViews (PNBV, uint) — number of views packed in a frame (top-to-bottom only).
Bitrate (RATE, uint) — bitrate in bps.
Maxrate (MRAT, uint) — max bitrate in bps.
TargetRate (TBRT, uint) — target bitrate in bps, used to setup encoders 🎯
DBSize (DBSZ, uint) — decode buffer size in bytes.
MediaDataSize (MDSZ, luint, D) — size in bytes of media data.
DataRef (DREF, bool, D) — data referencing is possible (each compressed frame is a continuous set of bytes in source, with no transformation).
URL (FURL, str, D) — URL of source.
RemoteURL (RURL, str, D) — remote URL of source — used for MPEG-4 systems.
RedirectURL (RELO, str, D) — redirection URL of source.
SourcePath (FSRC, str, D) — path of source file on the file system.
FileAlias (FALI, str, D) — alias name for the source file, replace $URL$ and $File$ in templates ✨
MIMEType (MIME, str, D) — MIME type of source.
Extension (FEXT, str, D) — file extension of source.
Cached (CACH, bool, D) — the file is completely cached 💾 fully downloaded, no buffering anxiety.
DownloadRate (DLBW, uint, D) — download rate of resource in bits per second — changes are signaled through PID info (no reconfigure).
DownloadSize (DLSZ, luint, D) — size of resource in bytes.
DownBytes (DLBD, luint, D) — number of bytes downloaded — changes are signaled through PID info (no reconfigure).
ByteRange (FBRA, lfrac, D) — byte range of resource.
DisableProgressive (NPRG, uint) — some blocks in the file need patching (replace or insertion) upon closing, potentially disabling progressive upload 👀
IsoAltBrands (ABRD, 4ccl, D) — ISOBMFF brands associated with PID/file.
IsoBrand (MBRD, 4cc, D) — ISOBMFF major brand associated with PID/file.
MovieTime (MHTS, lfrac, D) — ISOBMFF movie header duration and timescale.
HasSync (PSYN, bool, D) — the PID has sync points.
ServiceWidth (DWDT, uint, D) — display width of service.
ServiceHeight (DHGT, uint, D) — display height of service.
IsDefault (PDEF, bool, D) — default PID for this stream type.
CarouselRate (CARA, uint, D) — repeat rate in ms for systems carousel data.
AudioVolume (AVOL, uint, D) — volume of audio 🔊
AudioPan (APAN, uint, D) — balance/Pan of audio.
AudioPriority (APRI, uint, D) — audio thread priority.
ProtectionScheme (SCHT, 4cc) — protection scheme type (4CC) used.
SchemeVersion (SCHV, uint) — protection scheme version used.
SchemeURI (SCHU, str) — protection scheme URI.
KMS_URI (KMSU, str) — URI for key management system 🔑
SelectiveEncryption (ISSE, bool) — ISMA/OMA selective encryption is used.
IVLength (ISIV, uint) — ISMA IV size.
KILength (ISKI, uint) — ISMA KeyIndication size.
CryptType (OMCT, uint) — OMA encryption type.
ContentID (OMID, str) — OMA Content ID.
TextualHeaders (OMTH, str) — OMA textual headers.
PlaintextLen (OMPT, luint) — OMA size of plaintext data.
CryptInfo (ECRI, str, D) — URL (local file only) of crypt info file for this PID; use clear to force passthrough.
DecryptInfo (EDRI, str, D) — URL (local file only) of crypt info file for this PID — see decrypter help.
SenderNTP (NTPS, luint, DP) — NTP 64 bits timestamp at sender side or grabber side.
ReceiverNTP (NTPR, luint, DP) — receiver NTP (64 bits timestamp), usually associated with the sender NTP property.
UTC (UTCD, luint, DP) — UTC timestamp (in milliseconds) of parent packet.
Encrypted (EPCK, bool) — packets for the stream are by default encrypted (however the encryption state is carried in packet crypt flags) — changes are signaled through PID info change (no reconfigure).
OMAPreview (ODPR, luint) — OMA Preview range.
CENC_PSSH (PSSH, mem) — PSSH blob for CENC, formatted as (u32)NbSystems [ (bin128)SystemID(u32)version(u32)KID_count[ (bin128)keyID ] (u32)priv_size(char*priv_size)priv_data]
CENC_SAI (SAIS, mem, P) — CENC SAI for the packet, formatted as (char(IV_Size))IV(u16)NbSubSamples [(u16)ClearBytes(u32)CryptedBytes]
KeyInfo (CBIV, mem) — multi key info formatted as:

 is_mkey(u8);
nb_keys(u16);
[
     IV_size(u8);
     KID(bin128);
     if (!IV_size) {;
          const_IV_size(u8);
          constIV(const_IV_size);
}
]

CENCPattern (CPTR, frac) — CENC crypt pattern, CENC pattern, skip as frac.num crypt as frac.den.
CENCStore (CSTR, 4cc) — storage location 4CC of SAI data.
CENCstsdMode (CSTM, uint) — mode for CENC sample description when using clear samples:
1. 0: single sample description is used
2. 1: a clear clone of the sample description is created, inserted before the CENC sample description
3. 2: a clear clone of the sample description is created, inserted after the CENC sample description
AMRModeSet (AMST, uint) — ModeSet for AMR and AMR-WideBand.
SubSampleInfo (SUBS, mem, P) — binary blob describing N subsamples of the sample, formatted as N [(u32)flags(u32)size(u32)codec_param(u8)priority(u8) discardable]. Subsamples for a given flag MUST appear in order, however flags can be interleaved.
NALUMaxSize (NALS, uint) — max size of NAL units in stream — changes are signaled through PID info change (no reconfigure).
FileNumber (FNUM, uint, P) — index of file when dumping to files 🗂️
FileName (FNAM, str, P) — the name of your output file when you're dumping or dashing. 📁 Bestie, this must be set on the first packet that belongs to the new file, no exceptions.
IDXName (INAM, str, P) — the name of the index file when you're dashing MPEG-2 TS. Same energy as above: must be set on the first packet belonging to the new file. 🗂️
FileSuffix (FSUF, str, P) — the file suffix name, aka the glow-up replacement for $FS$ inside your tile templates. ✨
EODS (EODS, bool, P) — End of DASH segment. That's it, that's the whole vibe. 🏁
CueStart (PCUS, bool, P) — set on packets that mark the beginning of a DASH/HLS segment for cue-driven segmentation — go peek at the dasher help for the deets. 🎯
MediaTime (MTIM, dbl, DP) — the corresponding media time of the parent packet, with 0 being the origin. ⏱️
MaxFrameSize (MFRS, uint, D) — max size of a frame in the stream. Heads up: changes get signaled through PID info change, and there's no reconfigure. 📏
AvgFrameSize (AFRS, uint, D) — average size of a frame in the stream. ISOBMFF only, and it's a static property, so it's not gonna move for you. 📐
MaxTSDelta (MTSD, uint, D) — maximum DTS delta between frames. ISOBMFF only, static property. 🕰️
MaxCTSOffset (MCTO, uint, D) — maximum absolute CTS offset. ISOBMFF only, static property. 🧭
ConstantDuration (SCTD, uint, D) — constant duration of samples, where 0 means variable duration. ISOBMFF only, static property. 🔁
TrackTemplate (ITKT, mem, D) — ISOBMFF serialized track box for this PID, without any sample info (so: empty stbl and empty dref). 📦
TrexTemplate (ITXT, mem, D) — ISOBMFF serialized trex box for this PID. 🧱
STSDTemplate (ISTD, mem, D) — ISOBMFF serialized sample description entry for this PID. 🎞️
MovieUserData (IMUD, mem, D) — ISOBMFF serialized moov UDTA and other moov-level boxes (it's a list) for this PID. 💾
HandlerName (IHDL, str, D) — ISOBMFF track handler name. 🏷️
TrackFlags (ITKF, uint, D) — ISOBMFF track header flags. 🚩
TrackMatrix (ITKM, sintl, D) — ISOBMFF track header matrix. 🔢
AltGroup (IALG, uint, D) — ISOBMFF alt group ID. 👯
ForceNCTTS (IFNC, bool, D) — ISOBMFF force negative CTS offsets. ⚡
Disable (ITKD, bool, D) — ISOBMFF disable flag. 🙈
Period (PEID, str, D) — ID of the DASH period. 🗓️
PStart (PEST, lfrac, D) — DASH Period start — cf dasher help. 🚦
PDur (PEDU, lfrac, D) — DASH Period duration — cf dasher help. ⌛
Representation (DRID, str, D) — ID of the DASH representation. 🎭
ASID (DAID, uint, D) — ID of the parent DASH Adaptation Set. 🧬
SSR (SSRR, sint, D) — ID of the Adaptation Set, and it's giving options, so listen up:
- same value as ASID: regular SSR, not used for cross-AS switching
- ID of another AdaptationSet: enables cross-AS switching between this AS and the referenced one
- negative value: LL-HLS compatability mode
ASQuery (ASQR, str, D) — query string to add to this Adaptation Set when requesting segments. ❓
MuxSrc (MSRC, str, D) — name of the mux source(s), set by the dasher to direct its outputs. 🎛️
DashMode (DMOD, uint, D) — the DASH mode the multiplexer should use, if any, set by the dasher. 0 is no DASH, 1 is regular DASH, 2 is VoD. 🕹️
InitBase64 (IB64, bool, D) — tells the multiplexer it should send the base64 encoded version of the init segment. 🔐
SegSync (DFSS, bool, D) — indicates the segment must be completely flushed before sending segment/fragment size events. 🚰
DashDur (DDUR, frac, D) — DASH target segment duration, in seconds. ⏲️
FragDur (FDUR, frac, D) — DASH target fragment duration, in seconds. ⏲️
DashMultiPid (DMSD, ptr, D) — pointer to the GF_List of input PIDs for multi-stsd entries segments, set by the dasher. 🧵
DashMultiPidIdx (DMSI, uint, D) — 1-based index of the PID in the multi PID list, set by the dasher. 🔢
DashMultiTrack (DMTK, ptr, D) — pointer to the GF_List of input PIDs for multi-tracks segments, set by the dasher. 🧶
Role (ROLE, strl, D) — list of roles for this PID, where each role string can be a DASH role, a URN:role-value or any other string. Heads up: that last one will throw a warning and use a custom URI for the role. 🎪
PDesc (PDES, strl, D) — list of descriptors for the DASH period containing this PID. 📝
ASDesc (ACDS, strl, D) — list of conditional descriptors for the DASH AdaptationSet containing this PID. The tea: if a PID with the same property type but a different value shows up, those PIDs land in different AdaptationSets. 🫂
ASCDesc (AADS, strl, D) — list of common descriptors for the DASH AdaptationSet containing this PID. 🤝
RDesc (RDES, strl, D) — list of descriptors for the DASH Representation containing this PID. 📋
BUrl (BURL, strl, D) — list of base URLs for this PID. 🔗
Template (DTPL, str, ) — template to use for DASH generation for this PID. 🧩
StartNumber (DRSN, uint, ) — start number to use for this PID — cf dasher help. 🔢
xlink (XLNK, str, D) — remote period URL for DASH — cf dasher help. 🌐
ClampDur (DCMD, lfrac, D) — max media duration to process from the PID in DASH mode. ✂️
HLSPL (HLVP, str, D) — name of the HLS variant playlist for this media. 📺
HLSGroup (HLGI, str, D) — name of the HLS Group of a stream. 👥
HLSRend (HLGR, strl, D) — list of HLS groups allowed in group rendition. When it's not set, all groups are allowed. 🎚️
HLSForce (HLFI, str, D) — forces writing EXT-X-STREAM-INF if the stream is in a rendition group. The value is the name of the associated groups (and yes, it can be empty). 💪
HLSMExt (HLMX, strl, D) — list of extensions to add to the master playlist for this PID. 🎀
HLSVExt (HLVX, strl, D) — list of extensions to add to the variant playlist for this PID. 🎀
DCue (DCUE, str, D) — name of a cue list file for this PID — see dasher help. 🎵
DSegs (DCNS, uint, D) — number of DASH segments defined by the DASH cue info. 🔢
Codec (CODS, str, D) — the codec parameter string to force. If it starts with ., it gets appended to the ISOBMFF code point; otherwise it replaces the codec string. 🔤
SingleScale (DSTS, bool, D) — the movie header should use the media timescale of the first track added. 🧮
RequireReorder (PUDP, bool, D) — PID packets come from a source with losses and reordering happening (UDP, we're looking at you). 📡
Primary (PITM, bool, D) — primary item in ISOBMFF. 👑
DFMode (DFWD, uint, D) — DASH forward mode is used for this PID. If it's 2, the manifest is also carried in the packet property. 🚀
DFManifest (DMPD, str, DP) — value of the manifest in forward mode. 📄
DFVariant (DHLV, strl, DP) — value of the variant playlist in forward mode. 📃
DFVariantName (DHLN, strl, DP) — value of the variant playlist name in forward mode. 🏷️
DFPStart (DPST, luint, D) — value of the active period start time in ms, in forward mode. ⏳
DFPckPStart (PDPS, bool, DP) — indicates a new period start. Quick note: it's only set on the first packets of non-first periods. 🆕
HLSKey (HLSK, str, ) — URI, KEYFORMAT and KEYFORMATVERSIONS for HLS full segment encryption creation, otherwise the Key URI (decoding and sample-AES). 🔑
HLSIV (HLSI, mem, ) — init Vector for HLS decode. 🧿
CKUrl (CCKU, str, ) — URL for the ClearKey licence server. 🔓
ColorPrimaries (CPRM, cprm, D) — color primaries. 🌈
ColorTransfer (CTRC, ctfc, D) — color transfer characteristics. 🎨
ColorTransferAlternative (CATC, ctfc, D) — alternative color transfer characteristics. 🖌️
ColorMatrix (CMXC, cmxc, D) — color matrix coefficient. 🔲
FullRange (CFRA, bool, D) — color full range flag. 🎚️
Chroma (CFMT, uint, D) — chroma format (see ISO/IEC 23001-8 / 23091-2). 🧪
ChromaLoc (CLOC, uint, D) — chroma location (see ISO/IEC 23001-8 / 23091-2). 📍
ContentLightLevel (CLLI, mem, D) — content light level, i.e. the payload of the clli box (see ISO/IEC 14496-12). Can be set as a list of 2 integers in fragment declaration (e.g. "=max_cll,max_pic_avg_ll"). 💡
MasterDisplayColour (MDCV, mem, D) — master display colour info, i.e. the payload of the mdcv box (see ISO/IEC 14496-12). Can be set as a list of 10 integers in fragment declaration (e.g. "=dpx0,dpy0,dpx1,dpy1,dpx2,dpy2,wpx,wpy,max,min"). 🖥️
ICC (ICCP, mem, D) — ICC profile (see ISO 15076-1 or ICC.1). 🎯
SrcMagic (PSMG, luint, D) — magic number to store in the track, only used by importers. 🪄
MuxIndex (TIDX, uint, D) — target track index in the destination file, stored by lowest value first (not set by demultiplexers). 🔢
NoTSLoop (NTSL, bool, ) — timestamps on this PID get adjusted in case of loops (used by TS multiplexer output). 🔄
MHAProfiles (MHCP, uintl, D) — list of compatible profiles for this MPEG-H Audio object. 🎧
FragStart (PFRB, uint, DP) — the packet is a fragment start (value 1) or a segment start (value 2). 🏁
FragRange (PFRR, lfrac, DP) — start and end position in bytes of the fragment, if the packet is a fragment or segment start. 📏
FragTFDT (PFRT, luint, DP) — decode time of the first packet in the fragment. ⏱️
SIDXRange (PFSR, lfrac, DP) — start and end position in bytes of sidx in the segment, if any. 📦
VODSIDXRange (PRSR, lfrac, D) — start and end position in bytes of the root sidx. 🌳
MoofTemplate (MFTP, mem, DP) — serialized moof box corresponding to the start of a movie fragment or segment (with styp and optionally sidx). 🧱
InitSeg (PCKI, bool, P) — set to true if the packet is a complete DASH init segment file. 🚪
RawGrab (PGRB, uint, D) — the PID is a raw media grabber (webcam, microphone, etc...). Value 2 is used for front camera. 📸
KeepAfterEOS (PKAE, bool, D) — the PID must be kept alive after EOS (LASeR and BIFS). 🧟
CoverArt (PCOV, mem, D) — PID cover art image data. If the associated data is NULL, the data is carried in the PID. 🖼️
BufferLength (PBPL, uint, D) — playout buffer in ms. ⏳
MaxBuffer (PBMX, uint, D) — maximum buffer occupancy in ms. 📊
ReBuffer (PBRE, uint, D) — rebuffer threshold in ms, 0 disables rebuffering. 🔃
ViewIdx (VIDX, uint, D) — view index for multiview (1 being left). 👀
FragURL (OFRA, str, D) — fragment URL (without #) of the original URL (used by some filters to set the property on media PIDs). 🔗
MCASTIP (MSIP, str, D) — session Multicast IP address for ROUTE/MABR. 📶
MCASTPort (MSPN, uint, D) — session port number for ROUTE/MABR. 🚪
MCASTName (MSFN, str, D) — name (location) of the raw file to advertise in the ROUTE/MABR session. 📢
MCASTCarousel (MSCR, frac, D) — carousel period in seconds of the raw file, or of low-latency manifest/init segments, for ROUTE/MABR sessions. 🎠
MCASTUpload (MSST, frac, D) — upload time in seconds of raw files for ROUTE/MABR sessions. ⬆️
Stereo (PSTT, uint, D) — the stereo type of the video 👀
Projection (PPJT, uint, D) — the projection type of the video, it's giving immersive 🌀
InitialPose (PPOS, v3di, D) — initial pose for 360 video, in degrees expressed as 16.16 bits (x is yaw, y is pitch, z is roll) — so you know exactly where the camera's looking at frame zero 🎥
CMPad (PCMP, uint, D) — number of pixels to pad from the edge of each face in a cube map ✨
EQRClamp (PEQC, v4di, D) — clamping of the frame for EQR as 0.32 fixed point (x is top, y is bottom, z is left and w is right)
SceneNode (PSND, bool, ) — PID is a scene node decoder (AFX BitWrapper in BIFS)
OrigCryptoScheme (POCS, 4cc, ) — original crypto scheme on a decrypted PID 🔐
TSBSegs (PTSN, uint, D) — time shift in number of segments for HAS streams, only set by dashin and dasher filters
IsManifest (PHSM, uint, D) — PID is a HAS manifest (bit 9 set to 1 if live), and the lower 8 bits value can be:
- 0: not a manifest
- 1: DASH manifest
- 2: HLS manifest
- 3: GHI(X) manifest
Sparse (PSPA, bool, D) — PID has potentially empty times between packets 🕳️
CharSet (PCHS, str, D) — character set for an input text PID
ForcedSub (PFCS, uint, D) — PID forced sub, and the values are:
- 0: not forced
- 1: some frames are forced
- 2: all frames are forced
ChapTimes (CHPT, uintl, D) — chapter start times 📖
ChapNames (CHPN, strl, D) — chapter names
IsChap (PCHP, bool, D) — subtitle PID is a chapter (for QT-like chapters)
SkipBegin (PCKS, uint, P) — amount of media to skip from the beginning of the packet, in PID timescale (when set on PID, it indicates packets with skip will be present)
SkipPres (PCKD, bool, P) — this packet and any following with a CTS greater than this packet shall not be presented (used by the reframer to create edit lists)
OriginalDuration (PCOD, frac, P) — elapsed time (.num) and original duration (.den, 0 if last copy of packet) for redundant packets
HasSkipBegin (PSBP, bool, ) — indicates if the PID will carry packets with SkipBegin properties
HLSRef (PHLR, luint, D) — HLS playlist reference, gives a unique ID identifying the media mux, and it's indicated in packets carrying child playlists
PckHLSRef (HPLR, luint, DP) — same as HLSRef but carried on packets for ROUTE/MABR file transfer
LLHAS (HLHS, uint, D) — DASH/HLS low latency mode ⚡
LLHASFragNum (HLSN, uint, DP) — DASH-SSR/LLHLS fragment number
DownloadSession (GHTT, ptr, D) — pointer to the download session
HasTemi (PTEM, bool, D) — TEMI present flag
XPSMask (PXPM, uint, DP) — parameter set mask
RangeEnd (PCER, bool, P) — signals the packet is the last one in the desired play range 🏁
RefID (PKID, sint, P) — packet identifier for dependency (usually POC for video)
Refs (PRFS, sintl, P) — list of packet identifiers this packet depends on
UDTA (PUDT, ptr, DP) — user data for the packet
Timecode (TCOD, mem, P) — first timecode extracted from SEI (if present) ⏱️
DOVI (DOVI, mem, ) — DolbyVision configuration
OutPath (FDST, str, ) — output file name of the PID, used by some filters creating additional raw PIDs
ACrypMeta (AMET, mem, ) — meta-data for Adobe encryption
HasCRoll (CROL, bool, ) — indicates if key roll is used in CENC
STSDAllTemplates (ISTA, mem, D) — ISOBMFF serialized sample description box for this PID
STSDTemplateIdx (ISTI, uint, D) — index of the corresponding STSDAllTemplates
PremuxType (PPST, uint, ) — main streamtype of the PID before mux, only used for ROUTE/MABR setup
CodecMerge (PCMB, uint, D) — indicates the PID can be merged with other streams having the same value for single decoding (HEVC only for now)
RelativePath (FNRL, bool, DP) — indicates the packet file name uses a relative path
ClearKeyID (CCKI, mem, D) — key ID for the ClearKey scheme 🔑
DashSparse (DSSG, bool, D) — indicates DASH segments are generated in sparse mode (from context)
DashDepGroup (DGDI, uint, D) — indicates the DASH dependency group ID
SC35Ref (SC35, uint, D) — PID has SCTE35 information carried on the indicated PID number
NoInit (PNIN, bool, D) — PID does not use any init segment in DASH (file forward mode of dasher, only used for ROUTE/MABR)
ForceUnframe (PFUF, bool, D) — force creation of a rewriter filter (only used for forcing reparse of NALU-based codecs)
MetaCodecID (MDCI, uint, D) — identifier for meta codecs (FFmpeg, ...)
MetaCodecName (MDCN, str, D) — name used for meta codecs (FFmpeg, ...)
MetaCodecOpaque (MDOP, uint, D) — internal property used for meta demuxers (FFmpeg, ...) codec opaque data
HASSegStart (FMSS, lfrac, DP) — start time of the segment for ROUTE/MABR scheduling
SplitStart (PSPS, uint, DP) — split start time of the packet in PID timescale, for index-based dashing
SplitEnd (PSPE, uint, DP) — split end time of the packet in PID timescale, for index-based dashing
InitName (PINM, str, D) — name of the init segment when dashing, used for ROUTE/MABR
SegURL (SURL, str, DP) — URL of the source segment (when forwarding fragment boundaries)
DynPSSH (PSHP, mem, P) — PSSH blob for CENC, same format as CENC_PSSH, used when using master key and roll keys, signaled on the first packet of the segment where the PSSH changes
LLHASTemplate (PSRT, str, P) — template for DASH-SSR and LLHLS sub-segments
PartialRepair (PCPR, bool, P) — indicates the mux data in the associated data is parsable but contains errors (only set on corrupted packets) 😭
SEILoaded (PSEI, bool, D) — indicates that the PID is extracting SEI/inband data from packets
Fake (PFAK, bool, D) — indicates a stream present in the source but not delivered as a PID
ContentLightLevel (CLLP, mem, DP) — content light level, the payload of the clli box (see ISO/IEC 14496-12), and it can be set as a list of 2 integers in the fragment declaration (e.g. "=max_cll,max_pic_avg_ll")
MasterDisplayColour (MDCP, mem, DP) — master display colour info, the payload of the mdcv box (see ISO/IEC 14496-12), and it can be set as a list of 10 integers in the fragment declaration (e.g. "=dpx0,dpy0,dpx1,dpy1,dpx2,dpy2,wpx,wpy,max,min")
SEILoaded (SEIP, bool, DP) — indicates that the packet has SEI/inband data in its properties (yes bestie, this one's a different property than the PSEI one above, don't @ me 💀)
OriginalPTS (OPTS, luint, DP) — indicates the original PTS or PCR when remapping M2TS PCR
OriginalDTS (ODTS, luint, DP) — indicates the original DTS when remapping M2TS PCR
MABRBaseURLs (MABU, strl, D) — optional URLs for MABR — if the first one is none, the source server is not declared as a repair server
Forced (PCFS, bool, DP) — indicates the packet is a forced subtitle

🎨✨ Pixel formats ✨🎨

okay so this is the full roster of pixel formats GPAC knows about, each with its file extension vibe 💅 every single one, no skipping:

yuv420 (ext *.yuv) — Planar YUV 420 8 bit
yvu420 (ext *.yvu) — Planar YVU 420 8 bit
yuv420_10 (ext *.yuvl) — Planar YUV 420 10 bit
yuv422 (ext *.yuv2) — Planar YUV 422 8 bit
yuv422_10 (ext *.yp2l) — Planar YUV 422 10 bit
yuv444 (ext *.yuv4) — Planar YUV 444 8 bit
yuv444_10 (ext *.yp4l) — Planar YUV 444 10 bit
uyvy (ext *.uyvy) — Packed UYVY 422 8 bit
vyuy (ext *.vyuy) — Packed VYUV 422 8 bit
yuyv (ext *.yuyv) — Packed YUYV 422 8 bit
yvyu (ext *.yvyu) — Packed YVYU 422 8 bit
uyvl (ext *.uyvl) — Packed UYVY 422 10->16 bit
vyul (ext *.vyul) — Packed VYUV 422 10->16 bit
yuyl (ext *.yuyl) — Packed YUYV 422 10->16 bit
yvyl (ext *.yvyl) — Packed YVYU 422 10->16 bit
nv12 (ext *.nv12) — Semi-planar YUV 420 8 bit, Y plane and UV packed plane
nv21 (ext *.nv21) — Semi-planar YVU 420 8 bit, Y plane and VU packed plane
nv1l (ext *.nv1l) — Semi-planar YUV 420 10 bit, Y plane and UV plane
nv2l (ext *.nv2l) — Semi-planar YVU 420 8 bit, Y plane and VU plane
yuva (ext *.yuva) — Planar YUV+alpha 420 8 bit
yuvd (ext *.yuvd) — Planar YUV+depth 420 8 bit
yuv444a (ext *.yp4a) — Planar YUV+alpha 444 8 bit
yuv444p (ext *.yv4p) — Packed YUV 444 8 bit
v308 (ext *.v308) — Packed VYU 444 8 bit
yuv444ap (ext *.y4ap) — Packed YUV+alpha 444 8 bit
v408 (ext *.v408) — Packed UYV+alpha 444 8 bit
v410 (ext *.v410) — Packed UYV 444 10 bit LE
v210 (ext *.v210) — Packed UYVY 422 10 bit LE
grey (ext *.grey) — Greyscale 8 bit
algr (ext *.algr) — Alpha+Grey 8 bit
gral (ext *.gral) — Grey+Alpha 8 bit
rgb8 (ext *.rgb8) — RGB 332, 8 bits / pixel
rgb4 (ext *.rgb4) — RGB 444, 12 bits (16 stored) / pixel
rgb5 (ext *.rgb5) — RGB 555, 15 bits (16 stored) / pixel
rgb6 (ext *.rgb6) — RGB 555, 16 bits / pixel
rgba (ext *.rgba) — RGBA 32 bits (8 bits / component)
argb (ext *.argb) — ARGB 32 bits (8 bits / component)
bgra (ext *.bgra) — BGRA 32 bits (8 bits / component)
abgr (ext *.abgr) — ABGR 32 bits (8 bits / component)
rgb (ext *.rgb) — RGB 24 bits (8 bits / component)
bgr (ext *.bgr) — BGR 24 bits (8 bits / component)
xrgb (ext *.xrgb) — xRGB 32 bits (8 bits / component)
rgbx (ext *.rgbx) — RGBx 32 bits (8 bits / component)
xbgr (ext *.xbgr) — xBGR 32 bits (8 bits / component)
bgrx (ext *.bgrx) — BGRx 32 bits (8 bits / component)
rgbd (ext *.rgbd) — RGB+depth 32 bits (8 bits / component)
rgbds (ext *.rgbds) — RGB+depth+bit shape (8 bits / RGB component, 7 bit depth (low bits) + 1 bit shape)
extgl (ext *.extgl) — External OpenGL texture of unknown format, to be used with samplerExternalOES
uncv (ext *.uncv) — Generic uncompressed format ISO/IEC 23001-17

and that's the whole pixel-format lineup, no cap 🌈 every single one got its moment 💖

🎧 Audio formats 🎧

okay so these are the raw PCM sample formats GPAC knows about, and every single one comes with its own file extension vibe. lowkey satisfying list ngl 💖

u8 (ext *.pc8) — 8 bit PCM
s16 (ext *.pcm) — 16 bit PCM Little Endian
s16b (ext *.pcmb) — 16 bit PCM Big Endian
s24 (ext *.s24) — 24 bit PCM
s24b (ext *.s24b) — 24 bit Big-Endian PCM
s32 (ext *.s32) — 32 bit PCM Little Endian
s32b (ext *.s32b) — 32 bit PCM Big Endian
flt (ext *.flt) — 32-bit floating point PCM
fltb (ext *.fltb) — 32-bit floating point PCM Big Endian
dbl (ext *.dbl) — 64-bit floating point PCM
dblb (ext *.dblb) — 64-bit floating point PCM Big Endian
u8p (ext *.pc8p) — 8 bit PCM planar
s16p (ext *.pcmp) — 16 bit PCM Little Endian planar
s24p (ext *.s24p) — 24 bit PCM planar
s32p (ext *.s32p) — 32 bit PCM Little Endian planar
fltp (ext *.fltp) — 32-bit floating point PCM planar
dblp (ext *.dblp) — 64-bit floating point PCM planar

🎬 Stream types 🎬

the roster of what a stream can actually be. main character energy for each one, no notes ✨

Visual — Video or Image stream
Audio — Audio stream
SceneDescription — Scene stream
Text — Text or subtitle stream
Metadata — Metadata stream
File — Raw file stream
Encrypted — Encrypted media stream
ObjectDescriptor — MPEG-4 ObjectDescriptor stream
ClockReference — MPEG-4 Clock Reference stream
MPEG7 — MPEG-7 description stream
IPMP — MPEG-4 IPMP/DRM stream
OCI — MPEG-4 ObjectContentInformation stream
MPEGJ — MPEG-4 JAVA stream
Interaction — MPEG-4 Interaction Sensor stream
Font — MPEG-4 Font stream

🧬 Codecs 🧬

this is the big one bestie. every codec name GPAC will answer to, plus what it actually is. some of these have multiple aliases separated by |, and yes you can use any of them. and yes, a couple of them show up twice in this list — that's not me being sloppy, that's literally what's in the page, so I'm keeping it 💅

bifs — MPEG-4 BIFS v1 Scene Description
bifs2 — MPEG-4 BIFS v2 Scene Description
bifsX — MPEG-4 BIFS Extended Scene Description
od — MPEG-4 ObjectDescriptor v1
od2 — MPEG-4 ObjectDescriptor v2
interact — MPEG-4 Interaction Stream
afx — MPEG-4 AFX Stream
font — MPEG-4 Font Stream
syntex — MPEG-4 Synthetized Texture
m4txt — MPEG-4 Streaming Text
laser — MPEG-4 LASeR
saf — MPEG-4 Simple Aggregation Format
cmp|m4ve|m4v — MPEG-4 Visual part 2
264|avc|h264 — MPEG-4 AVC|H264 Video
avcps — MPEG-4 AVC|H264 Video Parameter Sets
svc|avc|264|h264 — MPEG-4 AVC|H264 Scalable Video Coding
mvc — MPEG-4 AVC|H264 Multiview Video Coding
hvc|hevc|h265 — HEVC Video
lhvc|shvc|mhvc — HEVC Video Layered Extensions
m2vs — MPEG-2 Visual Simple
m2v — MPEG-2 Visual Main
m2v|m2vsnr — MPEG-2 Visual SNR
m2v|m2vspat — MPEG-2 Visual Spatial
m2v|m2vh — MPEG-2 Visual High
m2v|m2v4 — MPEG-2 Visual 422
m1v — MPEG-1 Video
jpg|jpeg — JPEG Image
png — PNG Image
jp2|j2k — JPEG2000 Image
aac — MPEG-4 AAC Audio
aac|aac2m — MPEG-2 AAC Audio Main
aac|aac2l — MPEG-2 AAC Audio Low Complexity
aac|aac2s — MPEG-2 AAC Audio Scalable Sampling Rate
mp3|m1a — MPEG-1 Audio
mp2 — MPEG-2 Audio
mp1 — MPEG-1 Audio Layer 1
h263 — H263 Video
h263 — H263 Video
hvt1 — HEVC tiles Video
evc|evrc — EVRC Voice
smv — SMV Voice
qcp|qcelp — QCELP Voice
amr — AMR Audio
amr|amrwb — AMR WideBand Audio
qcp|evrcpv — EVRC (PacketVideo MUX) Audio
vc1 — SMPTE VC-1 Video
dirac — Dirac Video
ac3 — AC3 Audio
eac3 — Enhanced AC3 Audio
ac4 — AC4 Audio
mlp — Dolby TrueHD
dra — DRA Audio
g719 — G719 Audio
dtsc — DTS Coherent Acoustics and Digital Surround Audio
dtsh — DTS-HD High Resolution Audio and DTS-Master Audio
dtsl — DTS-HD Substream containing only XLLAudio
dtse — DTS Express low bit rate Audio
dtsx — DTS-X UHD Audio Profile 2
dtsy — DTS-X UHD Audio Profile 3
opus — Opus Audio
eti — DVB Event Information
svgr — SVG over RTP
svgzr — SVG+gz over RTP
dims — 3GPP DIMS Scene
vtt — WebVTT Text
txt — Simple Text Stream
mtxt — Metadata Text Stream
mxml — Metadata XML Stream
subs — Subtitle text Stream
subx — Subtitle XML Stream
tx3g — Subtitle/text 3GPP/Apple Stream
ssa — SSA /ASS Subtitles
theo|theora — Theora Video
vorb|vorbis — Vorbis Audio
opus — Opus Audio
iamf — AOM IAMF (Immersive Audio Model and Formats)
flac — Flac Audio
spx|speex — Speex Audio
vobsub — VobSub Subtitle
vobsub — VobSub Subtitle
adpcm — AD-PCM
csvd — IBM CSVD
alaw — ALAW
mulaw — MULAW
okiadpcm — OKI ADPCM
dviadpcm — DVI ADPCM
digistd — DIGISTD
yamadpcm — YAMAHA ADPCM
truespeech — DSP TrueSpeech
g610 — GSM 610
imulaw — IBM MULAW
ialaw — IBM ALAW
iadpcl — IBM ADPCL
swf — Adobe Flash
raw — Raw media
uncv — Raw Video
av1|ivf|obu|av1b — AOM AV1 Video
vp8|ivf — VP8 Video
vp9|ivf — VP9 Video
vp10|ivf — VP10 Video
avsv|avs3 — AVS3 Video
avsa|avs3 — AVS3 Audio
mhas — MPEG-H Audio
mhas — MPEG-H AudioMux
prores|apch — ProRes Video 422 HQ
prores|apco — ProRes Video 422 Proxy
prores|apcn — ProRes Video 422 STD
prores|apcs — ProRes Video 422 LT
prores|ap4x — ProRes Video 4444 XQ
prores|ap4h — ProRes Video 4444
ffmpeg — FFmpeg unmapped codec
tmcd — QT TimeCode
sc35 — SCTE35
evte — Event Messages
vvc|266|h266 — VVC Video
vvs1 — VVC Subpicture Video
usac|xheaac — xHEAAC / USAC Audio
ffv1 — FFmpeg Video Codec 1
dvbs — DVB Subtitles
dvbs — DVB-TeleText
div3 — MS-MPEG4 V3
caf — Apple Lossless Audio
dnx — AViD DNxHD

🌈 Stream types 🌈

no bestie you're not losing it — this section is also called Stream types, that's just how the page is. but this one is the audio channel layout table: a name, an int, and the hex layout value. obsessed with how chaotic that is fr fr 🫶

mono (int 1) — Layout 0x0000000000000004
stereo (int 2) — Layout 0x0000000000000003
3/0.0 (int 3) — Layout 0x0000000000000007
3/1.0 (int 4) — Layout 0x0000000000000407
3/2.0 (int 5) — Layout 0x0000000000000037
3/2.1 (int 6) — Layout 0x000000000000003f
5/2.1 (int 7) — Layout 0x000000000000003f
1+1 (int 8) — Layout 0x0000000000000003
2/1.0 (int 9) — Layout 0x0000000000000403
2/2.0 (int 10) — Layout 0x0000000000000033
3/3.1 (int 11) — Layout 0x000000000000043f
3/4.1 (int 12) — Layout 0x000000000000033f
11/11.2 (int 13) — Layout 0x000000003ffe67cf
5/2.1 (int 14) — Layout 0x000000000006003f
5/5.2 (int 15) — Layout 0x000000000606603f
5/4.1 (int 16) — Layout 0x000000000036003f
6/5.1 (int 17) — Layout 0x00000000023e003f
6/7.1 (int 18) — Layout 0x00000600023e003f
5/6.1 (int 19) — Layout 0x000000000036630f
7/6.1 (int 20) — Layout 0x000000600036630f

💫 EXAMPLES 💫

want to see this stuff actually in action? basic and advanced examples live right here:

https://wiki.gpac.io/Filters/Filters

🫶 MORE 🫶

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: 26.02
Copyright: (c) 2000-2024 Telecom Paris distributed under LGPL v2.1+ - https://gpac.io

👀 SEE ALSO 👀

gpac-filters(1)
MP4Box(1)

okay that's the whole page bestie, you made it to the end and honestly? iconic behavior 💖 this was gpac(1), dated 2019, manual page for the gpac tool itself. go forth and mux something gorgeous. slay 🎀🦋💅

📦 where this page comes from

fedora 44: gpac 26.02.0-1.fc44 · LGPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms

gpac(1)

🌸 gpac(1) 🌸

✨ NAME ✨

🦋 SYNOPSIS 🦋

💜 DESCRIPTION 💜

🌈 OPTIONS 🌈

🧚 libgpac core options 🧚

✨ Using Aliases ✨

🔐 User Credentials 🔐

🧪 Defer test mode 🧪

🌸 Configuration file 🌸

🧁 Core options

🎀 Filter options in configuration

🌈 Global filter options

💖 libgpac core options:

📝 libgpac logs options ✨

🌸 Overview 🌸

✨ Property and filter option format ✨

💅 Filter declaration [FILTER] 💅

🦋 Generic declaration 🦋

🌈 Source and Sink filters 🌈

⭐ Forcing specific filters ⭐

🧚 Specifying encoders and decoders 🧚

💜 Escaping option separators 💜

🔗 Filter linking [LINK] 💫

✨ Default filter linking ✨

🎀 Quick links 🎀

💜 Complex links 💜

🌈 Sub-session tagging 🌈

Arguments inheriting 🎀

URL templating 🌈

Cloning filters 💀

Templating filter chains 🫶

Assigning PID properties 💖

🌸 Using option files 🌸

🦋 Ignoring filters at run-time 🦋

💜 Specific filter options 💜

🌈 External filters 🌈

👑 GPAC Built-in properties 👑

✨ Built-in property types ✨

🎀 Built-in properties for PIDs and packets 🎀

🎨✨ Pixel formats ✨🎨

🎧 Audio formats 🎧

🎬 Stream types 🎬

🧬 Codecs 🧬

🌈 Stream types 🌈

💫 EXAMPLES 💫

🫶 MORE 🫶

👀 SEE ALSO 👀