gaspard7/wiki_gpac huggingface dataset:
Multiplexer development considerations

Output multiplexers allowing segmented output must obey the following:  

- inspect packet properties  

    - FileNumber: if set, indicate the start of a new DASH segment  
    - FileName: if set, indicate the file name. If not present, output shall be a single file. This is only set for packet carrying the `FileNumber` property, and only on one PID (usually the first) for multiplexed outputs  
    - IDXName: gives the optional index name. If not present, index shall be in the same file as dash segment. Only used for MPEG-2 TS for now  
    - EODS: property is set on packets with no payload and no timestamp to signal the end of a DASH segment. This is only used when stopping/resuming the segmentation process, in order to flush segments without dispatching an EOS (see [subdur](#subdur) )  

- for each segment done, send a downstream event on the first connected PID signaling the size of the segment and the size of its index if any  
- for multiplexers with init data, send a downstream event signaling the size of the init and the size of the global index if any  
- the following filter options are passed to multiplexers, which should declare them as arguments:  

    - noinit: disables output of init segment for the multiplexer (used to handle bitstream switching with single init in DASH)  
    - frag: indicates multiplexer shall use fragmented format (used for ISOBMFF mostly)  
    - subs_sidx=0: indicates an SIDX shall be generated - only added if not already specified by user  
    - xps_inband=all|no|both: indicates AVC/HEVC/... parameter sets shall be sent inband, out of band, or both  
    - nofragdef: indicates fragment defaults should be set in each segment rather than in init segment  

  
The segmenter adds the following properties to the output PIDs:  

- DashMode: identifies VoD (single file with global index) or regular DASH mode used by segmenter  
- DashDur: identifies target DASH segment duration - this can be used to estimate the SIDX size for example  
- LLHLS: identifies LLHLS is used; the multiplexer must send fragment size events back to the dasher, and set `LLHLSFragNum` on the first packet of each fragment  
- SegSync: indicates that fragments/segments must be completely flushed before sending back size events
Inspect packets

Register name used to load filter: __inspect__  
This filter is not checked during graph resolution and needs explicit loading.  
  
The inspect filter can be used to dump PID and packets. It may also be used to check parts of payload of the packets.  
  
The default options inspect only PID changes.  
If [full](#full) is not set, [mode=frame](#mode=frame) is forced and PID properties are formatted in human-readable form, one PID per line.  
Otherwise, all properties are dumped.  
_Note: specifying [xml](#xml), [analyze](#analyze), [fmt](#fmt) or using `-for-test` will force [full](#full) to true._
Custom property dumping

The packet inspector can be configured to dump specific properties of packets using [fmt](#fmt).  
When the option is not present, all properties are dumped. Otherwise, only properties identified by `$TOKEN$` are printed. You may use '$', '@' or '%' for `TOKEN` separator. `TOKEN` can be:  

- pn: packet (frame in framed mode) number  
- dts: decoding time stamp in stream timescale, N/A if not available  
- ddts: difference between current and previous packets decoding time stamp in stream timescale, N/A if not available  
- cts: composition time stamp in stream timescale, N/A if not available  
- dcts: difference between current and previous packets composition time stamp in stream timescale, N/A if not available  
- ctso: difference between composition time stamp and decoding time stamp in stream timescale, N/A if not available  
- dur: duration in stream timescale  
- frame: framing status  

    - interface: complete AU, interface object (no size info). Typically a GL texture  
    - frame_full: complete AU  
    - frame_start: beginning of frame  
    - frame_end: end of frame  
    - frame_cont: frame continuation (not beginning, not end)  

- sap or rap: SAP type of the frame  
- ilace: interlacing flag (0: progressive, 1: top field, 2: bottom field)  
- corr: corrupted packet flag  
- seek: seek flag  
- bo: byte offset in source, N/A if not available  
- roll: roll info  
- crypt: crypt flag  
- vers: carousel version number  
- size: size of packet  
- csize: total size of packets received so far  
- crc: 32 bit CRC of packet  
- lf or n: insert new line  
- t: insert tab  
- data: hex dump of packet (_big output!_) or as string if legal UTF-8  
- lp: leading picture flag  
- depo: depends on other packet flag  
- depf: is depended on other packet flag  
- red: redundant coding flag  
- start: packet composition time as HH:MM:SS.ms  
- startc: packet composition time as HH:MM:SS,ms  
- end: packet end time as HH:MM:SS.ms  
- endc: packet end time as HH:MM:SS,ms  
- ck: clock type used for PCR discontinuities  
- pcr: MPEG-2 TS last PCR, n/a if not available  
- pcrd: difference between last PCR and decoding time, n/a if no PCR available  
- pcrc: difference between last PCR and composition time, n/a if no PCR available  
- P4CC: 4CC of packet property  
- PropName: Name of packet property  
- pid.P4CC: 4CC of PID property  
- pid.PropName: Name of PID property  
- fn: Filter name  

  
Example
```
fmt="PID $pid.ID$ packet $pn$ DTS $dts$ CTS $cts$ $lf$"
```
  
This dumps packet number, cts and dts as follows: `PID 1 packet 10 DTS 100 CTS 108 \n`  
    
An unrecognized keyword or missing property will resolve to an empty string.  
  
_Note: when dumping in interleaved mode, there is no guarantee that the packets will be dumped in their original sequence order since the inspector fetches one packet at a time on each PID._
Note on playback

Buffering can be enabled to check the input filter chain behaviour, e.g. check HAS adaptation logic.  
The various buffering options control when packets are consumed. Buffering events are logged using `media@info` for state changes and `media@debug` for media filling events.  
The [speed](#speed) option is only used to configure the filter chain but is ignored by the filter when consuming packets.  
If real-time consumption is required, a reframer filter must be setup before the inspect filter.  
Example
```
gpac -i SRC reframer:rt=on inspect:buffer=10000:rbuffer=1000:mbuffer=30000:speed=2
```
  
This will play the session at 2x speed, using 30s of maximum buffering, consuming packets after 10s of media are ready and rebuffering if less than 1s of media.
Compressed bitstream rewriter

Register name used to load filter: __bsrw__  
This filter is not checked during graph resolution and needs explicit loading.  
Filters of this class can connect to each-other.  
  
This filter rewrites some metadata of various bitstream formats.  
The filter can currently modify the following properties in video bitstreams:  

- MPEG-4 Visual:  

    - sample aspect ratio  
    - profile and level  

- AVC|H264, HEVC and VVC:  

    - sample aspect ratio  
    - profile, level, profile compatibility  
    - video format, video fullrange  
    - color primaries, transfer characteristics and matrix coefficients (or remove all info)  

- ProRes:  

    - sample aspect ratio  
    - color primaries, transfer characteristics and matrix coefficients  

    
Values are by default initialized to -1, implying to keep the related info (present or not) in the bitstream.  
A [sar](#sar) value of `0/0` will remove sample aspect ratio info from bitstream if possible.  
    
The filter can currently modify the following properties in the stream configuration but not in the bitstream:  

- HEVC: profile IDC, profile space, general compatibility flags  
- VVC: profile IDC, general profile and level indication  

    
The filter will work in passthrough mode for all other codecs and media types.
Options  {.no-collapse}

<div markdown class="option">  
<a id="cprim" data-level="basic">__cprim__</a> (cprm, default: _-1_, Enum: reserved0|BT709|undef|reserved3|BT470M|BT470G|SMPTE170|SMPTE240|FILM|BT2020|SMPTE428|SMPTE431|SMPTE432|EBU3213, updatable): color primaries according to ISO/IEC 23001-8 / 23091-2  
</div>  
  
<div markdown class="option">  
<a id="ctfc" data-level="basic">__ctfc__</a> (ctfc, default: _-1_, Enum: reserved0|BT709|undef|reserved3|BT470M|BT470BG|SMPTE170|SMPTE249|Linear|Log100|Log316|IEC61966|BT1361|sRGB|BT2020_10|BT2020_12|SMPTE2084|SMPTE428|STDB67, updatable): color transfer characteristics according to ISO/IEC 23001-8 / 23091-2  
</div>  
  
<div markdown class="option">  
<a id="cmx" data-level="basic">__cmx__</a> (cmxc, default: _-1_, Enum: GBR|BT709|undef|FCC|BT601|SMPTE170|SMPTE240|YCgCo|BT2020|BT2020cl|YDzDx, updatable): color matrix coeficients according to ISO/IEC 23001-8 / 23091-2  
</div>  
  
<div markdown class="option">  
<a id="sar" data-level="basic">__sar__</a> (frac, default: _-1/-1_, updatable): aspect ratio to rewrite  
</div>  
<div markdown class="option">  
<a id="m4vpl" data-level="basic">__m4vpl__</a> (sint, default: _-1_, updatable): set ProfileLevel for MPEG-4 video part two  
</div>  
<div markdown class="option">  
<a id="fullrange" data-level="basic">__fullrange__</a> (bool, default: _false_, updatable): video full range flag  
</div>  
<div markdown class="option">  
<a id="novsi" data-level="basic">__novsi__</a> (bool, default: _false_, updatable): remove video_signal_type from VUI in AVC|H264 and HEVC  
</div>  
<div markdown class="option">  
<a id="novuitiming" data-level="basic">__novuitiming__</a> (bool, default: _false_, updatable): remove timing_info from VUI in AVC|H264 and HEVC  
</div>  
<div markdown class="option">  
<a id="prof" data-level="basic">__prof__</a> (sint, default: _-1_, updatable): profile indication for AVC|H264  
</div>  
<div markdown class="option">  
<a id="lev" data-level="basic">__lev__</a> (sint, default: _-1_, updatable): level indication for AVC|H264, level_idc for VVC  
</div>  
<div markdown class="option">  
<a id="pcomp" data-level="basic">__pcomp__</a> (sint, default: _-1_, updatable): profile compatibility for AVC|H264  
</div>  
<div markdown class="option">  
<a id="pidc" data-level="basic">__pidc__</a> (sint, default: _-1_, updatable): profile IDC for HEVC and VVC  
</div>  
<div markdown class="option">  
<a id="pspace" data-level="basic">__pspace__</a> (sint, default: _-1_, updatable): profile space for HEVC  
</div>  
<div markdown class="option">  
<a id="gpcflags" data-level="basic">__gpcflags__</a> (sint, default: _-1_, updatable): general compatibility flags for HEVC  
</div>  
<div markdown class="option">  
<a id="rmsei" data-level="basic">__rmsei__</a> (bool, default: _false_, updatable): remove SEI messages from bitstream for AVC|H264, HEVC and VVC  
</div>  
<div markdown class="option">  
<a id="vidfmt" data-level="basic">__vidfmt__</a> (enum, default: _-1_, updatable): video format for AVC|H264, HEVC and VVC (component|pal|ntsc|secam|mac|undef)  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="fps" data-level="basic">__fps__</a> (frac, default: _1/0_): import frame rate, default is AVI one  
</div>  
<div markdown class="option">  
<a id="importer">__importer__</a> (bool, default: _false_): compatibility with old importer, displays import results  
</div>  
<div markdown class="option">  
<a id="noreframe">__noreframe__</a> (bool, default: _false_): skip media reframer  
</div>
Generating indexes

Indexes are constructed using the dasher filter and a given segment duration.  
Example
```
gpac -i SRC [... -i SRCn] -o index.ghi:segdur=2
```
  
This constructs a binary index for the DASH session.  
Example
```
gpac -i SRC -o index.ghix:segdur=2
```
  
This constructs an XML index for the DASH session.  
  
__Warning: XML indexes should only be used for debug purposes as they can take a significant amount of time to be parsed.__  
  
When indexing, the default template used is `$Representation$_$Number$`. The template is stored in the index and shouldn't be re-specified when generating content.
Using indexes

The index can be used to generate manifest, child variants for HLS, init segments and segments.  
Example
```
gpac -i index.ghi:gm=all -o dash/vod.mpd
```
  
This generates manifest(s) and init segment(s).  
  
Example
```
gpac -i index.ghi:rep=FOO:sn=10 -o dash/vod.mpd
```
  
This generates the 10th segment of representation with ID `FOO`.  
  
_Note: The manifest file(s) and init segment(s) are not written when generating a segment. The manifest target (mpd or m3u8) is only used to setup the filter chain and target output path._  
  
Example
```
gpac -i index.ghi:gm=main -o dash/vod.m3u8
```
  
This generates main manifest only (MPD or master HLS playlist).  
  
Example
```
gpac -i index.ghi:gm=child:rep=FOO:out=BAR -o dash/vod.m3u8
```
  
This generates child manifest for representation `FOO` in file `BAR`.  
  
Example
```
gpac -i index.ghi:gm=init:rep=FOO:out=BAR2 -o dash/vod.m3u8
```
  
This generates init segment for representation `FOO` in file `BAR2`.  
  
The filter outputs are PIDs using framed packets marked with segment boundaries and can be chained to other filters before entering the dasher (e.g. for encryption, transcode...).  
  
If representation IDs are not assigned during index creation, they default to the 1-based index of the source. You can check them using:  
Example
```
gpac -i src.ghi inspect:full
```
Muxed Representations

The filter can be used to generate muxed representations, either at manifest generation time or when generating a segment.  
Example
```
gpac -i index.ghi:mux=A@V1@V2 -o dash/vod.mpd
```
  
This will generate a manifest muxing representations `A` with representations `V1` and `V2`.  
  
Example
```
gpac -i index.ghi:mux=A@V1@V2,T@V1@V2 -o dash/vod.mpd
```
  
This will generate a manifest muxing representations `A` and `T` with representations `V1` and `V2`.  
  
Example
```
gpac -i index.ghi:rep=V2:sn=5:mux=A@V2 -o dash/vod.mpd
```
  
This will generate the 5th segment containing representations `A` and `V2`.  
  
The filter does not store any state, it is the user responsibility to use consistent information across calls:  

- do not change segment templates  
- do not change muxed representations to configurations not advertised in the generated manifests
Recommendations

Indexing supports fragmented and non-fragmented MP4, MPEG-2 TS and seekable inputs.  

- It is recommended to use fragmented MP4 as input format since this greatly reduces file loading times.  
- If non-fragmented MP4 are used, it is recommended to use single-track files to decrease the movie box size and speedup parsing.  
- MPEG-2 TS sources will be slower since they require PES reframing and AU reformating, resulting in more IOs than with mp4.  
- other seekable sources will likely be slower (seeking, reframing) and are not recommended.
Options  {.no-collapse}

<div markdown class="option">  
<a id="gm">__gm__</a> (enum, default: _main_): manifest generation mode  

- none: no manifest generation (implied if sn is not 0)  
- all: generate all manifests and init segments  
- main: generate main manifest (MPD or master M3U8)  
- child: generate child playlist for HLS  
- init: generate init segment  
</div>  
  
<div markdown class="option">  
<a id="force">__force__</a> (bool, default: _false_): force loading sources in manifest generation for debug  
</div>  
<div markdown class="option">  
<a id="rep">__rep__</a> (str): representation to generate  
</div>  
<div markdown class="option">  
<a id="sn">__sn__</a> (uint):  segment number to generate, 0 means init segment  
</div>  
<div markdown class="option">  
<a id="mux">__mux__</a> (strl): representation to mux - cf filter help  
</div>  
<div markdown class="option">  
<a id="out">__out__</a> (str): output filename to generate  
</div>
Overview

Filters are configurable processing units consuming and producing data packets. These packets are carried between filters through a data channel called _PID_. A PID is in charge of allocating/tracking data packets, and passing the packets to the destination filter(s). A filter output PID may be connected to zero or more filters. This fan-out is handled internally by GPAC (no such thing as a tee filter in GPAC).  
_Note: When a PID cannot be connected to any filter, a warning is thrown and all packets dispatched on this PID will be destroyed. The session may however still run, unless [-full-link](core_options/#full-link) is set._  
    
Each output PID carries a set of properties describing the data it delivers (e.g. _width_, _height_, _codec_, ...). Properties can be built-in (see [gpac -h props](filters_properties) ), or user-defined. Each PID tracks its properties changes and triggers filter reconfiguration during packet processing. This allows the filter chain to be reconfigured at run time, potentially reloading part of the chain (e.g. unload a video decoder when switching from compressed to uncompressed sources).  
    
Each filter exposes a set of argument to configure itself, using property types and values described as strings formatted with separators. This help is given with default separator sets `:=#,@` to specify filters, properties and options. Use [-seps](gpac_general/#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/xmlformats/NHML-Format.  

- data: formatted as:  

    - `size@address`: constant data block, not internally copied; `size` gives the size of the block, `address` the data pointer.  
    - `0xBYTESTRING`: data block specified in hexadecimal, internally copied.  
    - `file@FILE`: load data from local `FILE` (opened in binary mode).  
    - `bxml@FILE`: binarize XML from local `FILE` - see https://wiki.gpac.io/xmlformats/NHML-Format.  
    - `b64@DATA`: load data from base-64 encoded `DATA`.  
    - `FMT@val`: load values from val (comma-separated list) with `FMT` being `u8`, `s8`, `u16`, `s16`, `u32`, `s32`, `u64`, `s64`, `flt`, `dbl`, `hex` or `str`.  

- pointer: pointer address as formatted by `%p` in C.  
- string lists: formatted as `val1,val2[,...]`. Each value can also use `file@FILE` syntax.  
- integer lists: formatted as `val1,val2[,...]`  

  
_Note: The special characters in property formats (0x,/,-,+I,-I,x) cannot be configured._  
  
Numbers and fraction can be expressed as `THH:MM:SS.ms`, `TMM:SS.ms`, `THH:MM:SS` or `TMM:SS`, translated into milliseconds.
Generic declaration

Each filter is declared by its name, with optional filter arguments appended as a list of colon-separated `name=value` pairs. Additional syntax is provided for:  

- boolean: `value` can be omitted, defaulting to `true` (e.g. `:allt`). Using `!` before the name negates the result (e.g. `:!moof_first`)  
- enumerations: name can be omitted, e.g. `:disp=pbo` is equivalent to `:pbo`.  

  
    
When string parameters are used (e.g. URLs), it is recommended to escape the string using the keyword `gpac`.    
Example
```
filter:ARG=http://foo/bar?yes:gpac:opt=VAL
```
  
This will properly extract the URL.  
Example
```
filter:ARG=http://foo/bar?yes:opt=VAL
```
  
This will fail to extract it and keep `:opt=VAL` as part of the URL.  
The escape mechanism is not needed for local source, for which file existence is probed during argument parsing. It is also not needed for builtin protocol handlers (`avin://`, `video://`, `audio://`, `pipe://`)  
For schemes not using a server path, e.g. `tcp://` and `udp://`, the escape is not needed if a trailing `/` is appended after the port number.  
Example
```
-i tcp://127.0.0.1:1234:OPT
```
  
This will fail to extract the URL and options.  
Example
```
-i tcp://127.0.0.1:1234/:OPT
```
  
This will extract the URL and options.  
_Note: one trick to avoid the escape sequence is to declare the URLs option at the end, e.g. `f1:opt1=foo:url=http://bar`, provided you have only one URL parameter to specify on the filter._  
  
It is possible to locally disable option parsing (usefull for string options) by duplicating the separator.  
Example
```
filter::opt1=UDP://IP:PORT/:someopt=VAL::opt2=VAL2
```
  
This will pass `UDP://IP:PORT/:someopt=VAL` to `opt1` without inspecting it, and `VAL2` to `opt2`.
Source and Sink filters

Source and sink filters do not need to be addressed by the filter name, specifying `src=` or `dst=` instead is enough. You can also use the syntax `-src URL` or `-i URL` for sources and `-dst URL` or `-o URL` for destination, this allows prompt completion in shells.  
Example
```
"src=file.mp4" or "-src file.mp4" or  "-i file.mp4"
```
  
This will find a filter (for example `fin`) able to load `file.mp4`. The same result can be achieved by using `fin:src=file.mp4`.  
Example
```
"dst=dump.yuv" or "-dst dump.yuv" or "-o dump.yuv"
```
  
This will dump the video content in `dump.yuv`. The same result can be achieved by using `fout:dst=dump.yuv`.  
  
Specific source or sink filters may also be specified using `filterName:src=URL` or `filterName:dst=URL`.  
  
The `src=` and `dst=` syntaxes can also be used in alias for dynamic argument cloning (see `gpac -hx alias`).
Forcing specific filters

There is a special option called `gfreg` which allows specifying preferred filters to use when handling URLs.  
Example
```
src=file.mp4:gfreg=ffdmx,ffdec
```
  
This will use _ffdmx_ to read `file.mp4` and _ffdec_ to decode it.  
This can be used to test a specific filter when alternate filter chains are possible.
Specifying encoders and decoders

By default filters chain will be resolved without any decoding/encoding if the destination accepts the desired format. Otherwise, decoders/encoders will be dynamically loaded to perform the conversion, unless dynamic resolution is disabled. There is a special shortcut filter name for encoders `enc` allowing to match a filter providing the desired encoding. The parameters for `enc` are:  

- c=NAME: identifies the desired codec. `NAME` can be the GPAC codec name or the encoder instance for ffmpeg/others  
- b=UINT, rate=UINT, bitrate=UINT: indicates the bitrate in bits per second  
- g=UINT, gop=UINT: indicates the GOP size in frames  
- pfmt=NAME: indicates the target pixel format name (see [properties (-h props)](filters_properties) ) of the source, if supported by codec  
- all_intra=BOOL: indicates all frames should be intra frames, if supported by codec  

  
Other options will be passed to the filter if it accepts generic argument parsing (as is the case for ffmpeg).  
The shortcut syntax `c=TYPE` (e.g. `c=aac:opts`) is also supported.  
  
Example
```
gpac -i dump.yuv:size=320x240:fps=25 enc:c=avc:b=150000:g=50:cgop=true:fast=true -o raw.264
```
  
This creates a 25 fps AVC at 175kbps with a gop duration of 2 seconds, using closed gop and fast encoding settings for ffmpeg.  
  
The inverse operation (forcing a decode to happen) is possible using the _reframer_ filter.  
Example
```
gpac -i file.mp4 reframer:raw=av -o null
```
  
This will force decoding media from `file.mp4` and trash (send to `null`) the result (doing a decoder benchmark for example).