diff --git a/Makefile b/Makefile
index 0a194fd7..94fb3845 100644
--- 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
new file mode 100644
index 00000000..5d6a75d1
--- /dev/null
+++ 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
+
+
+
+
+ 1
+ 568001708
+ 1
+
+ 2
+ timecode
+ 12
+
+ V_FFV1
+
+
+
+
+ 3000
+
+ {binary video frame}
+
+
+ 2
+ 01:00:00:00
+
+
+
+
+
+```
+
+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
index e3cf55d5..fb016f17 100644
--- 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
+
+ {Binary data of a VP9 video frame in YUV}
+
+
+ 1
+ {alpha channel encoding to supplement the VP9 frame}
+
+
+
+```
+
### 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
index d2afac1a..def4520b 100644
--- a/ebml_matroska.xml
+++ b/ebml_matroska.xml
@@ -151,7 +151,7 @@
- An ID to identify the BlockAdditional level.
+ 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.
@@ -317,6 +317,21 @@
The maximum value of BlockAddID. A value 0 means there is no BlockAdditions for this track.
+
+ Contains elements that describe each value of BlockAddID found in the Track.
+
+
+ The BlockAddID value being described. To keep MaxBlockAdditionID as low as possible, small values SHOULD be used.
+
+
+ A human-friendly name describing the type of BlockAdditional data as defined by the associated Block Additional Mapping.
+
+
+ Stores the registered identifer of the Block Additional Mapping to define how the BlockAdditional data should be handled.
+
+
+ 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.
+
A human-readable track name.