gaspard7/wiki_gpac huggingface dataset:
Overview {:data-level="all"}

We discuss here how to extract items from HEIF file collections. For track extraction, use the regular tools from GPAC.

A HEIF image collection will contain several items packed in a single `meta` box in ISOBMFF. These items will usually share the same coding type, although this is not a requirement. 
We only discuss here HEIF version 1 files, for which each item is an intra picture. We assume the image collection is made of HEVC items.
Extracting images {:data-level="beginner"}

You can use MP4Box to manually extract each item, see [MP4Box -h meta](mp4box-meta-opts): 

```
MP4Box -dump-item 1:path=dump.hvc source.heic
```

This will dump item 2 into `dump.hvc`.

This however requires the item ID, hence an inspection of the file prior to extracting the item.

To avoid this, you can use gpac as follows:
```
gpac -i source.heic -o dump_$ItemID$.hvc
```

This will dump each item in `dump_$ItemID$.hvc`, with `$ItemID$` being replaced by the item ID.
Transcoding as images {:data-level="beginner"}

Transcoding is not possible using MP4Box. Using gpac, it is a fairly simple process:

```
gpac -i source.heic -o dump_$ItemID$.jpg
```

This will transcode each item to JPEG  in `dump_$ItemID$.jpg`, with `$ItemID$` being replaced by the item ID. Changing the output extension to `png` will transcode to PNG.

Each item will be declared as a media PID. This implies that there will be one decoder instance and one encoder instance created for each media PID.
Transcoding as a sequence of images {:data-level="beginner"}

One way to optimize the previous drawback of high resource usage is by declaring all items as a single track using [-itt](mp4dmx#itt) option of the MP4 demultiplexer:

```
gpac -i source.heic:itt -o dump_$ItemID$.jpg
gpac -i source.heic:itt -o dump_$num$.jpg
```

In this case, a single HEVC PID will be declared, hence a single HEVC decoder and a single JPEG encoder.  

Note: Using `$num$` templating allows producing filenames independent from the item ID. 


The same approach can be used to quickly view all items declared in a file:

```
gpac -i source.heic:itt vout
```
Importing images {:data-level="beginner"}

You can use MP4Box to manually import each item, see [MP4Box -h meta](mp4box-meta-opts).

When importing images, the first image imported will be set as primary item if the destination file has no primary item.


To import a single key frame `src.hvc` source:
```
MP4Box -add-image src.hvc:primary -new image.heic
```

To import a key frame at a given time from a source video:
```
MP4Box -add-image src.hvc:primary:time=11.5 -new image.heic
```

MP4Box can also import several images at once.
To import all key frames from a source video:
```
MP4Box -add-image src.hvc:time=-1 -new image.heic
```

To import all key frames start time 3 sec to end time 22.5 second in a source video:
```
MP4Box -add-image src.hvc:primary:time=3-22.5 -new image.heic
```

To import all key frames every 30 seconds in a source video:
```
MP4Box -add-image src.hvc:primary:time=-1/30 -new image.heic
```

To import all key frames every 30 seconds from start time 3 sec to end time 3min in a source video:
```
MP4Box -add-image src.hvc:primary:time=3-180/30 -new image.heic
```
Creating images in a file with video {:data-level="beginner"}

MP4Box can create images from a file with one or more video tracks and save the combined video+items.
The syntax used is the same as the examples above except the source file is not set.
The video track to import from can be set using `tkID` option, otherwise the first video track will be used.


To import a key frame at a given sample position as item:
```
MP4Box -add-image samp=26 source.heif
```

To import all key frames as items position (here renaming the output file from mp4 to heif):
```
MP4Box -add-image time=-1 source.mp4 -out images_vid.heic
```

In the above examples, the video data is copied to the new item, which increases the file size. 
You can change that by specifying that the item is a reference to the sample data using `ref`:

```
MP4Box -add-image ref:time=-1/30 image.heic
```

In this example, the first key frame of every 30s window of the source track will be added as an item sharing the data with the track sample.
Creating grids

Grids can be created using `add-image-grid`, as illustrated in [these tests](https://github.com/gpac/testsuite/blob/filters/scripts/iff-grid.sh).

There is also a quick grid creation option called `agrid` which automatically computes a grid from the items present in the file. 
It will hide all these items and make the grid a primary item, resulting in a thumbnail-like grid picture.
All images in the file must have the same width and height. If the number of images is not even, the last image will be ignored. 

```
MP4Box -add-image long_video.mp4:time=-1/30 -add-image agrid -new thumbnails.heif
```

This will create a new file containing the first key frame of every 30s window of `long_video.mp4` and add a grid representing all these items.
The grid aspect ratio can be hinted using `agrid=AR` , with `AR` the target aspect ratio. There is no guarantee that the AR will be respected since this depends on the image source sizes and number.
Overview {:data-level="all"}

We discuss here how to use encryption in a filter chain in GPAC.  

We assume that you are familiar with encrypting ISOBMFF files with MP4Box. If not, please read the [Encryption](Encryption-Introduction) wiki first. 

MP4Box encryption is a direct wrapper around a filter chain using the source ISOBMFF file as input and the destination (new file or temp file) ISOBMFF as output. MP4Box is limited to ISOBMFF input, but this process can also be applied to any filter chain.
Loading the filter

The encryption filter in GPAC is described [here](cecrypt). It takes a single parameter locating the [DRM config file](Common-Encryption) used by the filter. This filter must be explicitly loaded in your graph, it is ignored during the graph link resolution.

 ```
 gpac -i source.mp4 cecrypt:cfile=drm.xml -o dest.mp4
 ```

This is strictly equivalent to:
```
MP4Box -crypt drm.xml source.mp4 -out dest.mp4
```

__Discussion__
As discussed [here](realtime#foreword) ( and [here](encoding) ), you need to specify a link directive to make sure that the input PIDs of your destination are indeed the output of the encryption filter.
Changing destination format

With your filter chain in place, you can now modify the output to the desired format.

The following example performs CENC encryption and dashing in a single pass:

```
gpac -i source.mp4 cecrypt:cfile=drm.xml -o dest.mpd:profile=live

```

The following example performs ISMA encryption and RTP streaming in a single pass:

```
gpac -i source.mp4 cecrypt:cfile=isma.xml -o session.sdp

```
Changing source format

You can also change your source format.
The following example performs encryption and live dashing from a live MPEG-2 TS source over udp:

```
gpac -i udp://localhost:1234 cecrypt:cfile=drm.xml -o dest.mpd:profile=live:dmode=dynamic

```

You will however need to setup the track IDs in your DRM config file to the right value, or to 0 to use a single DRM config for each PID.

If you do not know the stream IDs of your source mux and want to use different configurations for each PID, you will need to specify several encryption filters. In the following example, we apply different encryption to audio and video, using DRM config files with no assigned track IDs.

```
gpac -i udp://localhost:1234/:FID=in cecrypt:cfile=drm_audio.xml:SID=in#audio:FID=ae cecrypt:cfile=drm_video.xml:SID=in#video:FID=ve -o dest.mpd:profile=live:dmode=dynamic:SID=ae,ve
```

Another possibility is to define the `CryptInfo` PID property rather than using a global DRM config file. Combining this with conditional PID property assignment you get:
```
gpac -i udp://localhost:1234/:#CrypTrack=(audio)drm_audio.xml,(video)drm_video.xml cecrypt -o dest.mpd:profile=live:dmode=dynamic
```

This example assigns:

- a `CryptInfo` property to `drm_audio.xml` for PIDs of type audio
- a `CryptInfo` property to `drm_video.xml` for PIDs of type video
- no `CryptInfo` property for other PIDs
Overview {:data-level="all"}

We discuss here how to use ClearKey encryption in GPAC.  

We assume that you are familiar with encrypting ISOBMFF files with MP4Box. If not, please read the [Encryption](Encryption-Introduction) wiki first. 

ClearKey is a simple key distribution system for MPEG-DASH using plain text key exchange over https.
For more info, check https://github.com/Dash-Industry-Forum/ClearKey-Content-Protection

Fetching of keys through ClearKey is supported in GPAC decryptor and does not need to be configured.
Using MP4Box {:data-level="beginner"}

You first need to encrypt your source:

 ```
 MP4Box -crypt drm.xml source.mp4 -out cypted.mp4
 ```

You can then dash your source(s). If all streams share the same ClearKey licence server URL, specify `ckurl` option of dasher:

 ```
 MP4Box -dash 1000 cypted.mp4 -out dash/manifest.mpd:ckurl=https://ck.gpac.io/GetLicence
 ```


If each source has its own licence URL:
 ```
 MP4Box -dash 1000 cypted.mp4:#CKUrl=https://ck.gpac.io/GetLicence cypted2.mp4:#CKUrl=https://ck.gpac.io/GetLicence2  -out dash/manifest.mpd
 ```
Using gpac for single-pass encrypt and dash

If all streams share the same ClearKey licence server URL, specify `ckurl` option of dasher:

```
gpac -i src.mp4 cecrypt:cfile=drm.xml -o dash/manifest.mpd::ckurl=https://ck.gpac.io/GetLicence
```

Note that we use double colon separator, as the ClearKey URL also uses colons which will break parameter inheritance. One way to avoid this is to use:
```
gpac -i src.mp4 cecrypt:cfile=drm.xml  -o dash/manifest.mpd --ckurl=https://ck.gpac.io/GetLicence
```


If streams have different ClearKey licence server URL (we assume a single DRM.xml is needed here), specify `CKUrl` pid property on sources:

```
gpac -i src.mp4:#CKUrl=https://ck.gpac.io/GetLicence  -i src2.mp4:#CKUrl=https://ck.gpac.io/GetLicence2  cecrypt:cfile=drm.xml -o dash/manifest.mpd
```
Overview {:data-level="all"}

The multimedia packager available in GPAC is called MP4Box. It is mostly designed for processing ISOBMF files (e.g. MP4, 3GP), but can also be used to import/export media from container files like AVI, MPG, MKV, MPEG-2 TS ...

For detailed information on MP4Box options, check this wiki and `MP4Box -h`.

The command-line documentation available in this subsection is based on GPAC 2.0, and is automatically generated from the source tree on a daily basis.

In short, MP4Box can be used for:

* [manipulating](mp4box-gen-opts) ISOBMF files like MP4, 3GP, HEIF: removing/editing/tagging tracks, editing for specific devices, [tagging](mp4box-other-opts#tagging-support)... 
* [importing](mp4box-import-opts) audio, video and presentation data (including subtitles) from different sources and in different formats,
* packaging of content for [[HTTP Adaptive Streaming|DASH-intro]]  (MPEG-DASH, HLS), [RTP/RTSP](mp4box-other-opts#hinting-options) streaming or HTTP download
* editing/packaging of [HEIF image](mp4box-meta-opts) files
* [encryption and decryption](mp4box-gen-opts#encryptiondecryption-options) of streams
* [exporting and splitting](mp4box-dump-opts) ISOBMFF files
* [transcoding](mp4box-filters) audio and video
* [encoding/decoding](mp4box-scene-opts) presentation languages like MPEG-4 XMT or W3C SVG into/from binary formats like MPEG-4 BIFS or LASeR
Content Packaging

MP4Box can be used to repackage existing content to compliant ISO Base Media Files (MP4, 3GP, 3G2, OMA DCF). 

_Note  MP4Box prior to 0.9.0 does NOT re-encode audio, video and still image content, external tools shall be used for this purpose. With MP4Box 0.9.0 or above, MP4Box can be used in combination with encoding filters to [transcode the content](mp4box-filters)._

*   Remove specific track/streams from an MP4 file (this removes the third and fourth streams):

`MP4Box -rem 3 -rem 4 file.mp4`

*   Importing a media file to an existing MP4 file:

`MP4Box -add file.avi my_file.mp4`

*   Importing a media file to an new MP4 file:

`MP4Box -add file.avi -new new_file.mp4`

*   Adding a secondary audio track to the previous file:

`MP4Box -add audio2.mp3 new_file.mp4`

*   MP4Box can import specific media from an existing container. To get the supported media that can be imported from a container:

`MP4Box -info file`

*   Add a single audio stream  from a container:

`MP4Box -add file.mpg#audio new_file.mp4`

*   Add a specific duration of a media from a container:

`MP4Box -add file.mpg#audio:dur=10 new_file.mp4`

*   Adjust/correct a video stream with an incorrect aspect ratio (DAR = SAR x PAR):

`MP4Box -par 1=4:3 file.mp4`

*   To replace the label on an audio or subtitle track (uses udta "name" atom, shown by players like vlc):

`MP4Box -udta 3:type=name -udta 3:type=name:str="Director Commentary" file.mp4`
Delivery Setup

MP4Box can be used to prepare files for different delivery protocols, mainly HTTP downloading or RTP streaming.

*   To prepare a file for simple progressive HTTP download, the following instruction will interleave file data by chunks of 500 milliseconds in order to enable playback while downloading the file (HTTP FastStart):

`MP4Box -inter 500 file.mp4`

*   To prepare for RTP, the following instruction will create RTP hint tracks for the file. This enables classic streaming servers like DarwinStreamingServer or QuickTime Streaming Server to deliver the file through RTSP/RTP:

`MP4Box -hint file.mp4`

*   To prepare for adaptive streaming (MPEG-DASH), the following instruction will create the DASH manifest and associated files. For more information on DASH see [[this page|DASH Support in MP4Box]]:

`MP4Box -dash 1000 file.mp4`

*   To prepare for CMAF MPEG-DASH and HLS:

```
MP4Box -dash 1000 file.mp4 -out live.m3u8:dual:cmaf
MP4Box -dash 1000 file.mp4 -out live.mpd --dual --cmaf
```
Scene Transcoding

MP4Box can be used to encode MPEG-4 scene descriptions BIFS and LASeR and to decode MPEG-4 scene descriptions BIFS and LASeR.

*   To encode an existing description:

`MP4Box -mp4 scene.bt`

_Note MP4Box will do its best to encode VRML/X3D to MPEG-4, but that not all tools from X3D or VRML extensions are supported in MPEG-4._

*   To decode an existing BIFS track to a BIFS Text format (VRML-like format)description:

`MP4Box -bt file.mp4`

*   To decode an existing BIFS track to XMT-A format:

`MP4Box -xmt file.mp4`

*   To decode an existing LASeR track to an XSR format (SAF+LASeR Markup Language) description:

`MP4Box -lsr file.mp4`

*   To decode the first sample of an existing LASeR track to an SVG file:

`MP4Box -svg file.mp4`
Extracting Options

MP4Box can be used to extract media tracks from MP4 files. If you need to convert these tracks however, please check the [filters doc](Filters).  
    
Options:  
<div markdown class="option">
<a id="raw" data-level="basic">__-raw__</a> (string): extract given track in raw format when supported. Use `tkID:output=FileName` to set output file name  
</div>
<div markdown class="option">
<a id="raws" data-level="basic">__-raws__</a> (string): extract each sample of the given track to a file. Use `tkID:N` to extract the Nth sample  
</div>
<div markdown class="option">
<a id="nhnt" data-level="basic">__-nhnt__</a> (int): extract given track to [NHNT](nhntr) format  
</div>
<div markdown class="option">
<a id="nhml" data-level="basic">__-nhml__</a> (string): extract given track to [NHML](nhmlr) format. Use `tkID:full` for full NHML dump with all packet properties  
</div>
<div markdown class="option">
<a id="webvtt-raw" data-level="basic">__-webvtt-raw__</a> (string): extract given track as raw media in WebVTT as metadata. Use `tkID:embedded` to include media data in the WebVTT file  
</div>
<div markdown class="option">
<a id="single" data-level="basic">__-single__</a> (int): extract given track to a new mp4 file  
</div>
<div markdown class="option">
<a id="six" data-level="basic">__-six__</a> (int): extract given track as raw media in __experimental__ XML streaming instructions  
</div>
<div markdown class="option">
<a id="mux" data-level="basic">__-mux__</a> (string): multiplex input file to given destination  
</div>
<div markdown class="option">
<a id="qcp" data-level="basic">__-qcp__</a> (int): same as [-raw](#raw) but defaults to QCP file for EVRC/SMV  
</div>
<div markdown class="option">
<a id="saf" data-level="basic">__-saf__</a>: multiplex input file to SAF multiplex  
</div>
<div markdown class="option">
<a id="dvbhdemux" data-level="basic">__-dvbhdemux__</a>: demultiplex DVB-H file into IP Datagrams sent on the network  
</div>
<div markdown class="option">
<a id="raw-layer" data-level="basic">__-raw-layer__</a> (int): same as [-raw](#raw) but skips SVC/MVC/LHVC extractors when extracting  
</div>
<div markdown class="option">
<a id="diod" data-level="basic">__-diod__</a>: extract file IOD in raw format  
</div>
<div markdown class="option">
<a id="mpd" data-level="basic">__-mpd__</a> (string): convert given HLS or smooth manifest (local or remote http) to MPD - options `-url-template` and `-segment-timeline`can be used in this mode.    
_Note: This only provides basic conversion, for more advanced conversions, see `gpac -h dasher`_  
    

__Warning: This is not compatible with other DASH options and does not convert associated segments__  
  
</div>
Tagging support

Tags are specified as a colon-separated list `tag_name=tag_value[:tag2=val2]`  
Setting a tag with no value or value `NULL` removes the tag.  
Special tag value `clear` (or `reset`) removes all tags.  
Unsupported tags can be added using their four character code as a tag name, and string value will be assumed.  
If the tag name length is 3, the prefix 0xA9 is used to create the four character code.  
    
Tags can also be loaded from a text file using `-itags filename`. The file must be in UTF8 with:  

- lines starting with `tag_name=value` specify the start of a tag  
- other lines specify the remainder of the last declared tag  

    
If tag name starts with `WM/`, the tag is added to `Xtra` box (WMA tag, string only).
QT metadata key

The tag is added as a QT metadata key if:  

- `tag_name` starts with `QT/`  
- or `tag_name` is not recognized and longer than 4 characters  

    
The `tag_name` can optionally be prefixed with `HDLR@`, indicating the tag namespace 4CC, the default namespace being `mdta`.  
The `tag_value` can be prefixed with:  

- S: force string encoding (must be placed first) instead of parsing the tag value  
- b: use 8-bit encoding for signed or unsigned int  
- s: use 16-bit encoding for signed or unsigned int  
- l: use 32-bit encoding for signed or unsigned int  
- L: use 64-bit encoding for signed or unsigned int  
- f: force float encoding for numbers  

Numbers are converted by default and stored in variable-size mode.  
To force a positive integer to use signed storage, add `+` in front of the number.  
Example
```
-tags io.gpac.some_tag=s+32
```
  
This will force storing value `32` in signed 16 bit format.  
The `tag_value` can also be formatted as:  

- XxY@WxH: a rectangle type  
- XxY: a point type  
- W@H: a size type  
- A,B,C,D,E,F,G,H,I: a 3x3 matrix  
- FNAME: data is loaded from `FNAME`, type set to jpeg or png if needed
Supported tag names (name, value, type, aliases)

__title__ (A9nam) string (`alias` name)  
__artist__ (A9ART) string  
__album_artist__ (aART) string (`alias` albumArtist)  
__album__ (A9alb) string  
__group__ (A9grp) string (`alias` grouping)  
__composer__ (A9com) string  
__writer__ (A9wrt) string  
__conductor__ (A9con) string  
__comment__ (A9cmt) string (`alias` comments)  
__genre__ (gnre) string (ID3 genre tag)  
__created__ (A9day) string (`alias` releaseDate)  
__track__ (A9trk) string  
__tracknum__ (trkn) fraction (syntax: `A/B` or `A`, B will be 0)  
__disk__ (disk) fraction (syntax: `A/B` or `A`, B will be 0)  
__tempo__ (tmpo) integer  
__compilation__ (cpil) bool (`yes` or `no`)  
__show__ (tvsh) string (`alias` tvShow)  
__episode_id__ (tven) string (`alias` tvEpisodeID)  
__season__ (tvsn) integer (`alias` tvSeason)  
__episode__ (tves) integer (`alias` tvEPisode)  
__network__ (tvnn) string (`alias` tvNetwork)  
__sdesc__ (desc) string (`alias` description)  
__ldesc__ (ldes) string (`alias` longDescription)  
__lyrics__ (A9lyr) string  
__sort_name__ (sonm) string (`alias` sortName)  
__sort_artist__ (soar) string (`alias` sortArtist)  
__sort_album_artist__ (soaa) string (`alias` sortAlbumArtist)  
__sort_album__ (soal) string (`alias` sortAlbum)  
__sort_composer__ (soco) string (`alias` sortComposer)  
__sort_show__ (sosn) string (`alias` sortShow)  
__cover__ (covr) file path (`alias` artwork)  
__copyright__ (cprt) string  
__tool__ (A9too) string (`alias` encodingTool)  
__encoder__ (A9enc) string (`alias` encodedBy)  
__pdate__ (purd) string (`alias` purchaseDate)  
__podcast__ (pcst) bool (`yes` or `no`)  
__url__ (purl) string (`alias` podcastURL)  
__keywords__ (kyyw) string  
__category__ (catg) string  
__hdvideo__ (hdvd) integer  
__media__ (stik) integer (`alias` mediaType)  
__rating__ (rtng) integer (`alias` contentRating)  
__gapless__ (pgap) bool (`yes` or `no`)  
__art_director__ (A9ard) string  
__arranger__ (A9arg) string  
__lyricist__ (A9aut) string  
__acknowledgement__ (A9cak) string  
__song_description__ (A9des) string  
__director__ (A9dir) string  
__equalizer__ (A9equ) string  
__liner__ (A9lnt) string  
__record_company__ (A9mak) string  
__original_artist__ (A9ope) string  
__phono_rights__ (A9phg) string  
__producer__ (A9prd) string  
__performer__ (A9prf) string  
__publisher__ (A9pub) string  
__sound_engineer__ (A9sne) string  
__soloist__ (A9sol) string  
__credits__ (A9src) string  
__thanks__ (A9thx) string  
__online_info__ (A9url) string  
__exec_producer__ (A9xpd) string  
__genre__ (A9gen) string (ID3 genre tag)  
__location__ (A9xyz) string
Encryption/Decryption Options

MP4Box supports encryption and decryption of ISMA, OMA and CENC content, see [encryption filter `gpac -h cecrypt`](cecrypt).  
It requires a specific XML file called `CryptFile`, whose syntax is available at https://wiki.gpac.io/xmlformats/Common-Encryption  
Image files (HEIF) can also be crypted / decrypted, using CENC only.  
    
Options:  
<div markdown class="option">
<a id="crypt" data-level="basic">__-crypt__</a> (string): encrypt the input file using the given `CryptFile`  
</div>
<div markdown class="option">
<a id="decrypt" data-level="basic">__-decrypt__</a> (string): decrypt the input file, potentially using the given `CryptFile`. If `CryptFile` is not given, will fail if the key management system is not supported  
</div>
<div markdown class="option">
<a id="set-kms" data-level="basic">__-set-kms__</a> `tkID=kms_uri`: change ISMA/OMA KMS location for a given track or for all tracks if `all=` is used  
</div>