gaspard7/wiki_gpac huggingface dataset:
Help Options

<div markdown class="option">
<a id="h" data-level="basic">__-h__</a> (string): print help  

- general: general options help  
- hint: hinting options help  
- dash: DASH segmenter help  
- split: split options help  
- import: import options help  
- encode: scene description encoding options help  
- meta: meta (HEIF, MPEG-21) handling options help  
- extract: extraction options help  
- dump: dump options help  
- swf: Flash (SWF) options help  
- crypt: ISMA E&A options help  
- format: supported formats help  
- live: BIFS streamer help  
- core: libgpac core options  
- all: print all the above help screens  
- opts: print all options  
- tags: print supported iTunes tags  
- cicp: print various CICP code points  
- VAL: search for option named `VAL` (without `-` or `--`) in MP4Box, libgpac core and all filters  
  
</div>
  
<div markdown class="option">
<a id="hx" data-level="basic">__-hx__</a> (string): look for given string in name and descriptions of all MP4Box and filters options  
</div>
<div markdown class="option">
<a id="nodes" data-level="basic">__-nodes__</a>: list supported MPEG4 nodes  
</div>
<div markdown class="option">
<a id="nodex" data-level="basic">__-nodex__</a>: list supported MPEG4 nodes and print nodes  
</div>
<div markdown class="option">
<a id="node" data-level="basic">__-node__</a> (string): get given MPEG4 node syntax and QP infolist  
</div>
<div markdown class="option">
<a id="xnodes" data-level="basic">__-xnodes__</a>: list supported X3D nodes  
</div>
<div markdown class="option">
<a id="xnodex" data-level="basic">__-xnodex__</a>: list supported X3D nodes and print nodes  
</div>
<div markdown class="option">
<a id="xnode" data-level="basic">__-xnode__</a> (string): get given X3D node syntax  
</div>
<div markdown class="option">
<a id="snodes" data-level="basic">__-snodes__</a>: list supported SVG nodes  
</div>
<div markdown class="option">
<a id="languages" data-level="basic">__-languages__</a>: list supported ISO 639 languages  
</div>
<div markdown class="option">
<a id="boxes" data-level="basic">__-boxes__</a>: list all supported ISOBMF boxes and their syntax  
</div>
<div markdown class="option">
<a id="stats" data-level="basic">__-stats__</a>,__-fstat__: print filter session statistics (import/export/encrypt/decrypt/dashing)  
</div>
<div markdown class="option">
<a id="graph" data-level="basic">__-graph__</a>,__-fgraph__: print filter session graph (import/export/encrypt/decrypt/dashing)  
</div>
<div markdown class="option">
<a id="v" data-level="basic">__-v__</a>: verbose mode  
</div>
<div markdown class="option">
<a id="version" data-level="basic">__-version__</a>: get build version  
</div>
<div markdown class="option">
<a id="-" data-level="basic">__--__</a> `INPUT`: escape option if INPUT starts with `-` character  
</div>
General considerations

MP4Box supports encoding and decoding of of BT, XMT, VRML and (partially) X3D formats int MPEG-4 BIFS, and encoding and decoding of XSR and SVG into MPEG-4 LASeR  
Any media track specified through a `MuxInfo` element will be imported in the resulting MP4 file.  
See https://wiki.gpac.io/Howtos/scenecoding/MPEG-4-BIFS-Textual-Format and related pages.
Live Scene Encoder Options

The options shall be specified as `opt_name=opt_val.`  
Options:  
  
<div markdown class="option">
<a id="live" data-level="basic">__-live__</a>: enable live BIFS/LASeR encoder  
</div>
<div markdown class="option">
<a id="dst" data-level="basic">__-dst__</a> (string): destination IP  
</div>
<div markdown class="option">
<a id="port" data-level="basic">__-port__</a> (int, default: __7000__): destination port  
</div>
<div markdown class="option">
<a id="mtu" data-level="basic">__-mtu__</a> (int, default: __1450__): path MTU for RTP packets  
</div>
<div markdown class="option">
<a id="ifce" data-level="basic">__-ifce__</a> (string): IP address of the physical interface to use  
</div>
<div markdown class="option">
<a id="ttl" data-level="basic">__-ttl__</a> (int, default: __1__): time to live for multicast packets  
</div>
<div markdown class="option">
<a id="sdp" data-level="basic">__-sdp__</a> (string, default: __session.sdp__): output SDP file  
</div>
<div markdown class="option">
<a id="dims" data-level="basic">__-dims__</a>: turn on DIMS mode for SVG input  
</div>
<div markdown class="option">
<a id="no-rap" data-level="basic">__-no-rap__</a>: disable RAP sending and carousel generation  
</div>
<div markdown class="option">
<a id="src" data-level="basic">__-src__</a> (string): source of scene updates  
</div>
<div markdown class="option">
<a id="rap" data-level="basic">__-rap__</a> (int): duration in ms of base carousel; you can specify the RAP period of a single ESID (not in DIMS) using `ESID=X:time`  
</div>
    
Runtime options:  

- q: quits  
- u: inputs some commands to be sent  
- U: same as u but signals the updates as critical  
- e: inputs some commands to be sent without being aggregated  
- E: same as e but signals the updates as critical  
- f: forces RAP sending  
- F: forces RAP regeneration and sending  
- p: dumps current scene
SWF Importer Options

MP4Box can import simple Macromedia Flash files (".SWF")  
You can specify a SWF input file with '-bt', '-xmt' and '-mp4' options  
    
Options:  
<div markdown class="option">
<a id="global" data-level="basic">__-global__</a>: all SWF defines are placed in first scene replace rather than when needed  
</div>
<div markdown class="option">
<a id="no-ctrl" data-level="basic">__-no-ctrl__</a>: use a single stream for movie control and dictionary (this will disable ActionScript)  
</div>
<div markdown class="option">
<a id="no-text" data-level="basic">__-no-text__</a>: remove all SWF text  
</div>
<div markdown class="option">
<a id="no-font" data-level="basic">__-no-font__</a>: remove all embedded SWF Fonts (local playback host fonts used)  
</div>
<div markdown class="option">
<a id="no-line" data-level="basic">__-no-line__</a>: remove all lines from SWF shapes  
</div>
<div markdown class="option">
<a id="no-grad" data-level="basic">__-no-grad__</a>: remove all gradients from swf shapes  
</div>
<div markdown class="option">
<a id="quad" data-level="basic">__-quad__</a>: use quadratic bezier curves instead of cubic ones  
</div>
<div markdown class="option">
<a id="xlp" data-level="basic">__-xlp__</a>: support for lines transparency and scalability  
</div>
<div markdown class="option">
<a id="ic2d" data-level="basic">__-ic2d__</a>: use indexed curve 2D hardcoded proto  
</div>
<div markdown class="option">
<a id="same-app" data-level="basic">__-same-app__</a>: appearance nodes are reused  
</div>
<div markdown class="option">
<a id="flatten" data-level="basic">__-flatten__</a> (number): complementary angle below which 2 lines are merged, value `0` means no flattening  
</div>
XML Syntax {: data-level="all"}

```xml
<GPACDRM type="...">
 <DRMInfo >
    ...
 </DRMInfo>
 <CrypTrack  trackID="..." [see possible attributes below] >
  <key KID="..." value="..."/>
  <key KID="..." value="..."/>
 </CrypTrack>
</GPACDRM>
```
GPACDRM Element Semantics

*   `type` : is the default protection scheme type used for all tracks in the source media file. The possible values are (full name or 4 char code):
    *   **ISMA** or **iAEC**: ISMA E&A (ISMACryp) Scheme
    *   **Adobe** or **adkm**: Adobe Scheme
    *   **CENC AES-CTR** or **cenc**: CENC Protection Scheme using AES 128-bit keys in Counter Mode (AES-128 CTR),
    *   **CENC AES-CBC** or **cbc1**: CENC Protection Scheme using AES 128-bit keys in Cipher-block chaining mode (AES-128 CBC),
    *   **CENC AES-CTR Pattern** or **cens**: CENC Protection Scheme using AES 128-bit keys in Counter Mode (AES-128 CTR) using pattern of unencrypted/encrypted bytes,
    *   **CENC AES-CBC Pattern** or **cbcs**: CENC Protection Scheme using AES 128-bit keys in Cipher-block chaining mode (AES-128 CBC) using pattern of unencrypted/encrypted bytes.
    *   **piff**: PIFF Protection Scheme using AES 128-bit keys in Counter Mode (AES-128 CTR); this will force using PIFF specific boxes for storage of CENC information.
    *   **HLS SAES**: HLS Sample-AES Protection Scheme (AES-128 CBC) using pattern of unencrypted/encrypted bytes, 32 bytes clear header for AVC and 16 bytes clear header for AAC, used for SAES with MPEG-2 TS. Constant IV shall be used, and pattern {1 crypt, 9 clear} is always enforced.
DRMInfo Element Semantics

The `DRMInfo` element contains information needed by a Content Protection System to play back the content such as SystemID, the URL of license server(s) or rights issuer(s) used, embedded licenses/rights, embedded keys(s), and/or other protection system specific metadata. It is possible to specify  more than one DRM system by using one DRMInfo element per system ID. 
The children of this element use the binary XML construction of GPAC to build a binary blob representing:

- the CENC PSSH box payload without box size, type, version and no data size field
- or a complete pssh box 

The payload of a DRMInfo describing a PSSH blob can be encrypted using AES-128 CTR mode. In this case, the first byte of PSSH data is the first byte after the SystemID (version 0 of PSSH) or after the list of keys (version 1 of PSSH).

*   `type`: the only defined value is **pssh**, indicating this DRMInfo describes a PSSH blob.
*   `version`: if 0, indicates the payload is a PSSH version 0 (no key IDs given after the 16-bytes SystemID), otherwise a version 1 or more of PSSH.
*   `cypherMode`: indicates the cypher mode of the PSSH blob. Possible values are:
    *   **no** : no encryption (default if no cypher key is given)
    *   **yes** : encrypts all PSSH data in AES-128 CTR mode (default if cypher key is given)
*   `cypherKey`: indicates the cypher key to use (16 bytes). If not present, PSSH data is not encrypted.
*   `cypherIV`: indicates the cypher IV to use (16 bytes). If not present, PSSH data is not encrypted.
*   `cypherOffset`: indicates the offset in PSSH data to start encryption from, 0 if not present. 

The following example shows a simple GPAC DRM system info:
    
### Simple GPAC DRM system info
    
    ```xml
    <!-- example for GPAC 'clear' DRM System - keys are listed after the content and UL follows -->
    <DRMInfo type="pssh" version="1" cypherOffset="9" cypherKey="0x6770616363656E6364726D746F6F6C31" cypherIV="0x00000000000000000000000000000001">
        <!-- this indicates the PSSH SystemID -->
        <BS ID128="6770616363656E6364726D746F6F6C31"/>
        <!-- this indicates the PSSH number of keys (version 1), on 32 bits -->
        <BS value="2" bits="32"/>
        <!-- this gives the two key IDs in the PSSH (version 1) -->
        <BS ID128="0x279926496a7f5d25da69f2b3b2799a7f"/>
        <BS ID128="0x676cb88f302d10227992649885984045"/>
        <!-- the rest describe the remaining of the PSSH blob, the cypherOffset of 9 will keep the first 8 bytes in the clear -->
        <BS bits="8" string="CID=Toto"/>
        <BS ID128="0xccc0f2b3b279926496a7f5d25da692f6"/>
        <BS ID128="0xccc0f2b3b279926496a7f5d25da692d6"/>
    </DRMInfo>
    ```
Key Element Semantics

The `Key` element is used to specify key(s) applying to the parent track. This element must be a child of a `CrypTrack` Element.
The key ID and value must be specified as a 32 bytes hex string, using an improper length will result in an error. At least one key shall be defined. Key selection policy and key rolling are defined by `keyRoll` attribute.
If the KID attribute is not specified, the key will match any KID in the file. Such a key should be placed after all other key declarations.

 The defined attributes are:

*   `KID` : the ID of the key (KID in CENC) to use
*    `value`: the AES-128 bit key corresponding to this KID to use. 
*    `hlsInfo`: the associated info for HLS, must contain at least `URI="..."`  and may also contain other params of EXT-X-KEY, except `METHOD` which is set by GPAC. Multiple key options may be specified using `URI="uri1",KEYFORMAT="identity",URI="uri1",KEYFORMAT="myown"` (the code will look for `,URI` as a separator.
*   `IV_size` : the IV size of the key. If not set, use the one defined at the CryptTrack level.
*   `constant_IV` : constant IV associated with key. If not set, use the one defined at the CryptTrack level.
*   `rep` : ID of DASH representation (decryption only).
*   `period` : ID of DASH period (decryption only).
*   `as` : ID of DASH AdaptationSet (decryption only).


The `rep`, `period` and `as` attributes can be used to differentiate keys with the same KID but with different key values used in different DASH qualities, Adaptation Sets or periods while using a single DRM file.
DRMInfoTemplate Element Semantics

The `DRMInfoTemplate` element describes information for a Content Protection System to be injected at each key change.
This is typically used when `DRMInfo` contains information about a root key, and keys are then delivered inband crypted with this root key.

The children of this element use the binary XML construction of GPAC to build the CENC PSSH payload. 

The payload of a DRMInfoTemplate describing a PSSH blob is not encrypted, however the key value is encrypted using AES-128 in CTR, CBC or ECB mode.

*   `version`: if 0, indicates the payload is a PSSH version 0 (no key IDs given after the 16-bytes SystemID), otherwise a version 1 or more of PSSH. Default value is 1.
*   `system`: indicates the systemID, as written in pssh (16 bytes). It must be provided.
*   `key`: indicates the cypher key to use (16 bytes). It must be provided.
*    `mode`: indicate cypher mode, either `cbc` (default) , `ctr` or `ecb`
*   `IV`: indicates the cypher IV to use (16 bytes) for `cbc` or  `ctr` encryption, set to 0 if not present.

There can be multiple `DRMInfoTemplate`, typically one per system ID.

When a new key is activated, each `DRMInfoTemplate` will be serialized with the following templating:

-  in the first child `<BS>` element with an attribute `ID128` set to `KEY`, attribute value is replaced with the encrypted value of the new key (encrypted with `DRMInfoTemplate@key`)
-  in the first child `<BS>` element with an attribute `ID128` set to `KID`, attribute value is replaced with the new key ID (usually not needed if using pssh version 1)

The following example shows a simple DRMInfoTemplate info:
    
```xml
<DRMInfoTemplate version="1" system="6770616363656E6364726D746F6F6C31" KEY="0x5344694d47473326622665665a396b30">
<BS ID128="KEY"/>
</DRMInfoTemplate>
```

This will generate a PSSH blob version 1 (including the new KID) with the new key value as payload of PSSH.

You can customize the payload with other `<BS>` elements.

__WARNING Non-fragmented files produced with this approach are not CENC-compatible as multiple PSSHs varying over time cannot be represented in CENC at the current time.
GPAC uses a sample group of type `PSSH` to store this info, each entry being the concatenation of box content of all active PSSHs (cf `CENC_PSSH` [property](filters_properties) ).__

_Note: templating is only supported for single key mode, multi-keys per sample cannot use templating at the current time._
Encrypting/Decrypting a MP4 file with GPAC

The command line is as follows:

```
MP4Box -crypt drm_file.xml movie.mp4 -out movie_encrypted.mp4
MP4Box -decrypt drm_file.xml movie_encrypted.mp4 -out movie_decrypted.mp4
```

The following example shows an example file `drm_file_gpac_clear.xml` for encrypting all samples in a track, using only one key, and with GPAC 'clear' DRM System:
drm\_file\_gpac\_clear.xml

```xml
<?xml version="1.0" encoding="UTF-8"?>
<GPACDRM type="CENC AES-CTR">
<!-- example for GPAC 'clear' DRM System - keys are listed after the content and UL follows -->
    <DRMInfo type="pssh" version="1" cypherOffset="9" cypherKey="0x6770616363656E6364726D746F6F6C31" cypherIV="0x00000000000000000000000000000001">
        <BS ID128="6770616363656E6364726D746F6F6C31"/>
        <BS value="2" bits="32"/>
        <BS ID128="0x279926496a7f5d25da69f2b3b2799a7f"/>
        <BS ID128="0x676cb88f302d10227992649885984045"/>
        <BS bits="8" string="CID=Toto"/>
        <BS ID128="0xccc0f2b3b279926496a7f5d25da692f6"/>
        <BS ID128="0xccc0f2b3b279926496a7f5d25da692d6"/>
    </DRMInfo>
    <CrypTrack trackID="1" IsEncrypted="1" IV_size="16" first_IV="0x0a610676cb88f302d10ac8bc66e039ed" saiSavedBox="senc">
        <key KID="0x279926496a7f5d25da69f2b3b2799a7f" value="0xccc0f2b3b279926496a7f5d25da692f6"/>
        <key KID="0x676cb88f302d10227992649885984045" value="0xccc0f2b3b279926496a7f5d25da692d6"/>
    </CrypTrack>
</GPACDRM>
```

In the above XML, the `BS` element from NHML syntax is used to describe what needs to be written in the PSSH box. In this example, the PSSH block contains:

*   128 bit system ID
*   key IDs count (2) on 32 bits
*   two key IDs on 128 bits each
*   8 byte string prefixed with a length size on 8 bits
*   two keys on 128 bits each

For more information on what is supported by the `BS` element, check the [[NHML documentation|NHML Format]]. 

Another example `drm_file_2_drms.xml` shows how to use 2 DRM Systems:
drm\_file\_2\_drms.xml

```xml
<?xml version="1.0" encoding="UTF-8"?>
<GPACDRM type="CENC AES-CTR">
<!-- PlayReady - data contains the cyphered key & co -->
    <DRMInfo type="pssh" version="0">
        <BS ID128="9A04F07998404286AB92E65BE0885F95"/> <!-- SystemID -->
        <BS data="application/data;base64:ACE125"/> <!-- binary blob, could also use dataFile="cenc_blob.bin" -->
    </DRMInfo>
    <!-- GPAC 'clear' DRM System - keys are listed after the content and UL follows -->
    <DRMInfo type="pssh" version="1" cypherOffset="9" cypherKey="0x6770616363656E6364726D746F6F6C31" cypherIV="0x00000000000000000000000000000001">
        <BS ID128="6770616363656E6364726D746F6F6C31"/>
        <BS value="2" bits="32"/>
        <BS ID128="0x279926496a7f5d25da69f2b3b2799a7f"/>
        <BS ID128="0x676cb88f302d10227992649885984045"/>
        <BS bits="8" string="CID=Toto"/>
        <BS ID128="0xccc0f2b3b279926496a7f5d25da692f6"/>
        <BS ID128="0xccc0f2b3b279926496a7f5d25da692d6"/>
    </DRMInfo>
    <CrypTrack trackID="1" IsEncrypted="1" IV_size="16" first_IV="0x0a610676cb88f302d10ac8bc66e039ed" saiSavedBox="senc">
        <key KID="0x279926496a7f5d25da69f2b3b2799a7f" value="0xccc0f2b3b279926496a7f5d25da692f6"/>
        <key KID="0x676cb88f302d10227992649885984045" value="0xccc0f2b3b279926496a7f5d25da692d6"/>
    </CrypTrack>
</GPACDRM>
```

In the above XML, there are 2 PSSH blocks. For a non-GPAC DRM block, the opaque DRM specific data can be generated using the BS syntax or read from a data attribute or from a file indicated in dataFile attribute. Another example `drm_file_rap.xml` shows an advanced case: we will encrypt only the RAP and we use also key rolling policy.
drm\_file\_rap.xml

```xml
<?xml version="1.0" encoding="UTF-8"?>
<GPACDRM type="CENC AES-CTR">
    <DRMInfo type="pssh" version="1" cypherOffset="9" cypherKey="0x6770616363656E6364726D746F6F6C31" cypherIV="0x00000000000000000000000000000001">
        <BS ID128="6770616363656E6364726D746F6F6C31"/>
        <BS value="4" bits="32"/>
        <BS ID128="0x279926496a7f5d25da69f2b3b2799a7f"/>
        <BS ID128="0x597669572e55547e656b56586e2f6f68"/>
        <BS ID128="0x205b2b293a342f3d3268293e6f6f4e29"/>
        <BS ID128="0x32783e367c2e4d4d6b46467b3e6b5478"/>
        <BS bits="8" string="CID=Toto"/>>
        <BS ID128="0x5544694d47473326622665665a396b36"/>
        <BS ID128="0x7959493a764556786527517849756635"/>
        <BS ID128="0x3a4f3674376d6c48675a273464447b40"/>
        <BS ID128="0x3e213f6d45584f51713d534f4b417855"/>
    </DRMInfo>
    <CrypTrack trackID="1" IsEncrypted="1" IV_size="16" first_IV="0x0a610676cb88f302d10ac8bc66e039ed" selectiveType="RAP" saiSavedBox="senc" keyRoll="roll=5">
        <key KID="0x279926496a7f5d25da69f2b3b2799a7f" value="0x5544694d47473326622665665a396b36"/>
        <key KID="0x597669572e55547e656b56586e2f6f68" value="0x7959493a764556786527517849756635"/>
        <key KID="0x205b2b293a342f3d3268293e6f6f4e29" value="0x3a4f3674376d6c48675a273464447b40"/>
        <key KID="0x32783e367c2e4d4d6b46467b3e6b5478" value="0x3e213f6d45584f51713d534f4b417855"/>
    </CrypTrack>
</GPACDRM>
```
drm\_file.xml

```xml
<?xml version="1.0" encoding="UTF-8"?>
<GPACDRM type="ADOBE">
    <CrypTrack trackID="1" IsEncrypted="1" first_IV="0x0a610676cb88f302d10ac8bc66e039ed" selectiveType="RAP" metadata="url=toto" metadata_len="8">
        <key value="0x5544694d47473326622665665a396b36"/>
    </CrypTrack>
</GPACDRM>
```

In this example, `metadata` is a string used by the DRM client to retrieve decryption key
GPAC DRM format

GPAC Player can play protected files which use the GPAC SystemID. This system is mostly used for test purposes, as keys are carried encrypted with a fixed, public _system_ key.

The SystemID and _system_ key are _0x6770616363656E6364726D746F6F6C31_.

The PSSH version is used as follows:

- version 0 (no KID) indicates that inband keys are used (key rolling)
- version 1 identifies regular keys.

_Note: a version 1 with a single KID set to GPAC SystemID is equivalent to a version 0._

The specific DRM info (following KIDs + 32 bits private_data_len) is structured as:

- 8 bit field indicating a length `N` followed by `N` bytes of clear data `D`. This may be omitted.
  - if the first 6 bytes of `D` equal `master`, this indicates a master key - only the first KID/KEY value is used
  - if the first 4 bytes of `D` equal `leaf`, this indicates a leaf key - only the first KID/KEY value is used
  - if `N=0` or field is absent, this indicates a leaf key if a master key is in place, or regular keys otherwise. If inband keys are used or key is a leaf key, only the first KID/KEY value is used.

- encrypted keys (nbKIDs * 16 bytes)
	- a leaf key is encrypted in CBC using master key
	- an inband key is encrypted in CBC using _system_ key
	- all other keys are encrypted in CTR mode with an IV value of 1

- the remainder of the data is ignored
NHML Overview

The `NHML`  (Network Hint Markup Language) format has been developed at Telecom Paris in order to provide import support on media formats not natively supported by GPAC, typically for ISOBMFF file constructions. It is an XML translation and extension of a binary format called [[NHNT Format]] used during the development of MPEG-4 Systems.

The NHML format is an XML-based description of a single media stream, allowing to specify media stream properties and media samples in GPAC.

To obtain some sample NHML files, simply use `MP4Box -nhml trackID srcFile`

Just like any XML file, the file must begin with the usual xml header. The file encoding SHALL BE UTF-8.

The root element of an NHML file is the `NHNTStream` element, containing zero or one `DecoderSpecificInfo` element and zero or more `NHNTSample` elements.

The `NHNTStream`, `NHNTSample`,`SAI` and `P` elements may use child [bitstream constructors](XML-Binary), allow assembling bytes and files as needed to construct the desired data.