Merge pull request #287 from cellar-wg/block_addition_mapping

add BlockAdditionMapping to describe each BlockAdditional data
ietf-wg-cellar · Oct 22, 2019 · 87ffd39 · 87ffd39
2 parents 2eed48f + dc368ae
commit 87ffd39
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 3 deletions.
diff --git a/Makefile b/Makefile
@@ -24,7 +24,7 @@ ebml_matroska_elements4rfc.md: transforms/ebml_schema2markdown4rfc.xsl matroska_
 $(OUTPUT_MATROSKA).md: index_matroska.md diagram.md matroska_schema_section_header.md ebml_matroska_elements4rfc.md ordering.md chapters.md attachments.md cues.md streaming.md menu.md notes.md
 	cat $^ | grep -v '^---' > $@
 
-$(OUTPUT_CODEC).md: index_codec.md codec_specs.md subtitles.md
+$(OUTPUT_CODEC).md: index_codec.md codec_specs.md subtitles.md block_additional_mappings_intro.md block_additional_mappings/*.md
 	cat $^ > $@
 
 $(OUTPUT_TAGS).md: index_tags.md tagging.md matroska_tagging_registry.md tagging_end.md

diff --git a/block_additional_mappings_intro.md b/block_additional_mappings_intro.md
@@ -0,0 +1,50 @@
+# Block Additional Mapping
+
+Extra data or metadata can be added to each `Block` using `BlockAdditional` data. Each `BlockAdditional` contains a `BlockAddID` that identifies the kind of data it contains.
+When the `BlockAddID` is set to `1` the contents of the `BlockAdditional Element` are define by the Codec Mappings defines (see (#codec-blockadditions)).
+When the `BlockAddID` is set a value greater than `1`, then the contents of the `BlockAdditional Element` are defined by the `BlockAdditionalMapping Element` within the associated `Track Element` where the `BlockAddID Element` of `BlockAdditional Element` equals the `BlockAddIDValue` of the associated Track's `BlockAdditionalMapping Element`. That `BlockAdditionalMapping Element` then identifies a particular Block Additional Mapping by the `BlockAddIDType`.
+
+The following XML depicts a use of a Block Additional Mapping to associate a timecode value with a `Block`:
+
+```xml
+<Segment>
+  <!--Mandatory elements ommitted for readability-->
+  <Tracks>
+    <TrackEntry>
+      <TrackNumber>1</TrackNumber>
+      <TrackUID>568001708</TrackUID>
+      <TrackType>1</TrackType>
+      <BlockAdditionalMapping>
+        <BlockAddIDValue>2</BlockAddIDValue><!--arbitrary value
+          used in BlockAddID-->
+        <BlockAddIDName>timecode</BlockAddIDName>
+        <BlockAddIDType>12</BlockAddIDType>
+      </BlockAdditionalMapping>
+      <CodecID>V_FFV1</CodecID>
+      <Video>
+        <PixelWidth>1920</PixelWidth>
+        <PixelHeight>1080</PixelHeight>
+      </Video>
+    </TrackEntry>
+  </Tracks>
+  <Cluster>
+    <Timestamp>3000</Timestamp>
+    <BlockGroup>
+      <Block>{binary video frame}</Block>
+      <BlockAdditions>
+        <BlockMore>
+          <BlockAddID>2</BlockAddID><!--arbitrary value from
+            BlockAdditionalMapping-->
+          <BlockAdditional>01:00:00:00</BlockAdditional>
+        </BlockMore>
+      </BlockAdditions>
+    </BlockGroup>
+  </Cluster>
+</Segment>
+```
+
+Block Additional Mappings detail how additional data MAY be stored in the `BlockMore Element` with a `BlockAdditionMapping Element` within the `Track Element` which identifies the `BlockAdditional` content.
+Block Additional Mappings define the `BlockAddIDType` value reserved to identify that type of data as well as providing an optional label stored within the `BlockAddIDName Element`.
+When the Block Additional Mapping is dependent on additional contextual information then the Mapping SHOULD describe how such additional contextual information is stored within the `BlockAddIDExtraData Element`.
+
+The following Block Additional Mappings are defined.
diff --git a/codec_specs.md b/codec_specs.md
@@ -46,6 +46,32 @@ An optional description for the encoding. This value is only intended for human
 
 Each encoding supported for storage in Matroska MUST have a defined Initialization. The Initialization MUST describe the storage of data necessary to initialize the decoder, which MUST be stored within the `CodecPrivate Element`. When the Initialization is updated within a track then that updated Initialization data MUST be written into the `CodecState Element` of the first `Cluster` to require it. If the encoding does not require any form of Initialization then `none` MUST be used to define the Initialization and the `CodecPrivate Element` SHOULD NOT be written and MUST be ignored. Data that is defined Initialization to be stored in the `CodecPrivate Element` is known as `Private Data`.
 
+### Codec BlockAdditions
+
+Additional data that contextualizes or supplements a `Block` can be stored within the `BlockAdditional Element` of a `BlockMore Element`. This `BlockAdditional` data MAY be passed to the associated decoder along with the content of the `Block Element`. Each `BlockAdditional` is coupled with a `BlockAddID` that identifies the kind of data it contains. The following table defines the meanings of `BlockAddID` values.
+
+BlockAddID Value | Definition
+-----------------|:---------------
+0                | Invalid.
+1                | Indicates that the context of the `BlockAdditional` data is defined by the corresponding `Codec Mapping`.
+2 or greater     | `BlockAddID` values of 2 and greater are mapped to the `BlockAddIDValue` of the `BlockAdditionMapping` of the associated Track.
+
+The values of `BlockAddID` that are 2 of greater have no semantic meaning, but simply associate the `BlockMore Element` with a `BlockAdditionMapping` of the associated Track. See [the section on Block Additional Mappings](#block-additional-mapping) for more information.
+
+The following XML depicts the nested Elements of a `BlockGroup Element` with an example of BlockAdditions:
+
+```xml
+<BlockGroup>
+  <Block>{Binary data of a VP9 video frame in YUV}</Block>
+  <BlockAdditions>
+    <BlockMore>
+      <BlockAddID>1</BlockAddID>
+      <BlockAdditional>{alpha channel encoding to supplement the VP9 frame}</BlockAdditional>
+    </BlockMore>
+  </BlockAdditions>
+</BlockGroup>
+```
+
 ### Citation
 
 Documentation of the associated normative and informative references for the codec is RECOMMENDED.
@@ -243,6 +269,8 @@ Codec Name: VP8 Codec format
 
 Description: VP8 is an open and royalty free video compression format developed by Google and created by On2 Technologies as a successor to VP7. [@!RFC6386]
 
+Codec BlockAdditions: A single-channel encoding of an alpha channel MAY be stored in `BlockAdditions`. The `BlockAddId` of the `BlockMore` containing these data MUST be 1.
+
 Initialization: none
 
 ### V_VP9
@@ -253,6 +281,8 @@ Codec Name: VP9 Codec format
 
 Description: VP9 is an open and royalty free video compression format developed by Google as a successor to VP8. [Draft VP9 Bitstream and Decoding Process Specification](https://www.webmproject.org/vp9/)
 
+Codec BlockAdditions: A single-channel encoding of an alpha channel MAY be stored in `BlockAdditions`. The `BlockAddId` of the `BlockMore` containing these data MUST be 1.
+
 Initialization: none
 
 ### V_FFV1
@@ -623,7 +653,9 @@ Codec ID: A_WAVPACK4
 
 Codec Name: [WavPack](http://www.wavpack.com/) lossless audio compressor
 
-Description: The Wavpack packets consist of a stripped header followed by the frame data. For multi-track (> 2 tracks) a frame consists of many packets. For hybrid files (lossy part + correction part), the correction part is stored in an additional block (level 1). For more details, check the [WavPack muxing description](wavpack.html).
+Description: The Wavpack packets consist of a stripped header followed by the frame data. For multi-track (> 2 tracks) a frame consists of many packets. For more details, check the [WavPack muxing description](wavpack.html).
+
+Codec BlockAdditions: For hybrid `A_WAVPACK4` encodings (that include a lossy encoding with a supplemental correction to produce a lossless encoding), the correction part is stored in BlockAdditional. The `BlockAddId` of the `BlockMore` containing these data MUST be 1.
 
 Initialization: none
 

diff --git a/ebml_matroska.xml b/ebml_matroska.xml
@@ -151,7 +151,7 @@
     <extension webm="1"/>
   </element>
   <element name="BlockAddID" path="1*1(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAddID)" id="0xEE" type="uinteger" range="not 0" default="1" minOccurs="1" maxOccurs="1">
-    <documentation lang="en" purpose="definition">An ID to identify the BlockAdditional level.</documentation>
+    <documentation lang="en" purpose="definition">An ID to identify the BlockAdditional level. A value of 1 means the BlockAdditional data is interpreted as additional data passed to the codec with the Block data.</documentation>
     <extension webm="1"/>
   </element>
   <element name="BlockAdditional" path="1*1(\Segment\Cluster\BlockGroup\BlockAdditions\BlockMore\BlockAdditional)" id="0xA5" type="binary" minOccurs="1" maxOccurs="1">
@@ -317,6 +317,21 @@
     <documentation lang="en" purpose="definition">The maximum value of <a href="https://www.matroska.org/technical/specs/index.html#BlockAddID">BlockAddID</a>. A value 0 means there is no <a href="https://www.matroska.org/technical/specs/index.html#BlockAdditions">BlockAdditions</a> for this track.</documentation>
     <extension webm="0"/>
   </element>
+  <element name="BlockAdditionMapping" path="0*(\Segment\Tracks\TrackEntry\BlockAdditionMapping)" id="0x41E4" type="master" minver="4" webm="0">
+    <documentation lang="en">Contains elements that describe each value of <a href="https://www.matroska.org/technical/specs/index.html#BlockAddID">BlockAddID</a> found in the Track.</documentation>
+  </element>
+  <element name="BlockAddIDValue" path="1*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDValue)" id="0x41F0" type="uinteger" minOccurs="1" maxOccurs="1" minver="4" webm="0" range=">=2">
+    <documentation lang="en">The <a href="https://www.matroska.org/technical/specs/index.html#BlockAddID">BlockAddID</a> value being described. To keep MaxBlockAdditionID as low as possible, small values SHOULD be used.</documentation>
+  </element>
+  <element name="BlockAddIDName" path="0*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDName)" id="0x41A4" type="string" minOccurs="0" maxOccurs="1" minver="4" webm="0">
+    <documentation lang="en">A human-friendly name describing the type of BlockAdditional data as defined by the associated Block Additional Mapping.</documentation>
+  </element>
+  <element name="BlockAddIDType" path="1*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDType)" id="0x41E7" type="uinteger" minOccurs="1" maxOccurs="1" minver="4" webm="0" default="0">
+    <documentation lang="en">Stores the registered identifer of the Block Additional Mapping to define how the BlockAdditional data should be handled.</documentation>
+  </element>
+  <element name="BlockAddIDExtraData" path="0*1(\Segment\Tracks\TrackEntry\BlockAdditionMapping\BlockAddIDExtraData)" id="0x41E7" type="binary" minOccurs="0" maxOccurs="1" minver="4" webm="0">
+      <documentation lang="en">Extra binary data that the BlockAddIDType can use to interpret the BlockAdditional data. The intepretation of the binary data depends on the BlockAddIDType value and the corresponding Block Additional Mapping.</documentation>
+  </element>
   <element name="Name" path="0*1(\Segment\Tracks\TrackEntry\Name)" id="0x536E" type="utf-8" maxOccurs="1">
     <documentation lang="en" purpose="definition">A human-readable track name.</documentation>
     <extension cppname="TrackName"/>