Matroska Media Container Tag Specifications

6.1. Why official tags matter

There is a debate between people who think all tags SHOULD be free and those who think all tags SHOULD be strict. If you look at this page you will realize we are in between.¶

Advanced-users application might let you put any tag in your file. But for the rest of the applications, they usually give you a basic list of tags you can use. Both have their needs. But it's usually a bad idea to use custom/exotic tags because you will probably be the only person to use this information even though everyone else could benefit from it. So hopefully, when someone wants to put information in one's file, they will find an official one that fit them and hopefully use it ! If it's not in the list, this person can contact us any time for addition of such a missing tag. But it doesn't mean it will be accepted... Matroska files are not meant the become a whole database of people who made costumes for a film. A website would be better for that... It's hard to define what SHOULD be in and what doesn't make sense in a file. So we'll treat each request carefully.¶

We also need an official list simply for developers to be able to display relevant information in their own design (if they choose to support a list of meta-information they SHOULD know which tag has the wanted meaning so that other apps could understand the same meaning).¶

6.2. Tag translations

To be able to save tags from other systems to Matroska we need to translate them to our system. There is a translation table on our site.¶

6.3. Tag Formatting

• The TagName SHOULD always be written in all capital letters and contain no space.¶
• The fields with dates SHOULD have the following format: YYYY-MM-DD hh:mm:ss.mss YYYY = Year, MM = Month, DD = Days, HH = Hours, mm = Minutes, ss = Seconds, mss = Milliseconds. To store less accuracy, you remove items starting from the right. To store only the year, you would use, "2004". To store a specific day such as May 1st, 2003, you would use "2003-05-01".¶
• Fields that require a Float SHOULD use the "." mark instead of the "," mark. To display it differently for another local, applications SHOULD support auto replacement on display. Also, a thousandths separator SHOULD NOT be used.¶
• For currency amounts, there SHOULD only be a numeric value in the Tag. Only numbers, no letters or symbols other than ".". For instance, you would store "15.59" instead of "$15.59USD".¶

6.4. Target types

The TargetType element allows tagging of different parts that are inside or outside a given file. For example, in an audio file with one song you could have information about the album it comes from and even the CD set even if it's not found in the file.¶

For application to know what kind of information (like TITLE) relates to a certain level (CD title or track title), we also need a set of official TargetType names. For now audio and video will have different values & names. That also means the same tag name can have different meanings depending on where it is (otherwise we would end up with 15 TITLE_ tags).¶

An upper level value tag applies to the lower level. That means if a CD has the same artist for all tracks, you just need to set the ARTIST tag at level 50 (ALBUM) and not to each TRACK (but you can). That also means that, if some parts of the CD have no known ARTIST, the value MUST be set to nothing (a void string "").¶

When a level doesn't exist it MUST NOT be specified in the files, so that the TOTALPARTS and PARTNUMBER elements match the same levels.¶

Here is an example of how these organizational tags work: If you set 10 TOTAL_PARTS to the ALBUM level (40) it means the album contains 10 lower parts. The lower part in question is the first lower level that is specified in the file. So, if it's TRACK (30), then that means it contains 10 tracks. If it's MOVEMENT (20), that means it's 10 movements, etc.¶

6.5. Official tags

The following is a complete list of the supported Matroska Tags. While it is possible to use Tag names that are not listed below, this is not recommended as compatibility will be compromised. If you find that there is a Tag missing that you would like to use, then please contact the Matroska team for its inclusion in the specifications before the format reaches 1.0.¶

6.6. Nesting Information

Nesting Information tags are intended to contain other tags.¶

to describe the original work of art that this item is based on. All tags in this list can be used "under" the ORIGINAL tag like LYRICIST, PERFORMER, etc. SAMPLE | - | A tag that contains other tags to describe a sample used in the targeted item taken from another work of art. All tags in this list can be used "under" the SAMPLE tag like TITLE, ARTIST, DATERELEASED, etc. COUNTRY | UTF-8 | The name of the country ([biblio ISO-639-2](https://www.loc.gov/standards/iso639-2/php/Englishlist.php)) that is meant to have other tags inside (using nested tags) to country specific information about the item. All tags in this list can be used "under" the COUNTRYSPECIFIC tag like LABEL, PUBLISHRATING, etc.¶

6.7. Organization Information

the total number of tracks of an audio CD) PARTNUMBER | UTF-8 | Number of the current part of the current level. (e.g., if TargetType is TRACK, the track number of an audio CD) PARTOFFSET | UTF-8 | A number to add to PART_NUMBER, when the parts at that level don't start at 1. (e.g., if TargetType is TRACK, the track number of the second audio CD)¶

6.8. Titles

or for video's audio track you might use "English 5.1" This is akin to the TIT2 tag in ID3. SUBTITLE | UTF-8 | Sub Title of the entity.¶

6.9. Nested Information

Nested Information includes tags contained in other tags.¶

to be sorted -- for example, "Pet Shop Boys" instead of "The Pet Shop Boys". Or "Marley Bob" and "Marley Ziggy" (no comma needed). INSTRUMENTS | UTF-8 | The instruments that are being used/played, separated by a comma. It SHOULD be a child of the following tags: ARTIST, LEAD_PERFORMER, or ACCOMPANIMENT. EMAIL | UTF-8 | Email corresponding to the tag it's included in. ADDRESS | UTF-8 | The physical address of the entity. The address SHOULD include a country code. It can be useful for a recording label. FAX | UTF-8 | The fax number corresponding to the tag it's included in. It can be useful for a recording label. PHONE | UTF-8 | The phone number corresponding to the tag it's included in. It can be useful for a recording label.¶

6.10. Entities

This is akin to the TPE1 tag in ID3. LEADPERFORMER | UTF-8 | Lead Performer/Soloist(s). This can sometimes be the same as ARTIST. ACCOMPANIMENT | UTF-8 | Band/orchestra/accompaniment/musician. This is akin to the TPE2 tag in ID3. COMPOSER | UTF-8 | The name of the composer of this item. This is akin to the TCOM tag in ID3. ARRANGER | UTF-8 | The person who arranged the piece, e.g., Ravel. LYRICS | UTF-8 | The lyrics corresponding to a song (in case audio synchronization is not known or as a doublon to a subtitle track). Editing this value, when subtitles are found, SHOULD also result in editing the subtitle track for more consistency. LYRICIST | UTF-8 | The person who wrote the lyrics for a musical item. This is akin to the TEXT tag in ID3. CONDUCTOR | UTF-8 | Conductor/performer refinement. This is akin to the TPE3. DIRECTOR | UTF-8 | This is akin to the [IART tag in RIFF][RIFF.tags]. ASSISTANTDIRECTOR | UTF-8 | The name of the assistant director. DIRECTOROFPHOTOGRAPHY| UTF-8 | The name of the director of photography, also known as cinematographer. This is akin to the ICNM tag in Extended RIFF. SOUNDENGINEER | UTF-8 | The name of the sound engineer or sound recordist. ARTDIRECTOR | UTF-8 | The person who oversees the artists and craftspeople who build the sets. PRODUCTIONDESIGNER | UTF-8 | Artist responsible for designing the overall visual appearance of a movie. CHOREGRAPHER | UTF-8 | The name of the choregrapher COSTUMEDESIGNER | UTF-8 | The name of the costume designer ACTOR | UTF-8 | An actor or actress playing a role in this movie. This is the person's real name, not the character's name the person is playing. CHARACTER | UTF-8 | The name of the character an actor or actress plays in this movie. This SHOULD be a sub-tag of an ACTOR tag in order not to cause ambiguities. WRITTENBY | UTF-8 | The author of the story or script (used for movies and TV shows). SCREENPLAYBY | UTF-8 | The author of the screenplay or scenario (used for movies and TV shows). EDITEDBY | UTF-8 | This is akin to the IEDT tag in Extended RIFF. PRODUCER | UTF-8 | Produced by. This is akin to the IPRO tag in Extended RIFF. COPRODUCER | UTF-8 | The name of a co-producer. EXECUTIVEPRODUCER | UTF-8 | The name of an executive producer. DISTRIBUTEDBY | UTF-8 | This is akin to the IDST tag in Extended RIFF. MASTEREDBY | UTF-8 | The engineer who mastered the content for a physical medium or for digital distribution. ENCODEDBY | UTF-8 | This is akin to the TENC tag in ID3. MIXEDBY | UTF-8 | DJ mix by the artist specified REMIXEDBY | UTF-8 | Interpreted, remixed, or otherwise modified by. This is akin to the TPE4 tag in ID3. PRODUCTIONSTUDIO | UTF-8 | This is akin to the ISTD tag in Extended RIFF. THANKS_TO | UTF-8 | A very general tag for everyone else that wants to be listed. PUBLISHER | UTF-8 | This is akin to the TPUB tag in ID3. LABEL | UTF-8 | The record label or imprint on the disc.¶

6.11. Search and Classification

The format follows the infamous TCON tag in ID3. MOOD | UTF-8 | Intended to reflect the mood of the item with a few keywords, e.g., "Romantic", "Sad" or "Uplifting". The format follows that of the TMOO tag in ID3. ORIGINALMEDIATYPE | UTF-8 | Describes the original type of the media, such as, "DVD", "CD", "computer image," "drawing," "lithograph," and so forth. This is akin to the TMED tag in ID3. CONTENTTYPE | UTF-8 | The type of the item. e.g., Documentary, Feature Film, Cartoon, Music Video, Music, Sound FX, ... SUBJECT | UTF-8 | Describes the topic of the file, such as "Aerial view of Seattle." DESCRIPTION | UTF-8 | A short description of the content, such as "Two birds flying." KEYWORDS | UTF-8 | Keywords to the item separated by a comma, used for searching. SUMMARY | UTF-8 | A plot outline or a summary of the story. SYNOPSIS | UTF-8 | A description of the story line of the item. INITIALKEY | UTF-8 | The initial key that a musical track starts in. The format is identical to ID3. PERIOD | UTF-8 | Describes the period that the piece is from or about. For example, "Renaissance". LAW_RATING | UTF-8 | Depending on the COUNTRY it's the format of the rating of a movie (P, R, X in the USA, an age in other countries or a URI defining a logo). ICRA | binary | The ICRA content rating for parental control. (Previously RSACi)¶

6.12. Temporal Information

6.13. Spacial Information

same 2 octets as in Internet domains, or possibly ISO-3166. This code is followed by a comma, then more detailed information such as state/province, another comma, and then city. For example, "US, Texas, Austin". This will allow for easy sorting. It is okay to only store the country, or the country and the state/province. More detailed information can be added after the city through the use of additional commas. In cases where the province/state is unknown, but you want to store the city, simply leave a space between the two commas. For example, "US, , Austin". COMPOSITIONLOCATION | UTF-8 | Location that the item was originally designed/written. The countries corresponding to the string, same 2 octets as in Internet domains, or possibly ISO-3166. This code is followed by a comma, then more detailed information such as state/province, another comma, and then city. For example, "US, Texas, Austin". This will allow for easy sorting. It is okay to only store the country, or the country and the state/province. More detailed information can be added after the city through the use of additional commas. In cases where the province/state is unknown, but you want to store the city, simply leave a space between the two commas. For example, "US, , Austin". COMPOSERNATIONALITY | UTF-8 | Nationality of the main composer of the item, mostly for classical music. The countries corresponding to the string, same 2 octets as in Internet domains, or possibly ISO-3166.¶

6.14. Personal

0 and 5 with decimal values possible (e.g., 2.7), 5(.0) being the highest possible rating. Other rating systems with different ranges will have to be scaled.¶

6.15. Technical Information

and excludes headers and any container overhead. FPS | UTF-8 | The average frames per second of the specified item. This is typically the average number of Blocks per second. In the event that lacing is used, each laced chunk is to be counted as a separate frame. BPM | UTF-8 | Average number of beats per minute in the complete target (e.g., a chapter). Usually a decimal number. MEASURE | UTF-8 | In music, a measure is a unit of time in Western music like "4/4". It represents a regular grouping of beats, a meter, as indicated in musical notation by the time signature. The majority of the contemporary rock and pop music you hear on the radio these days is written in the 4/4 time signature. TUNING | UTF-8 | It is saved as a frequency in hertz to allow near-perfect tuning of instruments to the same tone as the musical piece (e.g., "441.34" in Hertz). The default value is 440.0 Hz. REPLAYGAINGAIN | binary | The gain to apply to reach 89dB SPL on playback. This is based on the Replay Gain standard. Note that ReplayGain information can be found at all TargetType levels (track, album, etc). REPLAYGAINPEAK | binary | The maximum absolute peak value of the item. This is based on the Replay Gain standard.¶

6.16. Identifiers

excluding the "ISRC" prefix and including hyphens. MCDI | binary | This is a binary dump of the TOC of the CDROM that this item was taken from. This holds the same information as the MCDI in ID3. ISBN | UTF-8 | International Standard Book Number BARCODE | UTF-8 | EAN-13 (European Article Numbering) or UPC-A (Universal Product Code) bar code identifier CATALOGNUMBER | UTF-8 | A label-specific string used to identify the release -- for example, TIC 01. LABELCODE | UTF-8 | A 4-digit or 5-digit number to identify the record label, typically printed as (LC) xxxx or (LC) 0xxxx on CDs medias or covers (only the number is stored). LCCN | UTF-8 | Library of Congress Control Number IMDB | UTF-8 | Internet Movie Database (IMDb) identifier. "tt" followed by at least 7 digits for Movies, TV Shows, and Episodes. TMDB | UTF-8 | The Movie Database (TMDb) identifier. The variable length digits string MUST be prefixed with either "movie/" or "tv/". TVDB | UTF-8 | The TV Database (TheTVDB) identifier. Variable length all-digits string identifying a TV Show.¶

6.17. Commercial

no letters or symbols other than ".". For instance, you would store "15.59" instead of "$15.59USD". PURCHASE_CURRENCY | UTF-8 | The currency type used to pay for the entity. Use ISO-4217 for the 3 letter currency code.¶

6.18. Legal

6.19. Notes

• In the Target list, a logical OR is applied on all tracks, a logical OR is applied on all chapters. Then a logical AND is applied between the Tracks list and the Chapters list to know if an element belongs to this Target.¶