gaspard7/wiki_gpac huggingface dataset:
NHML Syntax

The following shows the different elements defined in NHML.
```
<?xml version="1.0" encoding="UTF-8" ?>
<NHNTStream  ... >
 <!-- decoder config from XML binary -->
 <DecoderSpecificInfo>
	<BS/>
 </DecoderSpecificInfo>

 <!-- regular sample -->
 <NHNTSample ... />    

 <!-- sample building its data from XML binary -->
 <NHNTSample ... >
  <BS  ... />
 </NHNTSample>
 
 <!-- sample with subsample definitions -->
 <NHNTSample ...>
 	<SubSamples>
		<SubSample ... />
		<SubSample ... />
	</SubSamples>
 </NHNTSample>

 <!-- sample using XML binary with subsample definitions-->
 <NHNTSample ...>
   <BS dataFile="file1"/>
   <BS dataFile="file2"/>
   <BS value="30" bits="16"/>
   <SubSamples>
	<SubSample sfile="file1" />
	<SubSample size="2" sfile="file2" />
   </SubSamples>
 </NHNTSample>

 <!-- sample with auxiliary info definitions using XML binary -->
 <NHNTSample ...>
  <SAI type="fooX">
   <BS value="0" bits="8"/>
  </SAI>
 </NHNTSample>

 <!-- stream reconfiguration -->
 <NHNTReconfig />

 <!-- sample with sample group description using XML binary -->
 <NHNTSample ...>
  <SAI id="g2" group="true" type="barZ">
   <BS value="0" bits="8"/>
  </SAI>
 </NHNTSample>

 <!-- sample with sample group description reference -->
 <NHNTSample ...>
  <SAI ref="g2"/>
 </NHNTSample>

 <!-- sample using XML binary -->
 <NHNTSample ...>
   <BS value="0" bits="8"/>
   <BS value="2" bits="32"/>
 </NHNTSample>

 <!-- sample with sample group description and using XML binary construction -->
 <NHNTSample ...>
  <Media>
   <BS value="24" bits="32"/>
  </Media>  
  <SAI group="true" type="barZ">
   <BS value="3" bits="8"/>
  </SAI>
 </NHNTSample>

</NHNTStream>
```
SubSamples

### Overview

The `SubSamples` element is used to give subsample information for the parent sample.

A `SubSamples` element contains one or more `SubSample` element.

__WARNING Only the first `SubSamples` element in an `NHNTSample` is parsed at the current time.__

__WARNING Support for `SubSamples` requires GPAC 2.0 or above.__

### Defined Attributes for `SubSamples` element
*   `flags` : flags for the subsample box, default is 0

### Defined Attributes for `SubSample` element
*   `size` : size in bytes of the subsample, 0 by default
*   `fsize` : add to `size` the size of the file indicated by this attribute, default is NULL
*   `textmode` : if `fsize` is set, open the file in text mode if this attribute is set to `yes`, `true` or `1` , default is `no`
*   `discardable` : indicates if the subsample data is discardable (value `yes`, `true` or `1`), default is `no`
*   `priority` : indicates the subsample data priority , default is 0
*   `codec_info` : indicates the codec specific parameters (default is 0) for the subsample, as unsigned int or as hexadecimal data (prefixed with `0x`)
Sample Auxiliary Information

### Definition

The `SAI` element is used to associate auxiliary information to the parent sample. The children of this element must use [bitstream constructors](XML-Binary) to describe the data.

Auxiliary information will be tanslated by the ISOBMFF multiplexer as:

- sample group description with `grouping_type` value of `type` if `group` is set
- sample auxiliary information with  `aux_info_type` value of `type` if `group` is not set

An `SAI` element can be a reference to another `SAI` element, in which case the data is generated from the reference element. This avoids repeating the structure when reused (sample groups).

Several `SAI` can be specified for different auxiliary types.

__WARNING Support for `SAI` requires GPAC 2.0 or above.__

### Defined Attributes

*   `id` : string assigning ID to this SAI for later reuse
*   `ref` : string indicating a defined SAI to use. The first SAI found (starting from first defined sample) with matching ID will be used
*   `group` : boolean. If set to `yes`, `true` or `1`, indicates that this auxiliary info must be signaled as sample grouping in ISOBMFF, otherwise auxiliary sample info is used
*   `type` : 4CC of the auxiliary data or of the sample group
*   `aux_info` : 32bit integer for the auxiliary data (`aux_info_type_parameter`in ISOBMFF) or for the sample grouping (`grouping_type_parameter` in ISOBMFF)

### Example

```
<NHNTSample>
	<SAI type="fooZ" aux_info="0" group="1">
		<BS value="0" bits="8"/>
	</SAI>
</NHNTSample>
```
This defines a sample grouping with type `GPAC` and a value of '0' on 8 bits.

```
<NHNTSample>
	<SAI type="barZ" aux_info="0">
		<BS value="1" bits="8"/>
	</SAI>
</NHNTSample>
```
This defines a sample auxiliary data with type `GPAC` and a value of '1' on 8 bits.
Properties

The `Properties` element can be used to set packet or PID properties as used in GPAC filters.
The element is a list of `P` elements. Each `P` element can be a regular property (built-in or user defined), or can use  [bitstream constructors](XML-Binary) to construct the property data.

For `NHNTStream` element, the first `Properties` child element declared before the first `NHNTSample` element is used, if any.
For `NHNTSample` element, the first `Properties` child element  is used, if any.

__WARNING Support for `Properties` requires GPAC 2.0 or above.__

### Defined Attributes for Properties

* `id`: assigns an ID of the element 
* `ref`: uses the first `Properties` element with given ID found in the document.

### Defined Attributes for P
* `type`: property type. For non built-in properties, defaults to string or to data if bitstream constructors are used. Ignored for built-in properties.
* `name`: property name
* `value`: property value
* `id`: assigns an ID of the element 
* `ref`: uses the first `P` element with given ID found in the document.

If `name` attribute is not set, the first non-recognized attribute name is the property name and its value the property value.

### Examples
```
<Properties>
	<P name="foo" value="32" type="uint"/>
	<P myProp="Toto">
		<BS value="3" bits="8"/>
	</P>
</Properties>
```
NHNTReconfig

### Overview
The `NHNTReconfig` element reconfigures the media stream properties between samples. It may happen as often as desired, and has exactly the same syntax as the `NHNTStream` element. 

If a `DecoderSpecificInfo` element is needed, it must be set as a child of the  `NHNTReconfig` element.

```
<NHNTReconfig ...>
	<DecoderSpecificInfo>
		<BS .../>
	</DecoderSpecificInfo>
</NHNTReconfig>
```

If  `Properties`element is needed, it must be set as a child of the  `NHNTReconfig` element.

```
<NHNTReconfig ...>
	<Properties>
		<P .../>
	</Properties>
</NHNTReconfig>
```

__WARNING Support for `NHNTReconfig` requires GPAC 2.0 or above.__
OMA DRM authoring {: data-level="all"}

In order to encrypt a 3GP/MP4 file into a PDCF file, MP4Box uses the same process as CENC or ISMA encryption, only the drm file syntax changes.

This page documents OMA-specific options of the DRM file, see [Common Encryption](Common-Encryption) for more details on generic options.

An `CryptTrack` element may have children describing the optional textual headers defined in OMA DRM 2.0. Each textual header is inserted as is during OMA encryption, so be careful not to specify twice the same header. More information on textual headers can be found in the [OMA (P)DCF specification](https://www.openmobilealliance.org/release/DRM/V2_1_2-20110531-A/OMA-TS-DRM_DCF-V2_1-20081014-A.pdf).
CrypTrack OMA-specific Semantics

*   `trackID` : specifies the track ID to encrypt (mandatory, see [Common Encryption](Common-Encryption) ).
*   `key` : the AES-128 bit key to use. The key must be specified as an 32 bytes hex string, like **0x2b7e151628aed2a6abf7158809cf4f3c**. This is a mandatory field, not specifying it or using an improper length will result in an error.
*   `rightsIssuerURL` : the URL of the OMA DRM licence server. This is the URL to which an OMA client will request the keys using the ROAP protocol.
*   `contentID` : a string identifier for the content, passed during ROAP exchanges.
*   `transactionID` : a string identifier for the transaction, passed during ROAP exchanges.
*   `selectiveType` : specifies how selective encryption is to be used, see [Common Encryption](Common-Encryption) for more details.
Sample GPAC OMA drm files

The following example shows how to encrypt a file with one track, without selective encryption, using OMA DRM.

```xml
<?xml version="1.0" encoding="UTF-8" >
<OMADRM>
    <OMATrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" selectiveType="None" rightsIssuerURL="https://gpac.sourceforge.net/kms" contentID="WatchMe1984" transactionID="14fd12zd3q" >
        <OMATextHeader>Preview=instant;http://other.content.com/sonaive</OMATextHeader>
    </OMATrack>
</OMADRM>
```
ISMACryp authoring {: data-level="all"}

In order to encrypt an MP4 file, MP4Box will need a specific file containing all cryptographic information, usually referred to as `drm_file` in MP4Box documentation. The command line is as follows:

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

The DRM file is an XML document containing mainly key information, KMS information, encryption instructions and eventually MPEG-4 IPMP(X) indications. This page documents ISMA-specific options of the DRM file, see [Common Encryption](Common-Encryption) for more details on generic options.
CrypTrack Semantics for ISMA

*   `trackID` : specifies the track ID to encrypt (mandatory, see [Common Encryption](Common-Encryption) ).
*   `key` : the AES-128 bit key to use. The key must be specified as an 32 bytes hex string, like **0x2b7e151628aed2a6abf7158809cf4f3c**. This is a mandatory field, not specifying it or using an improper length will result in an error.
*   `salt` : the 64 bit salt key to use for the counter mode. The salting key must be specified as an 16 bytes hex string, like **0xf8f9fafbfcfdfeff**. This is a mandatory field, not specifying it or using an improper length will result in an error.
*   `scheme_URI` : the URI of the scheme used for protection (for example the cryptographic tool provider). The default value is **urn:gpac:isma:encryption\_scheme**. This URI is added to the track meta-data.
*   `kms_URI` : the URI of the key management system. This is the URI to which an ISMACryp client will request the keys. This URI is added to the track meta-data. Apart from regular URLs and URIs, two specific values are interpreted by GPAC:
    *   **self** : the keys will be written in the media track meta-data using base64 encoding. This is mainly useful for testing :)
    *   **file** : the URI will be set to this drm\_file name as given to MP4Box - in other words, if you indicate a relative path for the drm\_file, then the relative path will be used for the KMS URI.
*   `selectiveType` : specifies how selective encryption is to be used. See [Common Encryption](Common-Encryption) for more details
*   `ipmpType` : specifies what kind of MPEG-4 IPMP signaling must be used for this media. The possible values are:
    *   **None** : no MPEG-4 IPMP signaling.
    *   **IPMP** : use MPEG-4 IPMP (`the hooks`) signaling.
    *   **IPMPX** : use MPEG-4 IPMP-X (`ISO-IEC 14496-13` signaling.
*   `ipmpDescriptorID` : specifies the IPMP(X) descriptor ID for this media. If not set, **defaults to the media track 1-based index**. Ignored when IPMP(X) signaling is not used.
Sample GPAC ISMA drm files

The following example shows how to encrypt a file with one track, using selective encryption of RAP samples, embedded keys and no IPMP signaling.

```xml
<?xml version="1.0" encoding="UTF-8" >
<GPACDRM type="ISMA">
	<CrypTrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" salt="0xf8f9fafbfcfdfeff" selectiveType="RAP" KMS_URI="self"/>
</GPACDRM>
```

The following example shows how to encrypt a file with one track, using random encryption over 30 samples, using the source file as KMS URI and IPMP-X signaling.

```xml
<?xml version="1.0" encoding="UTF-8" >
<GPACDRM type="ISMA">
	<CrypTrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" salt="0xf8f9fafbfcfdfeff" selectiveType="Rand30" KMS_URI="file" ipmpType="IPMPX" ipmpDescriptorID="20" />
</GPACDRM>
```

The following example shows how to encrypt a file with one track, without selective encryption, a KMS URI and no IPMP signaling.

```xml
<?xml version="1.0" encoding="UTF-8" >
<GPACDRM type="ISMA">
	<CrypTrack trackID="1" key="0x2b7e151628aed2a6abf7158809cf4f3c" salt="0xf8f9fafbfcfdfeff" selectiveType="None" KMS_URI="https://gpac.sourceforge.net/kms/file.xml" />
</GPACDRM>
```
Decrypting a file with GPAC

MP4Box/GPAC players will attempt to load the keys from a KMS URI as follows:

*   if kms\_URI begins with **(key)**, the keys are Base64 encoded in the track and can be fetched. This corresponds to the case of special value `kms_URI="self"` when encrypting.
*   if the scheme URI is GPAC default one (**urn:gpac:isma:encryption\_scheme**) and the kms\_URI points to a file (ONLY LOCAL FILES FOR MP4BOX), the key and salt will be fetched from this file. This corresponds to the case of special value `kms_URI="file"` when encrypting. In this case only the `trackID`, `key` and `salt` attributes of the **ISMACrypTrack**element are needed.
*   if kms\_URI is `AudioKey` or `VideoKey`, KMS is assumed to be MPEG4IP one and the file ~/.kms\_data is checked (cf [MPEG4IP](https://sourceforge.net/projects/mpeg4ip/) documentation).

In all other cases:

*   For MP4Box: You will need to provide a drm\_file for decryption (e.g. `MP4Box -decrypt drm_file myfile.mp4`).
*   For GPAC client: key fetching will fail and the stream will be decoded WITHOUT being decrypted.
NHNT Overview {: data-level="all"}

The NHNT format has been developed during the MPEG-4 Systems implementation phase, as a way to easily mux unknown media formats to an MP4 file or an MPEG-4 multiplex. The goal was to have the media encoder produce a description of the media time fragmentation (access units and timestamps) that could be reused by a media-unaware MPEG-4 multiplexer.

A NHNT source is composed of 2 or 3 parts:

*   **the media file**: This file contains all the media data as written by the encoder. The file extension must be `.media`.
*   **the NHNT (meta) file**: This file contains all the information needed by the MPEG-4 multiplexer to use the media data. The file extension must be `.nhnt`.
*   **the decoder initialization file**: If the media format requires decoder configuration data (MPEG-4 Visual, AAC, AVC/H264, ...), the binary data is put in this third file in order for the MPEG-4 multiplexer to correctly signal decoder configuration. This is required by the fact that in MPEG-4 Systems, configuration data is never sent in-band of the media stream, but through the object descriptor stream. The file extension must be `.info`.
Foreword {: data-level="all"}

The 3GPP consortium has defined a standard for text streaming, independent of any scene description such as SMIL, SVG or BIFS: 3GPP Timed Text. MP4Box supports this standard and uses its own textual format to describe a streaming text session.

As of version 0.2.3, GPAC supports 3GPP timed text, also known as MPEG-4 Streaming Text. These standards provide a way to stream text and styles applying to text such as font size, color, highlighting. This is a very convenient way to encode subtitles, tickers, etc,... independently of the scene description language (MPEG-4, X3D, SVG/SMIL, ...).

For regular MPEG-4/VRML static text, please refer to the MPEG-4 tutorial or any VRML tutorials available on the internet.
Overview of a timed text stream

The 3GPP timed text specification is called [3GPP TS 26.245](http://www.3gpp.org/ftp/Specs/archive/26_series/26.245/26245-600.zip) (3GPP web site) and will give you in-depth knowledge of this format. If you don't want to read and understand all the technical details, there are some important things to know about timed text streams, so let's review them.

A text stream can be divided in two major sections, very much like most modern audio/video codecs: the configuration data for the decoder and the data samples. As you can guess, this is quite different from most subtitling formats, where subtitles configuration is left up to the player (color, font size, positioning, etc..). 

Authoring 3GPP text streams therefore requires careful design as to which font size shall be picked, color used and similar. The terminal may not changed these settings as these have been chosen by the author, in other words the text stream becomes an element of the final content just like video or audio tracks (think of it as DVD subtitles whose styles and position are part of the DVD and cannot be changed by the DVD player).
Positioning

Just like any video or image media, a text stream has size information, usually called `Text Track` size. This size defines the maximum width and height used by the text stream. All text will be drawn within this defined rectangle which will also act as a clipper (i.e., nothing will appear outside it). 

This rectangle can be positioned in the final display through horizontal and vertical offsets, allowing for instance to define a text track of 320\*50 pixels at the bottom of a 320\*240 video.
Default Styles

Samples in a text stream usually use the default properties defined in the decoder configuration. Since some styles may be used quite often in a text stream (for example, italic), the decoder configuration data contains a list of default styles, and samples then refer to a specific style in this list. This is known as the `TextSampleEntry` in 3GPP. 

A single `TextSampleEntry` contains:

*   A list of **font names** ("Times", "Arial", etc) with an associated ID - fonts are ALWAYS referenced by IDs in a 3GPP text stream. A compliant decoder shall be able to understand the default font names "Serif", "Sans-serif" and "Monospace".
*   **Text Styles:** default font ID, font size, font styles (italic, bold, underlined), text color in RGBA colorspace.
*   **Text Position:** in a 3GPP text stream, the text may be drawn in a given rectangle within the stream main display rectangle. This is known as the `TextBox` in 3GPP. Any text justification is always performed against this TextBox, not against the main display rectangle.
*   **Other styles:** background color in RGBA colorspace, horizontal and vertical justification, text scrolling modes, etc..
Text Samples

Text samples convey text data and, optionally, temporary styles to apply to this text. The text data can be encoded in UTF-8 or UTF-16, and may be empty (typically used for subtitles). The temporary styles are known as `TextModifiers` in 3GPP, and are of two kinds: those impacting the entire text, and those impacting only a sub-string of the text, identified through starting and ending characters.

### Sub-String Text Modifiers

*   **Styles:** overrides text style (font name, size and style, text color) for a substring of the text. All text characters not covered by temporary modifiers use the default text style from the decoder configuration.
*   **Highlight:** specifies a given substring shall be highlighted.
*   **Hyper Text:** specifies a given substring shall be treated as an hyper-link, and gives associated URL.
*   **Blinking:** specifies a given substring shall blink - blinking frequency is left up to the decoder.
*   **Karaoke:** specifies how highlighting shall be dynamically applied to text characters for a karaoke style.

### Complete String Text Modifiers

*   **Text Box:** specifies a temporary box where this text sample is displayed.
*   **Highlight Color:** specifies the highlight color when highlighting is used. When no highlighting color is given the decoder should use reverse video.
*   **Wrap:** specifies text wrapping shall be done on the text string if needed.
*   **Scroll Delay:** specifies the amount of time a text shall be presented statically to the user during a scroll.
GPAC TTXT Format

There is no official textual representation of a text stream. Moreover, the specification relies on IsoMedia knowledge for most structure descriptions. 

In order to help authoring text streams, an XML format has been developed in GPAC, called **TTXT** for timed-text - the extension used being`.ttxt`. 

This format is not related in any way to any scene description language to keep the timed text authoring a standalone step in the authoring process.
Obtaining a sample TTXT file

As said above, this format has been developed in GPAC, and you will likely not find any tool other than MP4Box supporting this format for quite some time. To get a sample file, you have two possibilities:

*   Find a 3GP file with a text track, and run `MP4Box -ttxt trackID file.3gp`. This will dump the text track in TTXT format.
*   Find an SRT or SUB subtitle file, and run `MP4Box -ttxt file.srt`. This will convert the subtitles in TTXT format.
Syntax of a TTXT file

The TTXT format is an XML description of the timed text stream, and as such MUST begin with the usual XML header with encoding hints - only UTF-8 has currently been tested. 

The text stream is encapsulated in a single element at the root of the document, called `TextStream`. This element has a single defined attribute `version` identifying the format version - the current and only defined version is "`1.0`". 

The TextStream element must have one and only one `TextStreamHeader` child and has as many `TextSample` children as desired. 

_Note:_ All coordinates are specified in pixels, framebuffer-coordinate like:

*   X-axis increases from left to right, with origin (0) on left edge.
*   Y-axis increases from top to bottom, with origin (0) on top edge.
TextStreamHeader

The TextStreamHeader describes all 3GPP text stream decoder configuration. It must contain at least one TextSampleDescription element.

### Syntax

```xml
<TextStreamHeader width="..." height="..." translation_x="..." translation_y="..." layer="..." />
    ...
</TextStreamHeader>
```

### Semantics

*   `width` : defines text stream width in pixels (type: unsigned integer). Default value is 400 pixels.
*   `height` : defines text stream height in pixels (type: unsigned integer). Default value is 80 pixels.
*   `translation_x` : defines text stream horizontal translation in main display in pixels (type: signed integer). Default value is 0 pixels.
*   `translation_y` : defines text stream vertical translation in main display in pixels (type: signed integer). Default value is 0 pixels.
*   `layer` : defines text stream z-order (type: signed short). This is only needed when composing several text streams in a single presentation: more negative layer values are towards the viewer. Default value is 0.