gaspard7/wiki_gpac huggingface dataset:
Escaping option separators

When a filter uses an option defined as a string using the same separator character as gpac, you can either modify the set of separators, or escape the separator by duplicating it. The options enclosed by duplicated separator are not parsed. This is mostly used for meta filters, such as ffmpeg, to pass options to sub-filters such as libx264 (cf `x264opts` parameter).  
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 excluded by connecting PIDs.  
To check the possible sources and destination for a filter `FNAME`, use `gpac -h links FNAME`  
  
The filter graph resolver uses this information together with the PID properties to link the different filters.  
  
Link directives, when provided, specify which source a filter can accept connections from.  
_They do not specify which destination a filter can connect to._
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 declarations, 0 indicating the previous filter declaration, 1 the one before the previous declaration, ...).  
If `@@` is used instead of `@`, the optional integer gives the filter index starting from the first filter (index 0) specified in command line.  
Several link directives can be given for a filter.  
Example
```
fA fB @1 fC
```
  
This indicates that `fC` only accepts inputs from `fA`.  
Example
```
fA fB fC @1 @0 fD
```
  
This indicates that `fD` only accepts inputs from `fB` and `fC`.  
Example
```
fA fB fC ... @@1 fZ
```
  
This indicates that `fZ` only accepts inputs from `fB`.
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 [-max-chain](core_options/#max-chain)), the filter engine will resolve implicit or explicit (_LINK_) connections between filters and will allocate any filter chain required to connect the filters. In doing so, it loads new filters with arguments inherited from both the source and the destination.  
Example
```
gpac -i file.mp4:OPT -o file.aac -o file.264
```
  
This will pass the `:OPT` to all filters loaded between the source and the two destinations.  
Example
```
gpac -i file.mp4 -o file.aac:OPT -o file.264
```
  
This will pass the `:OPT` to all filters loaded between the source and the file.aac destination.  
_Note: the destination arguments inherited are the arguments placed __AFTER__ the `dst=` option._  
Example
```
gpac -i file.mp4 fout:OPTFOO:dst=file.aac:OPTBAR
```
  
This will pass the `:OPTBAR` to all filters loaded between `file.mp4` source and `file.aac` destination, but not `OPTFOO`.  
Arguments inheriting can be stopped by using the keyword `gfloc`: arguments after the keyword will not be inherited.  
Example
```
gpac -i file.mp4 -o file.aac:OPTFOO:gfloc:OPTBAR -o file.264
```
  
This will pass `:OPTFOO` to all filters loaded between `file.mp4` source and `file.aac` destination, but not `OPTBAR`  
Arguments are by default tracked to check if they were used by the filter chain, and a warning is thrown if this is not the case.  
It may be useful to specify arguments which may not be consumed depending on the graph resolution; the specific keyword `gfopt` indicates that arguments after the keyword will not be tracked.  
Example
```
gpac -i file.mp4 -o file.aac:OPTFOO:gfopt:OPTBAR -o file.264
```
  
This will warn if `OPTFOO` is not consumed, but will not track `OPTBAR`.  
    
A filter may be assigned a name (for inspection purposes, not inherited) using `:N=name` option. This name is not used in link resolution and may be changed at runtime by the filter instance.  
    
A filter may be assigned a tag (any string) using `:TAG=name` option. This tag does not need to be unique, and can be used to exclude filter in link resolution. Tags are not inherited, therefore dynamically loaded filters never have a tag.  
    
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. Pattern `$KEYWORD$` is replaced in the template with the resolved value and `$KEYWORD%%0Nd$` is replaced in the template with the resolved integer, padded with up to N zeros if needed.  
`KEYWORD` is __case sensitive__, and may be present multiple times in the string. Supported `KEYWORD`:  

- num: replaced by file number if defined, 0 otherwise  
- PID: ID of the source PID  
- URL: URL of source file  
- File: path on disk for source file; if not found, use URL if set, or PID name otherwise  
- Type: name of stream type of PID (`video`, `audio` ...)  
- OType: same as `Type` but uses original type when stream is encrypted (e.g. move from `crypt` to `video`)  
- p4cc=ABCD: uses PID property with 4CC value `ABCD`  
- pname=VAL: uses PID property with name `VAL`  
- cts, dts, dur, sap: uses properties of first packet in PID at template resolution time  
- OTHER: locates property 4CC for the given name, or property name if no 4CC matches.  

    
`$$` is 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 encoders.  
  
When implicit linking is enabled, all filters are by default clonable. This allows duplicating the processing for each PIDs of the same type.  
Example
```
gpac -i dual_audio resample:osr=48k c=aac -o dst
```
  
The `resampler` filter will be cloned for each audio PID, and the encoder will be cloned for each resampler output.  
You can explicitly deactivate the cloning instructions:  
Example
```
gpac -i dual_audio resample:osr=48k:clone=0 c=aac -o dst
```
  
The first audio will connect to the `resample` filter, the second to the `enc` filter and the `resample` output will connect to a clone of the `enc` filter.
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 sourceID of a filter with the value `*` or an empty value. In this case, whenever a new PID with a new value for the property is found, the filter with such sourceID will be dynamically cloned.  

__Warning: This feature should only be called with a single property set to `*` (or empty) per source ID, results are undefined otherwise.__  
  
Example
```
gpac -i source.ts -o file_$ServiceID$.mp4:SID=*#ServiceID=*  
gpac -i source.ts -o file_$ServiceID$.mp4:SID=#ServiceID=
```
  
In this case, each new `ServiceID` value found when connecting PIDs to the destination will create a new destination file.  
  
Cloning in implicit linking mode applies to output as well:  
Example
```
gpac -i dual_audio -o dst_$PID$.aac
```
  
Each audio track will be dumped to aac (potentially reencoding if needed).
Using option files

It is possible to use a file to define options of a filter, by specifying the target file name as an option without value, i.e. `:myopts.txt`.  

__Warning: Only local files are allowed.__  
  
An option file is a simple text file containing one or more options or PID properties on one or more lines.  

- A line beginning with "//" is a comment and is ignored (not configurable).  
- A line beginning with ":" indicates an escaped option (the entire line is parsed as a single option).  

Options in an option file may point to other option files, with a maximum redirection level of 5.  
An option file declaration (`filter:myopts.txt`) follows the same inheritance rules as regular options.  
Example
```
gpac -i source.mp4:myopts.txt:foo=bar -o dst
```
  
Any filter loaded between `source.mp4` and `dst` will inherit both `myopts.txt` and `foo` options and will resolve options and PID properties given in `myopts.txt`.
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.
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 [-mod-dirs](core_options/#mod-dirs) option. The files shall be named `gf_*` and shall export a single function `RegisterFilter` returning a filter register - see [libgpac documentation](https://doxygen.gpac.io/) for more details.
HEVC Tile merger

Register name used to load filter: __hevcmerge__  
This filter may be automatically loaded during graph resolution.  
  
This filter merges a set of HEVC PIDs into a single motion-constrained tiled HEVC PID.  
The filter creates a tiling grid with a single row and as many columns as needed.  
If [mrows](#mrows) is set and tiles properly align on the final grid, multiple rows will be declared in the PPS.  
Positioning of tiles can be automatic (implicit) or explicit.  
The filter will check the SPS and PPS configurations of input PID and warn if they are not aligned but will still process them unless [strict](#strict) is set.  
The filter assumes that all input PIDs are synchronized (frames share the same timestamp) and will reassemble frames with the same decode time. If PIDs are of unequal duration, the filter will drop frames as soon as one PID is over.
Explicit Positioning

In explicit positioning, the `CropOrigin` property on input PIDs is used to setup the tile grid. In this case, tiles shall not overlap in the final output.  
If `CropOrigin` is used, it shall be set on all input sources.  
If positive coordinates are used, they specify absolute positioning in pixels of the tiles. The coordinates are automatically adjusted to the next multiple of max CU width and height.  
If negative coordinates are used, they specify relative positioning (e.g. `0x-1` indicates to place the tile below the tile 0x0).  
In this mode, it is the caller responsibility to set coordinates so that all tiles in a column have the same width and only the last row/column uses non-multiple of max CU width/height values. The filter will complain and abort if this is not respected.  

- If an horizontal blank is detected in the layout, an empty column in the tiling grid will be inserted.  
- If a vertical blank is detected in the layout, it is ignored.
Spatial Relationship Description (SRD)

The filter will create an `SRDMap` property in the output PID if `SRDRef` and `SRD` or `CropOrigin` are set on all input PIDs.  
The `SRDMap` allows forwarding the logical sources `SRD` in the merged PID.  
The output PID `SRDRef` is set to the output video size.  
The input `SRDRef` and `SRD` are usually specified in DASH MPD, but can be manually assigned to inputs.  

- `SRDRef` gives the size of the referential used for the input `SRD` (usually matches the original video size, but not always)  
- `SRD` gives the size and position of the input in the original video, expressed in `SRDRef` referential of the input.  

The inputs do not need to have matching `SRDRef`  
.EX src1:SRD=0x0x640x480:SRDRef=1280x720  
This indicates that `src1` contains a video located at 0,0, with a size of 640x480 pixels in a virtual source of 1280x720 pixels.  
Example
```
src2:SRD=640x0x640x480:SRDRef=1280x720
```
  
This indicates that `src1` contains a video located at 640,0, with a size of 640x480 pixels in a virtual source of 1280x720 pixels.  
   
Each merged input is described by 8 integers in the output `SRDMap`:  

- the source `SRD` is rescaled in the output `SRDRef` to form the first part (4 integers) of the `SRDMap` (i.e. _where was the input ?_)  
- the source location in the reconstructed video forms the second part (4 integers) of the `SRDMap` (i.e. _where are the input pixels in the output ?_)  

   
Assuming the two sources are encoded at 320x240 and merged as src2 above src1, the output will be a 320x480 video with a `SRDMap` of {0,160,160,240,0,0,320,240,0,0,160,240,0,240,320,240}  
_Note: merged inputs are always listed in `SRDMap` in their tile order in the output bitstream._  
  
Alternatively to using `SRD` and `SRDRef`, it is possible to specify `CropOrigin` property on the inputs, in which case:  

- the `CropOrigin` gives the location in the source  
- the input size gives the size in the source, and no rescaling of referential is done  

Example
```
src1:CropOrigin=0x0  src1:CropOrigin=640x0 
```
  
Assuming the two sources are encoded at 320x240 and merged as src1 above src2, the output will be a 320x480 video with a `SRDMap` of `{0,0,320,240,0,0,320,240,640,0,320,240,0,240,320,240}`
Options  {.no-collapse}

<div markdown class="option">  
<a id="strict">__strict__</a> (bool, default: _false_): strict comparison of SPS and PPS of input PIDs  
</div>  
<div markdown class="option">  
<a id="mrows">__mrows__</a> (bool, default: _false_): signal multiple rows in tile grid when possible  
</div>
Media Reframer

Register name used to load filter: __reframer__  
This filter is not checked during graph resolution and needs explicit loading.  
Filters of this class can connect to each-other.  
  
This filter provides various tools on inputs:  

- ensure reframing (1 packet = 1 Access Unit)  
- optionally force decoding  
- real-time regulation  
- packet filtering based on SAP types or frame numbers  
- time-range extraction and splitting  

    
This filter forces input PIDs to be properly framed (1 packet = 1 Access Unit).  
It is typically needed to force remultiplexing in file to file operations when source and destination files use the same format.
UTC-based range extraction

The filter can perform range extraction based on UTC time rather than media time. In this mode, the end time must be:  

- a UTC date: range extraction will stop after this date  
- a time in second: range extraction will stop after the specified duration  

  
The UTC reference is specified using [utc_ref](#utc_ref).  
If UTC signal from media source is used, the filter will probe for [utc_probe](#utc_probe) before considering the source has no UTC signal.  
  
The properties `SenderNTP` and, if absent, `UTC` of source packets are checked for establishing the UTC reference.
Other split actions

The filter can perform splitting of the source using [xs](#xs) option.  
The additional formats allowed for [xs](#xs) option are:  

- `SAP`: split source at each SAP/RAP  
- `D`VAL: split source by chunks of `VAL` seconds  
- `D`NUM/DEN: split source by chunks of `NUM/DEN` seconds  
- `S`VAL: split source by chunks of estimated size `VAL` bytes (can use property multipliers, e.g. `m`)  

  
_Note: In these modes, [splitrange](#splitrange) and [xadjust](#xadjust) are implicitly set._
JPG/J2K/PNG/BMP reframer

Register name used to load filter: __rfimg__  
This filter may be automatically loaded during graph resolution.  
  
This filter parses JPG/J2K/PNG/BMP files/data and outputs corresponding visual PID and frames.  
  
The following extensions for PNG change the pixel format for RGBA images:  

- pngd: use RGB+depth map pixel format  
- pngds: use RGB+depth(7bits)+shape(MSB of alpha channel) pixel format  

  
No options
Options  {.no-collapse}

<div markdown class="option">  
<a id="deblock_y">__deblock_y__</a> (bool, default: _false_): enable Y deblocking  
</div>  
<div markdown class="option">  
<a id="deblock_uv">__deblock_uv__</a> (bool, default: _false_): enable UV deblocking  
</div>  
<div markdown class="option">  
<a id="film_effect">__film_effect__</a> (bool, default: _false_): enable film effect  
</div>  
<div markdown class="option">  
<a id="dering_y">__dering_y__</a> (bool, default: _false_): enable Y deblocking  
</div>  
<div markdown class="option">  
<a id="dering_uv">__dering_uv__</a> (bool, default: _false_): enable UV deblocking  
</div>
AVC/HEVC reframer

Register name used to load filter: __rfnalu__  
This filter may be automatically loaded during graph resolution.  
  
This filter parses AVC|H264 and HEVC files/data and outputs corresponding video PID and frames.  
This filter produces ISOBMFF-compatible output: start codes are removed, NALU length field added and avcC/hvcC config created.  
_Note: The filter uses negative CTS offsets: CTS is correct, but some frames may have DTS greater than CTS._
Filter mode

In this mode, the compositor acts as a regular filter generating frames based on the loaded scene.  
It will generate its outputs based on the input video frames, and will process user event sent by consuming filter(s).  
If no input video frames (e.g. pure BIFS / SVG / VRML), the filter will generate frames based on the [fps](#fps), at constant or variable frame rate.  
It will stop generating frames as soon as all input streams are done, unless extended/reduced by [dur](#dur).  
If audio streams are loaded, an audio output PID is created.  
  
The default output pixel format in filter mode is:  

- `rgb` when the filter is explicitly loaded by the application  
- `rgba` when the filter is loaded during a link resolution  

This can be changed by assigning the [opfmt](#opfmt) option.  
If either [opfmt](#opfmt) specifies alpha channel or [bc](#bc) is not 0 but has alpha=0, background creation in default scene will be skipped.  
  
In filter-only mode, the special URL `gpid://` is used to locate PIDs in the scene description, in order to design scenes independently from source media.  
When such a PID is associated to a `Background2D` node in BIFS (no SVG mapping yet), the compositor operates in pass-through mode.  
In this mode, only new input frames on the pass-through PID will generate new frames, and the scene clock matches the input packet time.  
The output size and pixel format will be set to the input size and pixel format, unless specified otherwise in the filter options.  
  
If only 2D graphics are used and display driver is not forced, 2D rasterizer will happen in the output pixel format (including YUV pixel formats).  
In this case, in-place processing (rasterizing over the input frame data) will be used whenever allowed by input data.  
  
If 3D graphics are used or display driver is forced, OpenGL will be used on offscreen surface and the output packet will be an OpenGL texture.
Specific URL syntaxes

The compositor accepts any URL type supported by GPAC. It also accepts the following schemes for URLs:  

- views:// : creates an auto-stereo scene of N views from `views://v1::.::vN`  
- mosaic:// : creates a mosaic of N views from `mosaic://v1::.::vN`  

  
For both syntaxes, `vN` can be any type of URL supported by GPAC.  
For `views://` syntax, the number of rendered views is set by [nbviews](#nbviews):  

- If the URL gives less views than rendered, the views will be repeated  
- If the URL gives more views than rendered, the extra views will be ignored  

  
The compositor can act as a source filter when the [src](#src) option is explicitly set, independently from the operating mode:  
Example
```
gpac compositor:src=source.mp4 vout
```
  
  
The compositor can act as a source filter when the source url uses one of the compositor built-in protocol schemes:  
Example
```
gpac -i mosaic://URL1:URL2 vout
```
FFmpeg AVFilter

Register name used to load filter: __ffavf__  
This filter is not checked during graph resolution and needs explicit loading.  
Filters of this class can connect to each-other.  
  
This filter provides libavfilter raw audio and video tools.  
See FFmpeg documentation (https://ffmpeg.org/documentation.html) for more details  
To list all supported avfilters for your GPAC build, use `gpac -h ffavf:*`.
Declaring a filter

The filter loads a filter or a filter chain description from the [f](#f) option.  
Example
```
ffavf:f=showspectrum
```
  
  
Unlike other FFmpeg bindings in GPAC, this filter does not parse other libavfilter options, you must specify them directly in the filter chain, and the [f](#f) option will have to be escaped.  
Example
```
ffavf::f=showspectrum=size=320x320 or ffavf::f=showspectrum=size=320x320::pfmt=rgb  
ffavf::f=anullsrc=channel_layout=5.1:sample_rate=48000
```
  
  
For complex filter graphs, it is possible to store options in a file (e.g. `opts.txt`):  
Example
```
:f=anullsrc=channel_layout=5.1:sample_rate=48000
```
  
And load arguments from file:  
Example
```
ffavf:opts.txt aout
```
  
  
The filter will automatically create `buffer` and `buffersink` AV filters for data exchange between GPAC and libavfilter.  
The builtin options ( [pfmt](#pfmt), [afmt](#afmt) ...) can be used to configure the `buffersink` filter to set the output format of the filter.