gaspard7/wiki_gpac huggingface dataset:
TTML Support

If [ttml_split](#ttml_split) option is set, the TTML document is split in independent time segments by inspecting all overlapping subtitles in the body.  
Empty periods in TTML will result in empty TTML documents or will be skipped if [no_empty](#no_empty) option is set.  
  
The first sample has a CTS assigned as indicated by [ttml_cts](#ttml_cts):  

- a numerator of -2 indicates the first CTS is 0  
- a numerator of -1 indicates the first CTS is the first active time in document  
- a numerator &gt;= 0 indicates the CTS to use for first sample  

  
When TTML splitting is disabled, the duration of the TTML sample is given by [ttml_dur](#ttml_dur) if not 0, or set to the document duration  
  
By default, media resources are kept as declared in TTML2 documents.  
  
[ttml_embed](#ttml_embed) can be used to embed inside the TTML sample the resources in `<head>` or `<body>`:  

- for `<source>`, `<image>`, `<audio>`, `<font>`, local URIs indicated in `src` will be loaded and `src` rewritten.  
- for `<data>` with base64 coding, the data will be decoded, `<data>` element removed and parent &lt;source&gt; rewritten with `src` attribute inserted.  

  
The embedded data is added as a subsample to the TTML frame, and the referring elements will use `src=urn:mpeg:14496-30:N` with `N` the index of the subsample.  
  
A `subtitle zero` may be specified using [ttml_zero](#ttml_zero). This will remove all subtitles before the given time `T0`, and rewrite each subtitle begin/end `T` to `T-T0` using millisecond accuracy.  

__Warning: Original time formatting (tick, frames/subframe ...) will be lost when this option is used, converted to `HH:MM:SS.ms`.__  
  
The subtitle zero time __must__ be prefixed with `T` when the option is not set as a global argument:  
Example
```
gpac -i test.ttml:ttml_zero=T10:00:00 [...]  
MP4Box -add test.ttml:sopt:ttml_zero=T10:00:00 [...]  
gpac -i test.ttml --ttml_zero=10:00:00 [...]  
gpac -i test.ttml --ttml_zero=T10:00:00 [...]  
MP4Box -add test.ttml --ttml_zero=10:00:00 [...]
```
Simple Text Support

The text loader can convert input files in simple text streams of a single packet, by forcing the codec type on the input:  
Example
```
gpac -i test.txt:#CodecID=stxt  [...]  
gpac fin:pck="Text Data":#CodecID=stxt  [...]
```
  
  
The content of the source file will be the payload of the text sample. The [stxtmod](#stxtmod) option allows specifying WebVTT, TX3G or simple text mode for output format.  
In this mode, the [stxtdur](#stxtdur) option is used to control the duration of the generated subtitle:  

- a positive value always forces the duration  
- a negative value forces the duration if input packet duration is not known
Options  {.no-collapse}

<div markdown class="option">  
<a id="nodefbox">__nodefbox__</a> (bool, default: _false_): skip default text box  
</div>  
<div markdown class="option">  
<a id="noflush">__noflush__</a> (bool, default: _false_): skip final sample flush for srt  
</div>  
<div markdown class="option">  
<a id="fontname" data-level="basic">__fontname__</a> (str): default font  
</div>  
<div markdown class="option">  
<a id="fontsize" data-level="basic">__fontsize__</a> (uint, default: _18_): default font size  
</div>  
<div markdown class="option">  
<a id="lang" data-level="basic">__lang__</a> (str): default language  
</div>  
<div markdown class="option">  
<a id="width" data-level="basic">__width__</a> (uint, default: _0_): default width of text area  
</div>  
<div markdown class="option">  
<a id="height" data-level="basic">__height__</a> (uint, default: _0_): default height of text area  
</div>  
<div markdown class="option">  
<a id="txtx" data-level="basic">__txtx__</a> (uint, default: _0_): default horizontal offset of text area: -1 (left), 0 (center) or 1 (right)  
</div>  
<div markdown class="option">  
<a id="txty" data-level="basic">__txty__</a> (uint, default: _0_): default vertical offset of text area: -1 (bottom), 0 (center) or 1 (top)  
</div>  
<div markdown class="option">  
<a id="zorder">__zorder__</a> (sint, default: _0_): default z-order of the PID  
</div>  
<div markdown class="option">  
<a id="timescale">__timescale__</a> (uint, default: _1000_): default timescale of the PID  
</div>  
<div markdown class="option">  
<a id="ttml_split">__ttml_split__</a> (bool, default: _true_): split ttml doc in non-overlapping samples  
</div>  
<div markdown class="option">  
<a id="ttml_cts">__ttml_cts__</a> (lfrac, default: _-1/1_): first sample cts - see filter help  
</div>  
<div markdown class="option">  
<a id="ttml_dur">__ttml_dur__</a> (frac, default: _0/1_): sample duration when not spliting split - see filter help  
</div>  
<div markdown class="option">  
<a id="ttml_embed">__ttml_embed__</a> (bool, default: _false_): force embedding TTML resources  
</div>  
<div markdown class="option">  
<a id="ttml_zero">__ttml_zero__</a> (str): set subtitle zero time for TTML  
</div>  
<div markdown class="option">  
<a id="no_empty">__no_empty__</a> (bool, default: _false_): do not send empty samples  
</div>  
<div markdown class="option">  
<a id="stxtdur">__stxtdur__</a> (frac, default: _1_): duration for simple text  
</div>  
<div markdown class="option">  
<a id="stxtmod">__stxtmod__</a> (enum, default: _tx3g_): text stream mode for simple text streams and SRT inputs  

- stxt: output PID formatted as simple text stream  
- sbtt: output PID formatted as subtitle text stream  
- tx3g: output PID formatted as TX3G/Apple stream  
- vtt: output PID formatted as WebVTT stream  
- webvtt: same as vtt (for backward compatiblity  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="exporter">__exporter__</a> (bool, default: _false_): compatibility with old exporter, displays export results  
</div>  
<div markdown class="option">  
<a id="pfmt" data-level="basic">__pfmt__</a> (pfmt, default: _none_, Enum: none|yuv420|yvu420|yuv420_10|yuv422|yuv422_10|yuv444|yuv444_10|uyvy|vyuy|yuyv|yvyu|uyvl|vyul|yuyl|yvyl|nv12|nv21|nv1l|nv2l|yuva|yuvd|yuv444a|yuv444p|v308|yuv444ap|v408|v410|v210|grey|algr|gral|rgb4|rgb5|rgb6|rgba|argb|bgra|abgr|rgb|bgr|xrgb|rgbx|xbgr|bgrx|rgbd|rgbds|uncv): pixel format for raw extract. If not set, derived from extension  
</div>  
  
<div markdown class="option">  
<a id="afmt" data-level="basic">__afmt__</a> (afmt, default: _none_, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|u8p|s16p|s24p|s32p|fltp|dblp): audio format for raw extract. If not set, derived from extension  
</div>  
  
<div markdown class="option">  
<a id="decinfo">__decinfo__</a> (enum, default: _auto_): decoder config insert mode  

- no: never inserted  
- first: inserted on first packet  
- sap: inserted at each SAP  
- auto: selects between no and first based on media type  
</div>  
  
<div markdown class="option">  
<a id="split">__split__</a> (bool, default: _false_): force one file per decoded frame  
</div>  
<div markdown class="option">  
<a id="frame" data-level="basic">__frame__</a> (bool, default: _false_): force single frame dump with no rewrite. In this mode, all codec types are supported  
</div>  
<div markdown class="option">  
<a id="sstart" data-level="basic">__sstart__</a> (uint, default: _0_): start number of frame to forward. If 0, all samples are forwarded  
</div>  
<div markdown class="option">  
<a id="send" data-level="basic">__send__</a> (uint, default: _0_): end number of frame to forward. If less than start frame, all samples after start are forwarded  
</div>  
<div markdown class="option">  
<a id="dur" data-level="basic">__dur__</a> (frac, default: _0_): duration of media to forward after first sample. If 0, all samples are forwarded  
</div>  
<div markdown class="option">  
<a id="merge_region" data-level="basic">__merge_region__</a> (bool, default: _false_): merge TTML regions with same ID while reassembling TTML doc  
</div>  
<div markdown class="option">  
<a id="vtth" data-level="basic">__vtth__</a> (enum, default: _seg_): vtt header injection mode  

- single: inject only at first frame of the stream  
- seg: inject at each non-empty segment  
- all: inject at each segment even empty ones  
</div>
DASH and HLS segmenter

Register name used to load filter: __dasher__  
This filter may be automatically loaded during graph resolution.  
This filter requires the graph resolver to be activated.  
  
This filter provides segmentation and manifest generation for MPEG-DASH and HLS formats.  
The segmenter currently supports:  

- MPD and m3u8 generation (potentially in parallel)  
- ISOBMFF, MPEG-2 TS, MKV and raw bitstream segment formats  
- override of profiles and levels in manifest for codecs  
- most MPEG-DASH profiles  
- static and dynamic (live) manifest offering  
- context store and reload for batch processing of live/dynamic sessions  

  
The filter does perform per-segment real-time regulation using [sreg](#sreg).  
If you need per-frame real-time regulation on non-real-time inputs, insert a [reframer](reframer) before to perform real-time regulation.  
Example
```
gpac -i file.mp4 reframer:rt=on -o live.mpd:dmode=dynamic
```
Template strings

The segmenter uses templates to derive output file names, regardless of the DASH mode (even when templates are not used). The default one is `$File$_dash` for ondemand and single file modes, and `$File$_$Number$` for separate segment files  
Example
```
template=Great_$File$_$Width$_$Number$
```
  
If input is `foo.mp4` with `640x360` video resolution, this will resolve in `Great_foo_640_$Number$` for the DASH template.  
Example
```
template=Great_$File$_$Width$
```
  
If input is `foo.mp4` with `640x360` video resolution, this will resolve in `Great_foo_640.mp4` for onDemand case.  
  
Standard DASH replacement strings:   

- $Number[%%0Nd]$: replaced by the segment number, possibly prefixed with 0  
- $RepresentationID$: replaced by representation name  
- $Time$: replaced by segment start time  
- $Bandwidth$: replaced by representation bandwidth.  

_Note: these strings are not replaced in the manifest templates elements._  
  
Additional replacement strings (not DASH, not generic GPAC replacements but may occur multiple times in template):  

- $Init=NAME$: replaced by NAME for init segment, ignored otherwise  
- $XInit=NAME$: complete replace by NAME for init segment, ignored otherwise  
- $InitExt=EXT$: replaced by EXT for init segment file extensions, ignored otherwise  
- $Index=NAME$: replaced by NAME for index segments, ignored otherwise  
- $Path=PATH$: replaced by PATH when creating segments, ignored otherwise  
- $Segment=NAME$: replaced by NAME for media segments, ignored for init segments  
- $SegExt=EXT$: replaced by EXT for media segment file extensions, ignored for init segments  
- $FS$ (FileSuffix): replaced by `_trackN` in case the input is an AV multiplex, or kept empty otherwise  

_Note: these strings are replaced in the manifest templates elements._
Segmentation

The default behavior of the segmenter is to estimate the theoretical start time of each segment based on target segment duration, and start a new segment when a packet with SAP type 1,2,3 or 4 with time greater than the theoretical time is found.  
This behavior can be changed to find the best SAP packet around a segment theoretical boundary using [sbound](#sbound):  

- `closest` mode: the segment will start at the closest SAP of the theoretical boundary  
- `in` mode: the segment will start at or before the theoretical boundary  


__Warning: These modes will introduce delay in the segmenter (typically buffering of one GOP) and should not be used for low-latency modes.__  
  
The segmenter can also be configured to:  

- completely ignore SAP when segmenting using [sap](#sap).  
- ignore SAP on non-video streams when segmenting using [strict_sap](#strict_sap).  

  
When [seg_sync](#seg_sync) is disabled, the segmenter will by default announce a new segment in the manifest(s) as soon as its size/offset is known or its name is known, but the segment (or part in LL-HLS) may still not be completely written/sent.  
This may result in temporary mismatches between segment/part size currently received versus size as advertized in manifest.  
When [seg_sync](#seg_sync) is enabled, the segmenter will wait for the last byte of the fragment/segment to be pushed before announcing a new segment in the manifest(s). This can however slightly increase the latency in MPEG-DASH low-latency.  
  
When (-sflush)[] is set to `single`, segmentation is skipped and a single segment is generated per input.
Dynamic (real-time live) Mode

The dasher does not perform real-time regulation by default.  
For regular segmentation, you should enable segment regulation [sreg](#sreg) if your sources are not real-time.  
Example
```
gpac -i source.mp4 -o live.mpd:segdur=2:profile=live:dmode=dynamic:sreg
```
  
  
For low latency segmentation with fMP4, you will need to specify the following options:  

- cdur: set the fMP4 fragment duration  
- asto: set the availability time offset for DASH. This value should be equal or slightly greater than segment duration minus cdur  
- llhls: enable low latency for HLS  

  
_Note: [llhls](#llhls) does not force `cmaf` mode to allow for multiplexed media in segments but it enforces to `tfdt_traf` in the muxer._  
  
If your sources are not real-time, insert a reframer filter with real-time regulation  
Example
```
gpac -i source.mp4 reframer:rt=on -o live.mpd:segdur=2:cdur=0.2:asto=1.8:profile=live:dmode=dynamic
```
  
This will create DASH segments of 2 seconds made of fragments of 200 ms and indicate to the client that requests can be made 1.8 seconds earlier than segment complete availability on server.  
Example
```
gpac -i source.mp4 reframer:rt=on -o live.m3u8:segdur=2:cdur=0.2:llhls=br:dmode=dynamic
```
  
This will create DASH segments of 2 seconds made of fragments of 200 ms and produce HLS low latency parts using byte ranges in the final segment.  
Example
```
gpac -i source.mp4 reframer:rt=on -o live.m3u8:segdur=2:cdur=0.2:llhls=sf:dmode=dynamic
```
  
This will create DASH segments of 2 seconds made of fragments of 200 ms and produce HLS low latency parts using dedicated files.  
  
You can combine LL-HLS and DASH-LL generation:  
Example
```
gpac -i source.mp4 reframer:rt=on -o live.mpd:dual:segdur=2:cdur=0.2:asto=1.8:llhls=br:profile=live:dmode=dynamic
```
  
  
For DASH, the filter will use the local clock for UTC anchor points in DASH.  
The filter can fetch and signal clock in other ways using [utcs](#utcs).  
Example
```
[opts]:utcs=inband
```
  
This will use the local clock and insert in the MPD a UTCTiming descriptor containing the local clock.  
Example
```
[opts]::utcs=http://time.akamai.com[::opts]
```
  
This will fetch time from `http://time.akamai.com`, use it as the UTC reference for segment generation and insert in the MPD a UTCTiming descriptor containing the time server URL.  
_Note: if not set as a global option using `--utcs=`, you must escape the url using double `::` or use other separators._
Cue-driven segmentation

The segmenter can take a list of instructions, or Cues, to use for the segmentation process, in which case only these are used to derive segment boundaries. Cues can be set through XML files or injected in input packets.  
  
Cue files can be specified for the entire segmenter, or per PID using `DashCue` property.  
Cues are given in an XML file with a root element called &lt;DASHCues&gt;, with currently no attribute specified. The children are one or more &lt;Stream&gt; elements, with attributes:  

- id: integer for stream/track/PID ID  
- timescale: integer giving the units of following timestamps  
- mode: if present and value is `edit`, the timestamp are in presentation time (edit list applied) otherwise they are in media time  
- ts_offset: integer giving a value (in timescale) to subtract to the DTS/CTS values listed  

  
The children of &lt;Stream&gt; are one or more &lt;Cue&gt; elements, with attributes:  

- sample: integer giving the sample/frame number of a sample at which splitting shall happen  
- dts: long integer giving the decoding time stamp of a sample at which splitting shall happen  
- cts: long integer giving the composition / presentation time stamp of a sample at which splitting shall happen  


__Warning: Cues shall be listed in decoding order.__  
  
If the `DashCue` property of a PID equals `inband`, the PID will be segmented according to the `CueStart` property of input packets.  
This feature is typically combined with a list of files as input:  
Example
```
gpac -i list.m3u:sigcues -o res/live.mpd
```
  
This will load the `flist` filter in cue mode, generating continuous timelines from the sources and injecting a `CueStart` property at each new file.  
  
If the [cues](#cues) option equals `none`, the `DashCue` property of input PIDs will be ignored.
Manifest Generation only mode

The segmenter can be used to generate manifests from already fragmented ISOBMFF inputs using [sigfrag](#sigfrag).  
In this case, segment boundaries are attached to each packet starting a segment and used to drive the segmentation.  
This can be used with single-track ISOBMFF sources, either single file or multi file.  
For single file source:  

- if onDemand [profile](#profile) is requested, sources have to be formatted as a DASH self-initializing media segment with the proper sidx.  
- templates are disabled.  
- [sseg](#sseg) is forced for all profiles except onDemand ones.  

For multi files source:  

- input shall be a playlist containing the initial file followed by the ordered list of segments.  
- if no [template](#template) is provided, the full or main [profile](#profile) will be used  
- if [-template]() is provided, it shall be correct: the filter will not try to guess one from the input file names and will not validate it either.  

  
The manifest generation-only mode supports both MPD and HLS generation.  
  
Example
```
gpac -i ondemand_src.mp4 -o dash.mpd:sigfrag:profile=onDemand
```
  
This will generate a DASH manifest for onDemand Profile based on the input file.  
Example
```
gpac -i ondemand_src.mp4 -o dash.m3u8:sigfrag
```
  
This will generate a HLS manifest based on the input file.  
Example
```
gpac -i seglist.txt -o dash.mpd:sigfrag
```
  
This will generate a DASH manifest in Main Profile based on the input files.  
Example
```
gpac -i seglist.txt:Template=$XInit=init$$q1/$Number$ -o dash.mpd:sigfrag:profile=live
```
  
This will generate a DASH manifest in live Profile based on the input files. The input file will contain `init.mp4`, `q1/1.m4s`, `q1/2.m4s`...
Cue Generation only mode

The segmenter can be used to only generate segment boundaries from a set of inputs using [gencues](#gencues), without generating manifests or output files.  
In this mode, output PIDs are declared directly rather than redirected to media segment files.  
The segmentation logic is not changed, and packets are forwarded with the same information and timing as in regular mode.  
  
Output PIDs are forwarded with `DashCue=inband` property, so that any subsequent dasher follows the same segmentation process (see above).  
  
The first packet in a segment has:  

- property `FileNumber` (and, if multiple files, `FileName`) set as usual  
- property `CueStart` set  
- property `DFPStart=0` set if this is the first packet in a period  

  
This mode can be used to pre-segment the streams for later processing that must take place before final dashing.  
Example
```
gpac -i source.mp4 dasher:gencues cecrypt:cfile=roll_seg.xml -o live.mpd
```
  
This will allow the encrypter to locate dash boundaries and roll keys at segment boundaries.  
Example
```
gpac -i s1.mp4 -i s2.mp4:#CryptInfo=clear:#Period=3 -i s3.mp4:#Period=3 dasher:gencues cecrypt:cfile=roll_period.xml -o live.mpd
```
  
If the DRM file uses `keyRoll=period`, this will generate:  

- first period crypted with one key  
- second period clear  
- third period crypted with another key
Forced-Template mode

When [tpl_force](#tpl_force) is set, the [template](#template) string is not analyzed nor modified for missing elements.  
This is typically used to redirect segments to a given destination regardless of the dash profile.  
Example
```
gpac -i SRC -o null:ext=mpd:tpl_force --template=pipe://mypipe
```
  
This will trash the manifest and open `mypipe` as destination for the muxer result.  

__Warning: Options for segment destination cannot be set through the [template](#template), global options must be used.__
Batch Operations

The segmentation can be performed in multiple calls using a DASH context set with [state](#state).  
Between calls, the PIDs are reassigned by checking that the PID ID match between the calls and:  

- the input file names match between the calls  
- or the representation ID (and period ID if specified) match between the calls  

  
If a PID is not matched, it will be assigned to a new period.  
  
The default behaviour assume that the same inputs are used for segmentation and rebuilds a contiguous timeline at each new file start.  
If the inputs change but form a continuous timeline, [-keep_ts])() must be used to skip timeline reconstruction.  
  
The inputs will be segmented for a duration of [subdur](#subdur) if set, otherwise the input media duration.  
When inputs are over, they are restarted if [loop](#loop) is set otherwise a new period is created.  
To avoid this behaviour, the [sflush](#sflush) option should be set to `end` or `single`, indicating that further sources for the same representations will be added in subsequent calls. When [sflush](#sflush) is not `off`, the (-loop)[] option is ignored.  
  
Example
```
gpac -i SRC -o dash.mpd:segdur=2:state=CTX && gpac -i SRC -o dash.mpd:segdur=2:state=CTX
```
  
This will generate all dash segments for `SRC` (last one possibly shorter) and create a new period at end of input.  
Example
```
gpac -i SRC -o dash.mpd:segdur=2:state=CTX:loop && gpac -i SRC -o dash.mpd:segdur=2:state=CTX:loop
```
  
This will generate all dash segments for `SRC` and restart `SRC` to fill-up last segment.  
Example
```
gpac -i SRC -o dash.mpd:segdur=2:state=CTX:sflush=end && gpac -i SRC -o dash.mpd:segdur=2:state=CTX:sflush=end
```
  
This will generate all dash segments for `SRC` without looping/closing the period at end of input. Timestamps in the second call will be rewritten to be contiguous with timestamp at end of first call.  
Example
```
gpac -i SRC1 -o dash.mpd:segdur=2:state=CTX:sflush=end:keep_ts && gpac -i SRC2 -o dash.mpd:segdur=2:state=CTX:sflush=end:keep_ts
```
  
This will generate all dash segments for `SRC1` without looping/closing the period at end of input, then for `SRC2`. Timestamps of the sources will not be rewritten.  
  
_Note: The default behaviour of MP4Box `-dash-ctx` option is to set the (-loop)[] to true._
Output redirecting

When loaded implicitly during link resolution, the dasher will only link its outputs to the target sink  
Example
```
gpac -i SRC -o URL1:OPTS1 -o URL2:OPTS1
```
  
This will create one dasher (with options OPTS1) for the URL1 and one dasher (with options OPTS1) for URL2.  
This allows dashing to multiple outputs with different formats, dash durations, etc.  
  
It can be useful to redirect all the filter outputs to several sinks, for example to push through ROUTE and through HTTP the same segments.  
In order to do this, the filter MUST be explicitly loaded and all options related to dash and MP4 must be set either globally or on the dasher filter.  
Example
```
gpac -i SRC dasher:cmfc:segdur=2 -o URL1 -o URL2
```
  
This will create a single dasher whose outputs (manifests and segments) will be redirected to the given URLs.  
When explicitly loading the filter, the [dual](#dual) option will be disabled unless [mname](#mname) is set to the alternate output name.