FreeBSD Manual Pages
gpac(1) GPAC gpac(1) NAME gpac - GPAC command-line filter session manager SYNOPSIS gpac [options]FILTER[LINK]FILTER[...] gpac is GPAC's command line tool for setting up and running filter chains. FILTER: a single filter declaration (e.g., -i file, -o dump, inspect, ...), see gpac -h doc. [LINK]: a link instruction (e.g., @, @2, @2#StreamType=Visual, ...), see gpac -h doc. [options]: one or more option strings, each starting with a - charac- ter. - an option using a single - indicates an option of gpac (see gpac -hx) or of libgpac (see gpac -hx core) - an option using -- indicates a global filter or meta-filter (e.g. FFMPEG) option, e.g. --block_size=1000 or --profile=Baseline (see gpac -h doc) Filter declaration order may impact the link resolver which will try linking in declaration order. Most of the time for simple graphs, this has no impact. However, for complex graphs with no link declarations, this can lead to different results. Options do not require any specific order, and may be present anywhere, including between link statements or filter declarations. Boolean values do not need any value specified. Other types shall be formatted as opt=val, except .I -i, -src, .I -o, -dst and .I -h op- tions. The session can be interrupted at any time using ctrl+c, which can also be used to toggle global reporting. The possible options for gpac are: -mem-track enable memory tracker -mem-track-stack enable memory tracker with stack dumping -ltf load test-unit filters (used for for unit tests only) -sloop (int) loop execution of session, creating a session at each loop, mainly used for testing. If no value is given, loops forever -runfor (int) run for the given amount of milliseconds, exit with full session flush -runforf (int) run for the given amount of milliseconds, exit with fast session flush -runforx (int) run for the given amount of milliseconds and exit with no cleanup -runfors (int) run for the given amount of milliseconds and exit with segfault (tests) -runforl (int) run for the given amount of milliseconds and wait forever at end (tests) -stats print stats after execution -graph print graph after execution -qe enable quick exit (no mem cleanup) -k enable keyboard interaction from command line -r (string) enable reporting * r: runtime reporting * r=FA[,FB]: runtime reporting but only print given filters, e.g. r=mp4mx for ISOBMFF multiplexer only * r=: only print final report -seps (string, default: :=#,!@) set the default character sets used to separate various argu- ments - the first char is used to separate argument names - the second char, if present, is used to separate names and values - the third char, if present, is used to separate fragments for PID sources - the fourth char, if present, is used for list separators (sourceIDs, gfreg, ...) - the fifth char, if present, is used for boolean negation - the sixth char, if present, is used for LINK directives (see filters help (-h doc)) -i,-src (string) specify an input file - see filters help (-h doc) -o,-dst (string) specify an output file - see filters help (-h doc) -ib (string) specify an input file to wrap as GF_FileIO object (testing of GF_FileIO) -ibx (string) specify an input file to wrap as GF_FileIO object without caching (testing of GF_FileIO) -ob (string) specify an output file to wrap as GF_FileIO object (testing of GF_FileIO) -cl force complete mode when no link directive are set - see filters help (-h doc) -step test step mode in non-blocking session -h,-help,-ha,-hx,-hh (string) print help. Use -help or -h for basic options, -ha for advanced options, -hx for expert options and -hh for all. Note: The @ character can be used in place of the * character. String parameter can be: * empty: print command line options help * doc: print the general filter info * alias: print the gpac alias syntax * log: print the log system help * core: print the supported libgpac core options. Use -ha/-hx/-hh for advanced/expert options * cfg: print the GPAC configuration help * net: print network interfaces * prompt: print the GPAC prompt help when running in interactive mode (see .I -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 in- clude 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 prop- erties 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 fil- ters (use -hx to view src->dst cap bundle detail) * links FNAME: print sources and sinks for filter FNAME (either builtin or JS filter) * FNAME: print filter FNAME info (multiple FNAME can be given) - For meta-filters, use FNAME:INST, e.g. ffavin:avfoundation - Use * to print info on all filters (big output!), *:* to print info on all filters including meta filter instances (re- ally 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 in- cluding 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 pos- sible matches if none found. Use -hx to look for keyword in all option descriptions -p (string) use indicated profile for the global GPAC config. If not found, config file is created. If a file path is indicated, this will load profile from that file. Otherwise, this will create a di- rectory of the specified name and store new config there. The following reserved names create a temporary profile (not stored on disk): * 0: full profile * n: null profile disabling shared modules/filters and system paths in config (may break GUI and other filters) Appending :reload to the profile name will force recreating a new configuration file -alias (string) assign a new alias or remove an alias. Can be specified several times. See alias usage (-h alias) -aliasdoc (string) assign documentation for a given alias (optional). Can be speci- fied several times -uncache revert all items in GPAC cache directory to their original name and server path -js (string) specify javascript file to use as controller of filter session -wc write all core options in the config file unless already set -we write all file extensions in the config file unless already set (useful to change some default file extensions) -wf write all filter options in the config file unless already set -wfx write all filter options and all meta filter arguments in the config file unless already set (large config file !) -xopt unrecognized options and filters declaration following this op- tion are ignored - used to pass arguments to GUI -creds (string) setup credentials as used by servers The following libgpac core options allow customizing the filter session: -dbg-edges log edges status in filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status(disable_depth), weight, src_cap_idx -> dst_cap_idx) -full-link throw error if any PID in the filter graph cannot be linked -no-dynf disable dynamically loaded filters -no-block (Enum, default: no) disable blocking mode of filters * no: enable blocking mode * fanout: disable blocking on fan-out, unblocking the PID as soon as one of its destinations requires a packet * all: disable blocking -no-reg disable regulation (no sleep) in session -no-reassign disable source filter reassignment in PID graph resolution -sched (Enum, default: free) set scheduler mode * free: lock-free queues except for task list (default) * lock: mutexes for queues when several threads * freex: lock-free queues including for task lists (experimen- tal) * flock: mutexes for queues even when no thread (debug mode) * direct: no threads and direct dispatch of tasks whenever pos- sible (debug mode) -max-chain (int, default: 6) set maximum chain length when resolving filter links. Default value covers for [ in -> ] dmx -> reframe -> decode -> encode -> reframe -> mx [ -> out]. Filter chains loaded for adaptation (e.g. pixel format change) are loaded after the link resolution. Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually -max-sleep (int, default: 50) set maximum sleep time slot in milliseconds when regulation is enabled -threads (int) set N extra thread for the session. -1 means use all available cores -no-probe disable data probing on sources and relies on extension (faster load but more error-prone) -no-argchk disable tracking of argument usage (all arguments will be con- sidered as used) -blacklist (string) blacklist the filters listed in the given string (comma-sepa- rated list). If first character is '-', this is a whitelist, i.e. only filters listed in the given string will be allowed -no-graph-cache disable internal caching of filter graph connections. If dis- abled, the graph will be recomputed at each link resolution (lower memory usage but slower) -no-reservoir disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more -buffer-gen (int, default: 1000) default buffer size in microseconds for generic pids -buffer-dec (int, default: 1000000) default buffer size in microseconds for decoder input pids -buffer-units (int, default: 1) default buffer size in frames when timing is not available Using Aliases The gpac command line can become quite complex when many sources or filters are used. In order to simplify this, an alias system is pro- vided. To assign an alias, use the syntax gpac -alias="NAME VALUE". * `NAME`: shall be a single string, with no space. * `VALUE`: the list of argument this alias replaces. If not set, the alias is destroyed When parsing arguments, the alias will be replace by its value. Example gpac -alias="output aout vout" This allows later audio and video playback using gpac -i src.mp4 output Aliases can use arguments from the command line. The allowed syntaxes are: * `@{a}`: replaced by the value of the argument with index a after the alias * `@{a,b}`: replaced by the value of the arguments with index a and b * `@{a:b}`: replaced by the value of the arguments between index a and b * `@{-a,b}`: replaced by the value of the arguments with index a and b, inserting a list separator (comma by default) between them * `@{-a:b}`: replaced by the value of the arguments between index a and b, inserting a list separator (comma by default) between them * `@{+a,b}`: clones the parent word in the alias for a and b, replacing this pattern in each clone by the corresponding argument * `@{+a:b}`: clones the parent word in the alias for each argument be- tween index a and b, replacing this pattern in each clone by the corre- sponding argument The specified index can be: * forward index: a strictly positive integer, 1 being the first argu- ment 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 op- tions. Arguments not used by any aliases are kept on the command line, other ones are removed Example -alias="foo src=@{N} dst=test.mp4" The command gpac foo f1 f2 expands to gpac src=f2 dst=test.mp4 f1 Example -alias="list: inspect src=@{+:N}" The command gpac list f1 f2 f3 expands to gpac inspect src=f1 src=f2 src=f3 Example -alias="list inspect src=@{+2:N}" The command gpac list f1 f2 f3 expands to gpac inspect src=f2 src=f3 f1 Example -alias="plist aout vout flist:srcs=@{-,N}" The command gpac plist f1 f2 f3 expands to gpac aout vout flist:srcs="f1,f2,f3" Alias documentation can be set using gpac -aliasdoc="NAME VALUE", with NAME the alias name and VALUE the documentation. Alias documentation will then appear in gpac help. User Credentials Some servers in GPAC can use user-based and group-based authentication. The information is stored by default in the file users.cfg located in the GPAC profile directory. The file can be overwritten using the .I -users option. By default, this file does not exist until at least one user has been configured. The .I creds option allows inspecting or modifying the users and groups information. The syntax for the option value is: * `show` or no value: prints the users.cfg file * `reset`: deletes the users.cfg file (i.e. deletes all users and groups) * `NAME`: show information of user NAME * `+NAME`: adds user NAME * `+NAME:I1=V1[,I2=V2]`: sets info I1 with value V1 to user NAME. The info name password resets password without prompt. * `-NAME`: removes user NAME * `_NAME`: force password change of user NAME * `@NAME`: show information of group NAME * `@+NAME[:u1[,u2]]`: adds group NAME if not existing and adds speci- fied 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 de- scribing 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 direc- tory * rg: comma-separated list of group names with read access to the di- rectory * wu: comma-separated list of user names with write access to the di- rectory * wg: comma-separated list of group names with write access to the di- rectory * 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. Configuration file GPAC uses a configuration file to modify default options of libgpac and filters. This file is called GPAC.cfg and is located: - on Windows platforms, in C: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, oth- erwise in /data/data/io.gpac.gpac/GPAC. - on other platforms, in a $HOME/.gpac/. Applications in GPAC can also specify a different configuration file through the .I -p profile option. EX gpac -p=foo [] This will load configuration from $HOME/.gpac/foo/GPAC.cfg, creating it if needed. The reserved name 0 is used to disable configuration file writing. The configuration file is structured in sections, each made of one or more keys: - section foo is declared as [foo] - key bar with value N is declared as bar=N0 The key value N is not in- terpreted and always handled as ASCII text. By default the configuration file only holds a few system specific op- tions and directories. It is possible to serialize the entire set of options to the configuration file, using .I -wc .I -wf. This should be avoided as the resulting configuration file size will be quite large, hence larger memory usage for the applications. The options specified in the configuration file may be overridden by the values in restrict.cfg file located in GPAC share system directory (e.g. /usr/share/gpac or C:Program FilesGPAC), if present; this allows enforcing system-wide configuration values. Note: The methods describe in this section apply to any application in GPAC transferring their arguments to libgpac. This is the case for gpac and MP4Box. 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. The options specified at prompt overrides the value of the config file. Filter options in configuration It is possible to alter the default value of a filter option by modify- ing the configuration file. Filter foo options are stored in section [filter@foo], using option name and value as key-value pair. Options specified through the configuration file do not take precedence over options specified at prompt or through alias. Example [filter@rtpin] interleave=yes This will force the rtp input filter to always request RTP over RTSP by default. To generate a configuration file with all filters options serialized, use .I -wf. Global filter options 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 fil- ter. 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 in- stances of registry FNAME. This is used when several registries use same option names. Example --flist@timescale=100 -i plist1 -i plist2 -o live.mpd This will set the timescale option on the playlists filters but not on the dasher filter. libgpac core options: -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 un- sure about threading used) -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, configura- tion 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=N: set rule mode - N can be r for reception only (default), w for send only or rw for both * s=N: set packet start range to N * e=N: set packet end range to N (only used for r and f rules) * n=N: set number of packets to drop to N - not set, 0 or 1 means single packet * r=N: random drop one packet every N * f=N: drop first packet every N * p=P: local port number to filter, if not set the rule applies to all packets * o=N: patch packet instead of droping (always true for TCP), replacing byte at offset N (0 is first byte, <0 for random) * v=N: set patch byte value to N (hexa) or negative value for random (default) 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 ses- sion2.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-on enable HTTP proxy -proxy-name (string) set HTTP proxy address -proxy-port (int, default: 80) set HTTP proxy port -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 re- source in cache) -clean-cache indicate if HTTP cache should be clean upon launch/exit -cache-size (int, default: 100M) specify cache size in bytes -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 -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) set user profile filename. Content of file is appended as body to HTTP HEAD/GET requests, associated Mime is text/xml -query-string (string) insert query string (without ?) to URL on requests -dm-threads force using threads for async download requests rather than ses- sion scheduler -cte-rate-wnd (int, default: 20) set window analysis length in milliseconds for chunk-transfer encoding rate estimation -cred (string) path to 128 bits key for credential storage -no-h2 disable HTTP2 -no-h2c disable HTTP2 upgrade (i.e. over non-TLS) -h2-copy enable intermediate copy of data in nghttp2 (default is disabled but may report as broken frames in wireshark) -dbg-edges log edges status in filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status(disable_depth), weight, src_cap_idx -> dst_cap_idx) -full-link throw error if any PID in the filter graph cannot be linked -no-dynf disable dynamically loaded filters -no-block (Enum, default: no) disable blocking mode of filters * no: enable blocking mode * fanout: disable blocking on fan-out, unblocking the PID as soon as one of its destinations requires a packet * all: disable blocking -no-reg disable regulation (no sleep) in session -no-reassign disable source filter reassignment in PID graph resolution -sched (Enum, default: free) set scheduler mode * free: lock-free queues except for task list (default) * lock: mutexes for queues when several threads * freex: lock-free queues including for task lists (experimen- tal) * flock: mutexes for queues even when no thread (debug mode) * direct: no threads and direct dispatch of tasks whenever pos- sible (debug mode) -max-chain (int, default: 6) set maximum chain length when resolving filter links. Default value covers for [ in -> ] dmx -> reframe -> decode -> encode -> reframe -> mx [ -> out]. Filter chains loaded for adaptation (e.g. pixel format change) are loaded after the link resolution. Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually -max-sleep (int, default: 50) set maximum sleep time slot in milliseconds when regulation is enabled -threads (int) set N extra thread for the session. -1 means use all available cores -no-probe disable data probing on sources and relies on extension (faster load but more error-prone) -no-argchk disable tracking of argument usage (all arguments will be con- sidered as used) -blacklist (string) blacklist the filters listed in the given string (comma-sepa- rated list). If first character is '-', this is a whitelist, i.e. only filters listed in the given string will be allowed -no-graph-cache disable internal caching of filter graph connections. If dis- abled, the graph will be recomputed at each link resolution (lower memory usage but slower) -no-reservoir disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more -buffer-gen (int, default: 1000) default buffer size in microseconds for generic pids -buffer-dec (int, default: 1000000) default buffer size in microseconds for decoder input pids -buffer-units (int, default: 1) default buffer size in frames when timing is not available -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 -glfbo-txid (int) set output texture ID when using glfbo output. The OpenGL con- text shall be initialized and gf_term_process shall be called with the OpenGL context active -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 -rescan-fonts indicate the font directory must be rescanned -wait-fonts wait for SVG fonts to be loaded before displaying frames -webvtt-hours force writing hour when serializing WebVTT -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 -rmt enable profiling through Remotery. A copy of Remotery visualizer is in gpac/share/vis, usually installed in /usr/share/gpac/vis or Program Files/GPAC/vis -rmt-port (int, default: 17815) set remotery port -rmt-reuse allow remotery to reuse port -rmt-localhost make remotery only accepts localhost connection -rmt-sleep (int, default: 10) set remotery sleep (ms) between server updates -rmt-nmsg (int, default: 10) set remotery number of messages per update -rmt-qsize (int, default: 131072) set remotery message queue size in bytes -rmt-log redirect logs to remotery (experimental, usually not well han- dled by browser) -rmt-ogl make remotery sample opengl calls -m2ts-vvc-old hack for old TS streams using 0x32 for VVC instead of 0x33 -piff-force-subsamples hack for PIFF PSEC files generated by 0.9.0 and 1.0 MP4Box with wrong subsample_count inserted for audio -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 libgpac logs options: -noprog disable progress messages -quiet disable all messages, including errors -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 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 after- wards. The special keyword ncl can be set to disable color logs. The special keyword strict can be set to exit at first error. Example -logs=all@info:dash@debug:ncl This moves all log to info level, dash to debug level and dis- able color logs -proglf use new line at each progress messages -log-dual,-ld output to both file and stderr Overview Filters are configurable processing units consuming and producing data packets. These packets are carried between filters through a data chan- nel called PID. A PID is in charge of allocating/tracking data packets, and passing the packets to the destination filter(s). A filter output PID may be connected to zero or more filters. This fan-out is handled internally by GPAC (no such thing as a tee filter in GPAC). Note: When a PID cannot be connected to any filter, a warning is thrown and all packets dispatched on this PID will be destroyed. The session may however still run, unless .I -full-link is set. Each output PID carries a set of properties describing the data it de- livers (e.g. width, height, codec, ...). Properties can be built-in (see gpac -h props ), or user-defined. Each PID tracks its properties changes and triggers filter reconfiguration during packet processing. This allows the filter chain to be reconfigured at run time, poten- tially reloading part of the chain (e.g. unload a video decoder when switching from compressed to uncompressed sources). Each filter exposes a set of argument to configure itself, using prop- erty types and values described as strings formatted with separators. This help is given with default separator sets :=#,@ to specify fil- ters, properties and options. Use .I -seps to change them. Property and filter option format * boolean: formatted as yes,true,1 or no,false,0 * enumeration (for filter arguments only): must use the syntax given in the argument description, otherwise value 0 (first in enum) is assumed. * 1-dimension (numbers, floats, ints...): formatted as value[unit], where unit can be k,K (x 1000) or m,M (x 1000000) or g,G (x 1000000000) or sec (x 1000) or min (x 60000). +I means max float/int/uint value, -I min float/int/uint value. * fraction: formatted as num/den or num-den or num, in which case the denominator is 1 if num is an integer, or 1000000 if num is a floating- point value. * unsigned 32 bit integer: formatted as number or hexadecimal using the format 0xAABBCCDD. * N-dimension (vectors): formatted as DIM1xDIM2[xDIM3[xDIM4]] values, without unit multiplier. * For 2D integer vectors, the following resolution names can be used: 360, 480, 576, 720, 1080, hd, 2k, 2160, 4k, 4320, 8k * string: formatted as: * `value`: copies value to string. * `file@FILE`: load string from local FILE (opened in binary mode). * `bxml@FILE`: binarize XML from local FILE and set property type to data - see https://wiki.gpac.io/NHML-Format. * data: formatted as: * `size@address`: constant data block, not internally copied; size gives the size of the block, address the data pointer. * `0xBYTESTRING`: data block specified in hexadecimal, internally copied. * `file@FILE`: load data from local FILE (opened in binary mode). * `bxml@FILE`: binarize XML from local FILE - see https://wiki.gpac.io/NHML-Format. * `b64@DATA`: load data from base-64 encoded DATA. * pointer: pointer address as formatted by %p in C. * string lists: formatted as val1,val2[,...]. Each value can also use file@FILE syntax. * integer lists: formatted as val1,val2[,...] Note: The special characters in property formats (0x,/,-,+I,-I,x) can- not 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 ap- pended 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 es- cape the string using the keyword gpac. Example filter:ARG=http://foo/bar?yes:gpac:opt=VAL This will properly extract the URL. Example filter:ARG=http://foo/bar?yes:opt=VAL This will fail to extract it and keep :opt=VAL as part of the URL. The escape mechanism is not needed for local source, for which file ex- istence is probed during argument parsing. It is also not needed for builtin protocol handlers (avin://, video://, audio://, pipe://) For tcp:// and udp:// protocols, the escape is not needed if a trailing / is appended after the port number. Example -i tcp://127.0.0.1:1234:OPT This will fail to extract the URL and options. Example -i tcp://127.0.0.1:1234/:OPT This will extract the URL and options. Note: one trick to avoid the escape sequence is to declare the URLs op- tion at the end, e.g. f1:opt1=foo:url=http://bar, provided you have only one URL parameter to specify on the filter. It is possible to disable option parsing (for string options) by dupli- cating 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 filter- Name:src=URL or filterName:dst=URL. The src= and dst= syntaxes can also be used in alias for dynamic argu- ment cloning (see gpac -hx alias). Forcing specific filters There is a special option called gfreg which allows specifying pre- ferred 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/en- coders will be dynamically loaded to perform the conversion, unless dy- namic resolution is disabled. There is a special shortcut filter name for encoders enc allowing to match a filter providing the desired en- coding. 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 sup- ported by codec Other options will be passed to the filter if it accepts generic argu- ment parsing (as is the case for ffmpeg). The shortcut syntax c=TYPE (e.g. c=aac:opts) is also supported. Example gpac -i dump.yuv:size=320x240:fps=25 enc:c=avc:b=150000:g=50:cgop=true:fast=true -o raw.264 This creates a 25 fps AVC at 175kbps with a gop duration of 2 seconds, using closed gop and fast encoding settings for ffmpeg. The inverse operation (forcing a decode to happen) is possible using the reframer filter. Example gpac -i file.mp4 reframer:raw=av -o null This will force decoding media from file.mp4 and trash (send to null) the result (doing a decoder benchmark for example). Escaping option separators When a filter uses an option defined as a string using the same separa- tor character as gpac, you can either modify the set of separators, or escape the separator by duplicating it. The options enclosed by dupli- cated separator are not parsed. This is mostly used for meta filters, such as ffmpeg, to pass options to sub-filters such as libx264 (cf x264opts parameter). Example f:a=foo:b=bar This will set option a to foo and option b to bar on the filter. Example f::a=foo:b=bar This will set option a to foo:b=bar on the filter. Example f:a=foo::b=bar:c::d=fun This will set option a to foo, b to bar:c and the option d to fun on the filter. Filter linking [LINK] Each filter exposes one or more sets of capabilities, called capability bundle, which are property type and values that must be matched or ex- cluded by connecting PIDs. To check the possible sources and destination for a filter FNAME, use gpac -h links FNAME The filter graph resolver uses this information together with the PID properties to link the different filters. Link directives, when provided, specify which source a filter can ac- cept connections from. They do not specify which destination a filter can connect to. Default filter linking When no link instructions are given (see below), the default linking strategy used is either implicit mode (default in gpac) or complete mode (if .I -cl is set). Each PID is checked for possible connection to all defined filters, in their declaration order. For each filter DST accepting a connection from the PID, directly or with intermediate filters: - if DST filter has link directives, use them to allow or reject PID connection. - otherwise, if complete mode is enabled, allow connection.. - otherwise (implicit mode): - if DST is not a sink and is the first matching filter with no link directive, allow connection. - otherwise, if DST is not a sink and is not the first matching filter with no link directive, reject connection. - otherwise (DST is a sink) and no previous connections to a non-sink filter, allow connection. In all linking modes, a filter can prevent being linked to a filter with no link directives by setting RSID option on the filter. This is typically needed when dynamically inserting/removing filters in an existing session where some filters have no ID defined and are not desired for the inserted chain. Example gpac -i file.mp4 c=avc -o output With this setup in implicit mode: - if the file has a video PID, it will connect to enc but not to out- put. The output PID of enc will connect to output. - if the file has other PIDs than video, they will connect to output, since this enc filter accepts only video. Example gpac -cl -i file.mp4 c=avc -o output With this setup in complete mode: - if the file has a video PID, it will connect both to enc and to out- put, and the output PID of enc will connect to output. - if the file has other PIDs than video, they will connect to output. Furthermore in implicit mode, filter connections are restricted to fil- ters defined between the last source and the sink(s). Example gpac -i video1 reframer:saps=1 -i video2 ffsws:osize=128x72 -o output This will connect: - video1 to reframer then reframer to output but will prevent reframer to ffsws connection. - video2 to ffsws then ffsws to output but will prevent video2 to re- framer connection. Example gpac -i video1 -i video2 reframer:saps=1 ffsws:osize=128x72 -o output This will connect video1 AND video2 to reframer->ffsws->output The implicit mode allows specifying linear processing chains (no PID fan-out except for final output(s)) without link directives, simplify- ing command lines for common cases. Warning: Argument order really matters in implicit mode! Example gpac -i file.mp4 c=avc c=aac -o output If the file has a video PID, it will connect to c=avc but not to out- put. The output PID of c=avc will connect to output. If the file has an audio PID, it will connect to c=aac but not to out- put. The output PID of c=aac will connect to output. If the file has other PIDs than audio or video, they will connect to output. Example gpac -i file.mp4 ffswf=osize:128x72 c=avc resample=osr=48k c=aac -o output This will force: - SRC(video)->ffsws->enc(video)->output and prevent SRC(video)->output, SRC(video)->enc(video) and ffsws->output connections which would happen in complete mode. - SRC(audio)->resample->enc(audio)->output and prevent SRC(audio)->out- put, SRC(audio)->enc(audio) and resample->output connections which would happen in complete mode. Quick links Link between filters may be manually specified. The syntax is an @ character optionally followed by an integer (0 if omitted). This indicates that the following filter specified at prompt should be linked only to a previous listed filter. The optional integer is a 0-based index to the previous filter declara- tions, 0 indicating the previous filter declaration, 1 the one before the previous declaration, ...). If @@ is used instead of @, the optional integer gives the filter index starting from the first filter (index 0) specified in command line. Several link directives can be given for a filter. Example fA fB @1 fC This indicates that fC only accepts inputs from fA. Example fA fB fC @1 @0 fD This indicates that fD only accepts inputs from fB and fC. Example fA fB fC ... @@1 fZ This indicates that fZ only accepts inputs from fB. Complex links The @ link directive is just a quick shortcut to set the following fil- ter arguments: * FID=name: assigns an identifier to the filter * SID=name1[,name2...]: sets a list of filter identifiers, or sour- ceIDs, restricting the list of possible inputs for a filter. Example fA fB @1 fC This is equivalent to fA:FID=1 fB fC:SID=1. Example fA:FID=1 fB fC:SID=1 This indicates that fC only accepts input from fA, but fB might accept inputs from fA. Example fA:FID=1 fB:FID=2 fC:SID=1 fD:SID=1,2 This indicates that fD only accepts input from fA and fB and fC only from fA Note: A filter with sourceID set cannot get input from filters with no IDs. A sourceID name can be further extended using fragment identifier (# by default): * name#PIDNAME: accepts only PID(s) with name PIDNAME * name#TYPE: accepts only PIDs of matching media type. TYPE can be au- dio, video, scene, text, font, meta * name#TYPEN: accepts only N (1-based index) PID of matching type from source (e.g. video2 to only accept second video PID) * name#TAG=VAL: accepts the PID if its parent filter has no tag or a tag matching VAL * name#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 builtin property of type P4CC and value VAL. * name#PName=VAL: same as above, using the builtin name corresponding to the property. * name#AnyName=VAL: same as above, using the name of a non built-in property. * name#Name=OtherPropName: compares the value with the value of another property of the PID. The matching will fail if the value to compare to is not present or different from the value to check. The property to compare with shall be a built-in property. If the property is not defined on the PID, the property is matched. Otherwise, its value is checked against the given value. The following modifiers for comparisons are allowed (for any fragment format using =): * name#P4CC=!VAL: accepts only PIDs with property NOT matching VAL. * name#P4CC-VAL: accepts only PIDs with property strictly less than VAL (only for 1-dimension number properties). * name#P4CC+VAL: accepts only PIDs with property strictly greater than VAL (only for 1-dimension number properties). A sourceID name can also use wildcard or be empty to match a property regardless of the source filter. Example fA fB:SID=*#ServiceID=2 fA fB:SID=#ServiceID=2 This indicates to match connection between fA and fB only for PIDs with a ServiceID property of 2. These extensions also work with the LINK @ shortcut. Example fA fB @1#video fC This indicates that fC only accepts inputs from fA, and of type video. Example gpac -i img.heif @#ItemID=200 vout This indicates to connect to vout only PIDs with ItemID property equal to 200. Example gpac -i vid.mp4 @#PID=1 vout This indicates to connect to vout only PIDs with ID property equal to 1. Example gpac -i vid.mp4 @#Width=640 vout This indicates to connect to vout only PIDs with Width property equal to 640. Example gpac -i vid.mp4 @#Width-640 vout This indicates to connect to vout only PIDs with Width property less than 640 Example gpac -i vid.mp4 @#ID=ItemID#ItemNumber=1 vout This will connect to vout only PID with an ID property equal to ItemID property (keep items, discard tracks) and an Item number of 1 (first item). Multiple fragment can be specified to check for multiple PID proper- ties. Example gpac -i vid.mp4 @#Width=640#Height+380 vout This indicates to connect to vout only PIDs with Width property equal to 640 and Height greater than 380. Warning: If a PID directly connects to one or more explicitly loaded filters, no further dynamic link resolution will be done to connect it to other filters with no sourceID set. Link directives should be care- fully setup. Example fA @ reframer fB If fB accepts inputs provided by fA but reframer does not, this will link fA PID to fB filter since fB has no sourceID. Since the PID is connected, the filter engine will not try to solve a link between fA and reframer. An exception is made for local files: by default, a local file destina- tion will force a remultiplex of input PIDs from a local file. Example gpac -i file.mp4 -o dump.mp4 This will prevent direct connection of PID of type file to dst file.mp4, remultiplexing the file. The special option nomux is used to allow direct connections (ignored for non-sink filters). Example gpac -i file.mp4 -o dump.mp4:nomux This will result in a direct file copy. This only applies to local files destination. For pipes, sockets or other file outputs (HTTP, ROUTE): - direct copy is enabled by default - nomux=0 can be used to force remultiplex Sub-session tagging Filters may be assigned to a sub-session using :FS=N, with N a positive integer. Filters belonging to different sub-sessions may only link to each- other: - if explicitly allowed through sourceID directives (@ or SID) - or if they have the same sub-session identifier This is mostly used for implicit mode in gpac: each first source filter specified after a sink filter will trigger a new sub-session. Example gpac -i in1.mp4 -i in2.mp4 -o out1.mp4 -o out2.mp4 This will result in both inputs multiplexed in both outputs. Example gpac -i in1.mp4 -o out1.mp4 -i in2.mp4 -o out2.mp4 This will result in in1 mixed to out1 and in2 mixed to out2, these last two filters belonging to a different sub-session. Arguments inheriting Unless explicitly disabled (see .I -max-chain), the filter engine will resolve implicit or explicit (LINK) connections between filters and will allocate any filter chain required to connect the filters. In do- ing so, it loads new filters with arguments inherited from both the source and the destination. Example gpac -i file.mp4:OPT -o file.aac -o file.264 This will pass the :OPT to all filters loaded between the source and the two destinations. Example gpac -i file.mp4 -o file.aac:OPT -o file.264 This will pass the :OPT to all filters loaded between the source and the file.aac destination. Note: the destination arguments inherited are the arguments placed AF- TER the dst= option. Example gpac -i file.mp4 fout:OPTFOO:dst=file.aac:OPTBAR This will pass the :OPTBAR to all filters loaded between file.mp4 source and file.aac destination, but not OPTFOO. Arguments inheriting can be stopped by using the keyword gfloc: argu- ments after the keyword will not be inherited. Example gpac -i file.mp4 -o file.aac:OPTFOO:gfloc:OPTBAR -o file.264 This will pass :OPTFOO to all filters loaded between file.mp4 source and file.aac destination, but not OPTBAR Arguments are by default tracked to check if they were used by the fil- ter chain, and a warning is thrown if this is not the case. It may be useful to specify arguments which may not be consumed depend- ing on the graph resolution; the specific keyword gfopt indicates that arguments after the keyword will not be tracked. Example gpac -i file.mp4 -o file.aac:OPTFOO:gfopt:OPTBAR -o file.264 This will warn if OPTFOO is not consumed, but will not track OPTBAR. A filter may be assigned a name (for inspection purposes, not inher- ited) using :N=name option. This name is not used in link resolution and may be changed at runtime by the filter instance. A filter may be assigned a tag (any string) using :TAG=name option. This tag does not need to be unique, and can be used to exclude filter in link resolution. Tags are not inherited, therefore dynamically loaded filters never have a tag. A filter may also be assigned an inherited tag (any string) using :ITAG=name option. Such tags are inherited, and are typically used to track dynamically loaded filters. URL templating Destination URLs can be dynamically constructed using templates. Pat- tern $KEYWORD$ is replaced in the template with the resolved value and $KEYWORD%%0Nd$ is replaced in the template with the resolved integer, padded with up to N zeros if needed. KEYWORD is case sensitive, and may be present multiple times in the string. Supported KEYWORD: * num: replaced by file number if defined, 0 otherwise * PID: ID of the source PID * URL: URL of source file * File: path on disk for source file; if not found, use URL if set, or PID name otherwise * Type: name of stream type of PID (video, audio ...) * 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 tem- plate resolution time * OTHER: locates property 4CC for the given name, or property name if no 4CC matches. $$ is an escape for $ Templating can be useful when encoding several qualities in one pass. Example gpac -i dump.yuv:size=640x360 vcrop:wnd=0x0x320x180 c=avc:b=1M @2 c=avc:b=750k -o dump_$CropOrigin$x$Width$x$Height$.264 This will create a cropped version of the source, encoded in AVC at 1M, and a full version of the content in AVC at 750k. Outputs will be dump_0x0x320x180.264 for the cropped version and dump_0x0x640x360.264 for the non-cropped one. Cloning filters When a filter accepts a single connection and has a connected input, it is no longer available for dynamic resolution. There may be cases where this behavior is undesired. Take a HEIF file with N items and do: Example gpac -i img.heif -o dump_$ItemID$.jpg In this case, only one item (likely the first declared in the file) will connect to the destination. Other items will not be connected since the destination only accepts one input PID. Example gpac -i img.heif -o dump_$ItemID$.jpg In this case, the destination will be cloned for each item, and all will be exported to different JPEGs thanks to URL templating. Example gpac -i vid.mpd c=avc:FID=1 -o transcode.mpd:SID=1 In this case, the encoder will be cloned for each video PIDs in the source, and the destination will only use PIDs coming from the en- coders. When implicit linking is enabled, all filters are by default clonable. This allows duplicating the processing for each PIDs of the same type. Example gpac -i dual_audio resample:osr=48k c=aac -o dst The resampler filter will be cloned for each audio PID, and the encoder will be cloned for each resampler output. You can explicitly deactivate the cloning instructions: Example gpac -i dual_audio resample:osr=48k:clone=0 c=aac -o dst The first audio will connect to the resample filter, the second to the enc filter and the resample output will connect to a clone of the enc filter. Templating filter chains There can be cases where the number of desired outputs depends on the source content, for example dumping a multiplex of N services into N files. When the destination involves multiplexing the input PIDs, the :clone option is not enough since the multiplexer will always accept the input PIDs. To handle this, it is possible to use a PID property name in the sour- ceID of a filter with the value * or an empty value. In this case, whenever a new PID with a new value for the property is found, the fil- ter with such sourceID will be dynamically cloned. Warning: This feature should only be called with a single property set to * (or empty) per source ID, results are undefined otherwise. Example gpac -i source.ts -o file_$ServiceID$.mp4:SID=*#ServiceID=* gpac -i source.ts -o file_$ServiceID$.mp4:SID=#ServiceID= In this case, each new ServiceID value found when connecting PIDs to the destination will create a new destination file. Cloning in implicit linking mode applies to output as well: Example gpac -i dual_audio -o dst_$PID$.aac Each audio track will be dumped to aac (potentially reencoding if needed). Assigning PID properties It is possible to define properties on output PIDs that will be de- clared by a filter. This allows tagging parts of the graph with differ- ent properties than other parts (for example ServiceID). The syntax is the same as filter option, and uses the fragment separator to identify properties, e.g. #Name=Value. This sets output PIDs property (4cc, built-in name or any name) to the given value. Value can be omitted for boolean (defaults to true, e.g. :#Alpha). Non built-in properties are parsed as follows: - file@FOO will be declared as string with a value set to the content of FOO. - bxml@FOO will be declared as data with a value set to the binarized content of FOO. - FOO will be declared as string with a value set to FOO. - TYPE@FOO will be parsed according to TYPE. If the type is not recog- nized, the entire value is copied as string. See gpac -h props for de- fined types. User-assigned PID properties on filter fA will be inherited by all fil- ters dynamically loaded to solve fA -> fB connection. If fB also has user-assigned PID properties, these only apply starting from fB in the chain and are not inherited by filters between fA and fB. Warning: Properties are not filtered and override the properties of the filter's output PIDs, be careful not to break the session by overriding core properties such as width/height/samplerate/... ! Example gpac -i v1.mp4:#ServiceID=4 -i v2.mp4:#ServiceID=2 -o dump.ts This will multiplex the streams in dump.ts, using ServiceID 4 for PIDs from v1.mp4 and ServiceID 2 for PIDs from v2.mp4. PID properties may be conditionally assigned by checking other PID properties. The syntax uses parenthesis (not configurable) after the property assignment sign: #Prop=(CP=CV)VAL This will assign PID property Prop to VAL for PIDs with property CP equal to CV. #Prop=(CP=CV)VAL,(CP2=CV2)VAL2 This will assign PID property Prop to VAL for PIDs with property CP equal to CV, and to VAL2 for PIDs with property CP2 equal to CV2. #Prop=(CP=CV)(CP2=CV2)VAL This will assign PID property Prop to VAL for PIDs with property CP equal to CV and property CP2 equal to CV2. #Prop=(CP=CV)VAL,()DEFAULT This will assign PID property Prop to VAL for PIDs with property CP equal to CV, or to DEFAULT for other PIDs. The condition syntax is the same as source ID fragment syntax. Note: When set, the default value (empty condition) always matches the PID, therefore it should be placed last in the list of conditions. Example gpac -i source.mp4:#MyProp=(audio)"Super Audio",(video)"Super Video" This will assign property MyProp to Super Audio for audio PIDs and to Super Video for video PIDs. Example gpac -i source.mp4:#MyProp=(audio1)"Super Audio" This will assign property MyProp to Super Audio for first audio PID de- clared. Example gpac -i source.mp4:#MyProp=(Width+1280)HD This will assign property MyProp to HD for PIDs with property Width greater than 1280. The property value can use templates with the following keywords: * $GINC(init[,inc]) or @GINC(...): replaced by integer for each new output PID of the filter (see specific filter options for details on syntax) * PROP (enclosed between `$` or `@`): replaced by serialized value of property PROP (name or 4CC) of the PID or with empty string if no such property Example gpac -i source.ts:#ASID=$PID$ This will assign DASH AdaptationSet ID to the PID ID value. Example gpac -i source.ts:#RepresentationID=$ServiceID$ This will assign DASH Representation ID to the PID ServiceID value. Using option files It is possible to use a file to define options of a filter, by specify- ing the target file name as an option without value, i.e. :myopts.txt. Warning: Only local files are allowed. An option file is a simple text file containing one or more options or PID properties on one or more lines. - A line beginning with "//" is a comment and is ignored (not config- urable). - A line beginning with ":" indicates an escaped option (the entire line is parsed as a single option). Options in an option file may point to other option files, with a maxi- mum redirection level of 5. An option file declaration (filter:myopts.txt) follows the same inheri- tance 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 my- opts.txt and foo options and will resolve options and PID properties given in myopts.txt. Ignoring filters at run-time The special option ccp can be used to replace filters with an identity filter at run-time based on the input codec ID. 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 codec, the filter is replaced with a reframer filter with single PID input and same name and ID. 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. Specific filter options Some specific keywords are replaced when processing filter options. Warning: These keywords do not apply to PID properties. Multiple key- words cannot be defined for a single option. Defined keywords: * $GSHARE: replaced by system path to GPAC shared directory (e.g. /usr/share/gpac) * $GJS: replaced by the first path from global share directory and paths set through .I -js-dirs that contains the file name following the macro, e.g. $GJS/source.js * $GDOCS: replaced by system path to: - application document directory for iOS - EXTERNAL_STORAGE environment variable if present or /sdcard other- wise for Android - user home directory for other platforms * $GLANG: replaced by the global config language option .I -lang * $GUA: replaced by the global config user agent option .I -user-agent * $GINC(init_val[,inc]): replaced by init_val and increment init_val by inc (positive or negative number, 1 if not specified) each time a new filter using this string is created. The $GINC construct can be used to dynamically assign numbers in filter chains: Example gpac -i source.ts tssplit @#ServiceID= -o dump_$GINC(10,2).ts This will dump first service in dump_10.ts, second service in dump_12.ts, etc... As seen previously, the following options may be set on any filter, but are not visible in individual filter help: * FID: filter identifier * SID: filter source(s) (string value) * N=NAME: filter name (string value) * FS: sub-session identifier (unsigned int value) * RSID: require sourceID to be present on target filters (no value) * TAG: filter tag (string value) * 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 inher- ited (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 fil- ter, 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@re- framer]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. It may also load external filters in dynamic libraries, located in default module folder or folders listed in .I -mod-dirs option. The files shall be named gf_* and shall export a single function RegisterFilter returning a filter register - see libgpac documentation for more details. 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 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 en- hancement 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 ServiceProvider (SPRO,str,D ) Provider of parent service 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 Duration (PDUR,lfrac, ) Media duration (a negative value means 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 over- flow - changes are signaled through PID info (no reconfigure) Timescale (TIMS,uint, ) Media timescale (a timestamp delta of N is N/timescale seconds) ProfileLevel (PRPL,uint,D ) MPEG-4 profile and level DecoderConfig (DCFG,mem, ) Decoder configuration data DecoderConfigEnhancement (ECFG,mem, ) Decoder configuration data of the enhancement layer(s). Also used by 3GPP/Apple text streams to give the full sample descrip- tion table used in SDP. DSISuperset (DCFS,bool, ) Decoder config is a superset of previous decoder config DecoderConfigIndex (ICFG,uint, ) 1-based index of decoder config for ISO base media files SampleRate (AUSR,uint, ) Audio sample rate SamplesPerFrame (FRMS,uint, ) Number of audio sample in one coded frame NumChannels (CHNB,uint, ) Number of audio channels BPS (ABPS,uint, ) Number of bits per sample in 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 me- dia timescale. Positive value imply holding (delaying) the stream. 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 Width (WIDT,uint, ) Visual Width (video / text / graphics) Height (HEIG,uint, ) Visual Height (video / text / graphics) PixelFormat (PFMT,pfmt, ) Pixel format PixelFormatWrapped (PFMW,pfmt, ) Underlying pixel format of video stream if pixel format is ex- ternal GL texture 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, ) Video is interlaced SAR (PSAR,frac, ) Sample (i.e. pixel) aspect ratio MaxWidth (MWID,uint, ) Maximum width (video / text / graphics) of all enhancement lay- ers MaxHeight (MHEI,uint, ) Maximum height (video / text / graphics) of all enhancement lay- ers ZOrder (VZIX,sint, ) Z-order of the video, from 0 (first) to max int (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 reference width is unknown TransYTop (VTRy,sint, ) Vertical translation of the video (0 is top, positive towards down), for cases where reference height is unknown Hidden (HIDE,bool, ) PID is hidden in visual/audio rendering CropOrigin (VCXY,v2di, ) Position in source window, X,Y indicate coordinates in source (0,0 for top-left) OriginalSize (VOWH,v2di, ) Original resolution of video SRD (SRD ,v4di, ) Position and size of the video in the referential given by SR- DRef SRDRef (SRDR,v2di, ) Width and Height of the SRD referential SRDMap (SRDM,uintl, ) Mapping of input videos in 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 re- constructed output, expressed in the output referential given by SRDRef Alpha (VALP,bool, ) Video in this PID is an alpha map Mirror (VMIR,uint, ) Mirror mode (as 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 contin- uous 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 file system MIMEType (MIME,str,D ) MIME type of source Extension (FEXT,str,D ) File extension of source Cached (CACH,bool,D ) File is completely cached DownloadRate (DLBW,uint,D ) Download rate of resource in bits per second - changes are sig- naled 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 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 ) 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 de- crypter 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 en- cryption 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)Sys- temID(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)Nb- SubSamples [(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: * 0: single sample description is used * 1: a clear clone of the sample description is created, in- serted before the CENC sample description * 2: a clear clone of the sample description is created, in- serted after the CENC sample description AMRModeSet (AMST,uint, ) ModeSet for AMR and AMR-WideBand SubSampleInfo (SUBS,mem, ) Binary blob describing N subsamples of the sample, formatted as N [(u32)flags(u32)size(u32)codec_param(u8)priority(u8) discard- able]. 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) Name of output file when dumping / dashing. Must be set on first packet belonging to new file IDXName (INAM,str, P) Name of index file when dashing MPEG-2 TS. Must be set on first packet belonging to new file FileSuffix (FSUF,str, P) File suffix name, replacement for $FS$ in tile templates EODS (EODS,bool, P) End of DASH segment CueStart (PCUS,bool, P) Set on packets marking the beginning of a DASH/HLS segment for cue-driven segmentation - see dasher help MediaTime (MTIM,dbl,D ) Corresponding media time of the parent packet (0 being the ori- gin) MaxFrameSize (MFRS,uint,D ) Max size of frame in stream - changes are signaled through PID info change (no reconfigure) AvgFrameSize (AFRS,uint,D ) Average size of frame in stream (ISOBMFF only, static property) 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, 0 means variable duration (ISOBMFF only, static property) TrackTemplate (ITKT,mem,D ) ISOBMFF serialized track box for this PID, without any sample info (empty stbl and empty dref) TrexTemplate (ITXT,mem,D ) ISOBMFF serialized trex box for this PID STSDTemplate (ISTD,mem,D ) ISOBMFF serialized sample description box (stsd entry) for this PID MovieUserData (IMUD,mem,D ) ISOBMFF serialized moov UDTA and other moov-level boxes (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 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 DASH representation ASID (DAID,uint,D ) ID of parent DASH AS MuxSrc (MSRC,str,D ) Name of mux source(s), set by dasher to direct its outputs DashMode (DMOD,uint,D ) DASH mode to be used by multiplexer if any, set by dasher. 0 is no DASH, 1 is regular DASH, 2 is VoD SegSync (DFSS,bool,D ) Indicate segment must be completely flushed before sending seg- ment/fragment size events DashDur (DDUR,frac,D ) DASH target segment duration in seconds 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 (this 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 con- taining this PID. If a PID with the same property type but dif- ferent value is found, the PIDs will be in different Adaptation- Sets 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 PID in DASH mode HLSPL (HLVP,str,D ) Name of the HLS variant playlist for this media HLSGroup (HLGI,str,D ) Name of HLS Group of a stream HLSForce (HLFI,str,D ) Force writing EXT-X-STREAM-INF if stream is in a rendition group, value is the name of associated groups (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 ) codec parameter string to force. If starting with '.', appended to ISOBMFF code point; otherwise replace the codec string SingleScale (DSTS,bool,D ) Movie header should use the media timescale of the first track added RequireReorder (PUDP,bool,D ) PID packets come from source with losses and reordering happen- ing (UDP) Primary (PITM,bool,D ) Primary item in ISOBMFF DFMode (DFWD,uint,D ) DASH forward mode is used for this PID. If 2, the manifest is also carried in packet propery DFManifest (DMPD,str,D ) Value of manifest in forward mode DFVariant (DHLV,strl,D ) Value of variant playlist in forward mode DFVariantName (DHLN,strl,D ) Value of variant playlist name in forward mode DFPStart (DPST,luint,D ) Value of active period start time in forward mode HLSKey (HLSK,str, ) URI, KEYFORMAT and KEYFORMATVERSIONS for HLS full segment en- cryption creation, Key URI otherwise ( decoding and sample-AES) HLSIV (HLSI,mem, ) Init Vector for HLS decode CKUrl (CCKU,str, ) URL for ClearKey licence server ColorPrimaries (CPRM,cprm,D ) Color primaries ColorTransfer (CTRC,ctfc,D ) 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, payload of 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, payload of mdcv box (see ISO/IEC 14496-12), can be set as a list of 10 integers in fragment dec- laration (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 destination file, stored by lowest value first (not set by demultiplexers) NoTSLoop (NTSL,bool, ) Timestamps on this PID are 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) Packet is a fragment start (value 1) or a segment start (value 2) FragRange (PFRR,lfrac,DP) Start and end position in bytes of fragment if packet is a frag- ment or segment start FragTFDT (PFRT,luint,DP) Decode time of first packet in fragmentt SIDXRange (PFSR,lfrac,DP) Start and end position in bytes of sidx if packet is a fragment or segment start MoofTemplate (MFTP,mem,DP) Serialized moof box corresponding to the start of a movie frag- ment or segment (with styp and optionally sidx) InitSeg (PCKI,bool, P) Set to true if packet is a complete DASH init segment file RawGrab (PGRB,uint,D ) PID is a raw media grabber (webcam, microphone, etc...). Value 2 is used for front camera KeepAfterEOS (PKAE,bool,D ) PID must be kept alive after EOS (LASeR and BIFS) CoverArt (PCOV,mem,D ) PID cover art image data. If 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 disable rebuffering ViewIdx (VIDX,uint,D ) View index for multiview (1 being left) FragURL (OFRA,str,D ) Fragment URL (without '#') of original URL (used by some filters to set the property on media PIDs) ROUTEIP (RSIP,str,D ) ROUTE session IP address ROUTEPort (RSPN,uint,D ) ROUTE session port number ROUTEName (RSFN,str,D ) Name (location) of raw file to advertise in ROUTE session ROUTECarousel (RSCR,frac,D ) Carousel period in seconds of raw file in ROUTE session ROUTEUpload (RSST,frac,D ) Upload time in seconds of raw file in ROUTE session Stereo (PSTT,uint,D ) Stereo type of video Projection (PPJT,uint,D ) Projection type of video InitalPose (PPOS,v3di,D ) Initial pose for 360 video, in degrees expressed as 16.16 bits (x is yaw, y is pitch, z is roll) CMPad (PCMP,uint,D ) Number of pixels to pad from edge of each face in cube map EQRClamp (PEQC,v4di,D ) Clamping of 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 (MSB=1 if live) * 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 input text PID ForcedSub (PFCS,uint,D ) PID or Packet is forced sub 0: not forced 1: forced frame 2: all frames are forced (PID only) ChapTimes (CHPT,uintl,D ) Chapter start times ChapNames (CHPN,strl,D ) Chapter names IsChap (PCHP,bool,D ) Subtitle PID is chapter (for QT-like chapters) SkipBegin (PCKS,uint, P) Amount of media to skip from beginning of packet in PID timescale SkipPres (PCKD,bool, P) Packet and any following with CTS greater than this packet shall not be presented (used by reframer to create edit lists) HLSRef (HPLR,luint,DP) HLS playlist reference, gives a unique ID identifying media mux, and indicated in packets carrying child playlists LLHLS (HLSL,uint,D ) HLS low latency mode LLHLSFragNum (HLSN,uint, P) LLHLS fragment number DownloadSession (GHTT,ptr,D ) Pointer to download session HasTemi (PTEM,bool,D ) TEMI present flag XPSMask (PXPM,uint,DP) Parameter set mask RangeEnd (PCER,bool, P) Signal packet is the last in the desired play range Pixel formats 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 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 sam- plerExternalOES uncv (ext *.uncv) Generic uncompressed format ISO/IEC 23001-17 Audio formats 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 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 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 mlp Dolby TrueHD dra DRA Audio g719 G719 Audio dstc DTS Coherent Acoustics and Digital Surround Audio dtsh DTS-HD High Resolution Audio and DTS-Master Audio dstl 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 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 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 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 Stream types 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 0x0000000000000307 3/2.1 (int 6) Layout 0x000000000000030f 5/2.1 (int 7) Layout 0x000000000000030f 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 0x000000000006030f 5/5.2 (int 15) Layout 0x000000000606630f 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 Basic and advanced examples are available at https://wiki.gpac.io/Fil- ters 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: 2.4 Copyright: (c) 2000-2023 Telecom Paris distributed under LGPL v2.1+ - https://gpac.io SEE ALSO gpac-filters(1),MP4Box(1) gpac 2019 gpac(1)
NAME | SYNOPSIS | Using Aliases | User Credentials | 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] | Filter linking [LINK] | 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 | Pixel formats | Audio formats | Stream types | Codecs | Stream types | EXAMPLES | MORE | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gpac&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>