References ▼
The KLV keys are described in Data Encoding Protocol using Key-Length-Value (SMPTE 336M-2001). The following sections provide a quick overview of the key structure, but for complete information you should read the previously mentioned document.
Offset (0-based) |
Description |
Length (bytes) |
Content/Format |
0 |
KLV header (this is the same for all keys). |
4 |
Always 0x06 0x0E 0x2B |
4 |
Registry category designator: Identifies the category of registry described (dictionary, groups, wrappers, labels). |
1 |
One of the RegistryCategoryConstants values |
5 |
Registry designator: identifies the specific registry in a category. |
1 |
Depends on the value of Registry category designator. |
6 |
Structure designator: Designator of the structure variant within the given registry. |
1 |
|
7 |
Version number. |
1 |
|
8 |
Item designator: the identifier for the key. |
8 |
|
The KLV keys are identified by 16 bytes, which can be broken into 3 sections as follows:
1. KLV header section (bytes 0..3), which are always 0x06 0x0E 0x2B 0x34. Right now, this is not important because the number of defined keys is less than 264.
2. General section (bytes 4..7), which was originally meant to describe the format of the data. In reality, these bytes are almost the same for all versions of a key, except for the version number (byte at offset 7). The byte at offset 6 (structure designator) is almost always 0x01. The version number is quite important because the format of the data might change from one version to another. For example, key data for version 1 might be a 16-bit value, while the version 2 key might write 32-bit values.
3. The key identifier (bytes 8..15). These bytes identify which data is associated with this key. This is the data that you should be searching for when you want to find out the meaning of a certain key.
LEAD has defined some common keys in ILMMpgDmxP.h. You will find them defined as KlvKey_XXX values. For example, look for KlvKey_UserDefinedTimeStamp and you will find the list of the keys that LEAD has defined.
LEAD has defined certain defines to help you access certain bytes in the key. Look below for more information.
Useful enumerations for examining the keys
Use the KlvOffsetConstants enumeration to find the offsets for important key components in the 16-byte key:
typedef enum KlvOffsetConstants{KLVOFFSET_REGISTRYCATEGORY = 4, /* Designator identifying the category of registry described (e.g.,dictionaries) */KLVOFFSET_REGISTRYDESIGNATOR = 5, /* Designator identifying the specific registry in a category (e.g., metadata dictionary) */KLVOFFSET_STRUCTUREDESIGNATOR = 6, /* Designator of the structure variant within the given registry */KLVOFFSET_VERSIONNUMBER = 7, /* Version of the given registry which first defines the item specified by the item designator */KLVOFFSET_ITEMDESIGNATOR = 8, /* Unique identification of the particular item within the context of the UL designator (Up to 8 bytes) */} KlvOffsetConstants;
Use the RegistryCategoryConstants enumeration to determine possible values for the registry category designator (the byte at offset 4):
typedef enum RegistryCategoryConstants{ REGISTRYCATEGORY_DICTIONARY = 1, /* Dictionaries: Next byte=KlvDictionaryConstants (01=Metadata, 02=Essence, 03=Control, 04=Types) */REGISTRYCATEGORY_GROUPS = 2, /* Groups: Next byte=KlvGroupConstants (01=Universal, 02=Global, 03=Local, 04=Variable-length packs (default), 05=Fixed-length packs) */REGISTRYCATEGORY_WRAPPERS = 3, /* Wrappers and containers: Next byte=KlvWrapperConstants (01=Simple, 02=Complex) */REGISTRYCATEGORY_LABELS = 4, /* Labels: Next byte=KlvLabelConstants (01=Labels dictionary) */} RegistryCategoryConstants;
If the registry category value designator is REGISTRYCATEGORY_DICTIONARY, the registry designator (byte at offset 5) is one of the following values:
typedef enum KlvDictionaryConstants{KLVDICTIONARY_METADATA = 1, /* 01 = Metadata Dictionaries */KLVDICTIONARY_ESSENCE = 2, /* 02 = Essence Dictionaries */KLVDICTIONARY_CONTROL = 3, /* 03 = Control Dictionaries */KLVDICTIONARY_TYPES = 4, /* 04 = Types Dictionaries */} KlvDictionaryConstants;
If the registry category value designator is REGISTRYCATEGORY_GROUP, the registry designator (byte at offset 5) is one of the following values:
typedef enum KlvGroupConstants{KLVGROUPS_UNIVERSAL= 0x01, /* 01 = Universal Groups */KLVGROUPS_GLOBAL= 0x02, /* 02 = Global Groups */KLVGROUPS_VARIABLEPACK= 0x04, /* 04 = Variable-length packs (default) */KLVGROUPS_FIXEDPACK= 0x05, /* 05 = Fixed-length packs */KLVGROUPS_LOCAL_1_BER= 0x03, /* 03 = Local Groups (Key=1 byte, Data=ASN.1 BER short or long) */KLVGROUPS_LOCAL_BER_BER= 0x0B, /* 0B = Local Groups (Key=ASN.1 OID BER, Data=ASN.1 BER short or long) */KLVGROUPS_LOCAL_2_BER= 0x13, /* 13 = Local Groups (Key=2 bytes, Data=ASN.1 BER short or long */KLVGROUPS_LOCAL_4_BER= 0x1B, /* 1B = Local Groups (Key=4 bytes, Data=ASN.1 BER short or long */KLVGROUPS_LOCAL_1_1= 0x23, /* 23 = Local Groups (Key=1 byte, Data=1 byte */KLVGROUPS_LOCAL_BER_1= 0x2B, /* 2B = Local Groups (Key=ASN.1 OID BER, Data=1 byte */KLVGROUPS_LOCAL_2_1= 0x33, /* 33 = Local Groups (Key=2 bytes, Data=1 byte */KLVGROUPS_LOCAL_4_1= 0x3B, /* 3B = Local Groups (Key=4 bytes, Data=1 byte */KLVGROUPS_LOCAL_1_2= 0x43, /* 43 = Local Groups (Key=1 byte, Data=2 bytes */KLVGROUPS_LOCAL_BER_2= 0x4B, /* 4B = Local Groups (Key=ASN.1 OID BER, Data=2 bytes */KLVGROUPS_LOCAL_2_2= 0x53, /* 53 = Local Groups (Key=2 bytes, Data=2 bytes */KLVGROUPS_LOCAL_4_2= 0x5B, /* 5B = Local Groups (Key=4 bytes, Data=2 bytes */KLVGROUPS_LOCAL_1_4= 0x63, /* 63 = Local Groups (Key=1 byte, Data=4 bytes */KLVGROUPS_LOCAL_BER_4= 0x6B, /* 6B = Local Groups (Key=ASN.1 OID BER, Data=4 bytes */KLVGROUPS_LOCAL_2_4= 0x73, /* 73 = Local Groups (Key=2 bytes, Data=4 bytes */KLVGROUPS_LOCAL_4_4= 0x7B, /* 7B = Local Groups (Key=4 bytes, Data=4 bytes */} KlvGroupConstants;
In each of the above KLVGROUPS_LOCAL_X_Y keys, X indicates the number of bytes used to store the keys and Y the number of bytes used to store the data for each key. BER indicates variable length. The most common cases are :
KLVGROUPS_LOCAL_BER_BER (Both key and data are stored using variable length encodings)
KLVGROUPS_LOCAL_1_BER (the key is stored using one byte, while the data is stored using variable length)
If the registry category value designator is REGISTRYCATEGORY_WRAPPER, the registry designator (byte at offset 5) is one of the following values:
typedef enum KlvWrapperConstants{KLVWRAPPERS_SIMPLE = 1, /* 01 = Simple wrappers */KLVWRAPPERS_COMPLEX = 2, /* 02 = Complex wrappers */} KlvWrapperConstants;
If the registry category value designator is REGISTRYCATEGORY_LABEL, the registry designator (byte at offset 5) is one of the following values:
typedef enum KlvLabelConstants{KLVLABELS_LABEL = 4, /* 01 = Labels dictionary */} KlvLabelConstants;