| $Id: musicmatch.txt,v 1.4 2000/09/09 23:02:37 eldamitri Exp $ |
| |
| |
| MusicMatch (TM) tag format description |
| |
| Status of this document |
| |
| This document is a description of a deprecated tagging format. The |
| information contained herein is not a specification; its intent is to |
| interpret the format based on hundreds of examples. It also relies heavily |
| on information obtained by others who have done similar investigations. It |
| is not based on any official documentation of the format, as such |
| documentation is not publicly available. Therefore the contents of this |
| document may change to adjust for newly-discovered information, but the |
| format itself is unlikely to change due to its deprecation. |
| |
| Distribution of this document is unlimited. |
| |
| |
| Abstract |
| |
| This document describes the MusicMatch tagging format present in some |
| digital audio files. This format, like other tagging specifications, |
| provides a method for storing information about an audio file within itself |
| to document its contents. This format was developed by MusicMatch and |
| used exclusively by older versions of Jukebox, their popular, "all-in-one" |
| MP3 application. |
| |
| 1. Table of contents |
| |
| Status of this document |
| Abstract |
| 1. Table of contents |
| 2. Introduction |
| 3. Conventions in this document |
| 4. Tagging format |
| 4.1. Header |
| 4.2. Image extension |
| 4.3. Image binary |
| 4.4. Unused |
| 4.5. Version information |
| 4.6. Audio meta-data |
| 4.6.1. Single-line text fields |
| 4.6.2. Non-text fields |
| 4.6.3. Multi-line text fields |
| 4.6.4. Internet addresses |
| 4.6.5. Padding |
| 4.7. Data offsets |
| 4.8. Footer |
| 5. Identifying and parsing a MusicMatch tag |
| 6. Converting to ID3v2 |
| 7. Copyright |
| 8. References |
| 9. Author's Address |
| |
| |
| 2. Introduction |
| |
| The following document describes the structure of the tagging format used |
| by MusicMatch (TM) Jukebox, prior to version 4.0 of that application. This |
| program is a so-called "All-In-One" MP3 program and provides a CD-Ripper, |
| WAV-to-MP3 converter, database, and MP3 player. |
| |
| The MusicMatch tagging format has gone through several incremental |
| iterations in its format, although the basic structure has remained fairly |
| constant throughout its history. The various formats of the MusicMatch tag |
| have been tightly coupled with the version of Jukebox that created it. As |
| such, this document will refer to the Jukebox version and tagging format |
| version interchangeably. |
| |
| As of version 4.0, MusicMatch has deprecated the use of this format in |
| their own Jukebox application, transitioning instead to ID3v2, an open |
| standard for tagging digital audio. Unfortunately, despite repeated |
| requests, MusicMatch has not provided to the public any documents |
| describing this format, and the MusicMatch Jukebox is the only |
| widely-distributed software application that can read and write these tags. |
| |
| As such, this text may not be completely accurate and is surely incomplete, |
| but it covers enough to the format to enable one to write robust software |
| to find and parse tags in this format. For example, the id3lib tagging |
| library's MusicMatch parsing routines were written solely based on the |
| information found in this document. However, the authors cannot be held |
| responsible for any inaccuracies or any harm caused by using this |
| information. One can assume that the specifition is unlikely to change, |
| given MusicMatch's own abandonment of the format. It should also be noted |
| that incoporating functionality into applications to write tags in this |
| format is discouraged, as the format has been officially deprecated by |
| MusicMatch themselves. |
| |
| 3. Conventions in this document |
| |
| This document borrows heavily from specifications written by Martin |
| Nillson, author of the ID3v2 tagging standard. Much of the structure, |
| formatting, and other such conventions used in the ID3v2 specifications are |
| carried over into this document. |
| |
| Text within "" is a text string exactly as it appears in a tag. Numbers |
| preceded with $ are hexadecimal and numbers preceded with % are binary. $xx |
| is used to indicate a byte with unknown content. |
| |
| 4. Tag overview |
| |
| The MusicMatch Tagging Format was designed to store specific types of audio |
| meta-data inside the audio file itself. As the format was used exclusively |
| by the MusicMatch Jukebox application, it is used only with MPEG-1/2 layer |
| III files encoded with that program. However, its tagging format is not |
| inherently exclusive of other audio formats, and could conceivably be |
| used with other types of encodings. |
| |
| MusicMatch tags were originally designed to come at the very end of MP3 |
| files, after all of the MP3 audio frames. Starting with Jukebox version |
| 3.1, the application became more ID3-friendly and started placing ID3v1 |
| tags after the MusicMatch tag as well. In practice, since very few |
| applications outside of the MusicMatch Jukebox are capable of reading and |
| understanding this format, it is not unusual to find MusicMatch tags |
| "buried" within mp3 files, coming before other types of tagging formats in |
| a file, such as Lyrics3 or ID3v2.4.0. Such "relocations" are not uncommon, |
| and therefore any software application that intends to find, read, and |
| parse MusicMatch tags should be flexible in this endeavor, despite the |
| apparent intentions of the original specification. |
| |
| Although various sections of a MusicMatch tag are fixed in length, other |
| sections are not, and so tag lengths can vary from one file to another. A |
| valid MusicMatch tag will be at least 8 kilobytes (8192 bytes) in length. |
| Those tags with image data will often be much larger. |
| |
| The byte-order in 4-byte pointers and multibyte numbers for MusicMatch tags |
| is least-significant byte (LSB) first, also known as "little endian". For |
| example, $12345678 is encoded as $78 56 34 12. |
| |
| Overall tag structure: |
| |
| +-----------------------------+ |
| | Header | |
| | (256 bytes, OPTIONAL) | |
| +-----------------------------+ |
| | Image extension (4 bytes) | |
| +-----------------------------+ |
| | Image binary | |
| | (var. length >= 4 bytes) | |
| +-----------------------------+ |
| | Unused (4 bytes) | |
| +-----------------------------+ |
| | Version info (256 bytes) | |
| +-----------------------------+ |
| | Audio meta-data | |
| | (var. length >= 7868 bytes) | |
| +-----------------------------+ |
| | Data offsets (20 bytes) | |
| +-----------------------------+ |
| | Footer (48 bytes) | |
| +-----------------------------+ |
| |
| This document will describe the various sections of the tag in the order |
| listed above (that is, in the sequential order that they appear when |
| reading the tag from beginning to end). However, due to the nature of the |
| tag's format, in practice the tag's sections will often be parsed in the |
| reverse order. A robust parsing algorithm will be suggested and described |
| later in the document. |
| |
| 4.1. Header |
| |
| An optional tag header often precedes the tag data in a MusicMatch tag. |
| Although the rules that determine this header's required presence are |
| unknown, the header is usually found in tag versions up to and including |
| 2.50, and is usually lacking otherwise. Luckily, its format is rigid and |
| therefore its presence is easy to determine. The data in the header are |
| not vital to the correct parsing of the rest of the tag and can thus be |
| discarded. The header is the only optional section in a MusicMatch tag. |
| All other sections are required to consider the tag valid. |
| |
| The header section is always 256 bytes in length. It begins with three |
| 10-byte subsections, and ends with 226 bytes of space ($20) padding. Each |
| of the first three subsections contains an 8-byte ASCII text string |
| followed by two bytes of null ($00) padding. |
| |
| The first subsection serves as a sync string: its 8-byte string is always |
| "18273645". |
| |
| The second subsection's 8-byte string is the version of the Xing encoder |
| used to encode the mp3 file. The last four bytes of this string are |
| usually '0' ($30). An example of this string is "1.010000". |
| |
| The third and final 10-byte subsection is the version of the MusicMatch |
| Jukebox used to encode the mp3 file. The last four bytes of this string |
| are usually '0' ($30). An example of this string is "2.120000". |
| |
| Sync string "18273645" |
| Null padding $00 00 |
| Xing encoder version <8-byte numerical ASCII string> |
| Null padding $00 00 |
| MusicMatch version <8-byte numerical ASCII string> |
| Null padding $00 00 |
| Space padding 226 * $20 |
| |
| 4.2. Image extension |
| |
| MusicMatch tags can contain at most one image. This first required section |
| is the extension of the image when saved as a file (for example, "jpg" or |
| "bmp"). This section is 4 bytes in length, and the data is padded with |
| spaces ($20) if the extension doesn't use all 4 bytes (in practice, 3-byte |
| extensions are the most prevalent). Likewise, tags without images have all |
| spaces for this section (4 * $20). |
| |
| Picture extension $xx xx xx xx |
| |
| 4.3. Image binary |
| |
| When an image is present in the tag, the image binary section consists of |
| two fields. The first field is the size of the image data, in bytes. The |
| second is the actual image data. |
| |
| Image size $xx xx xx xx |
| Image data <binary data> |
| |
| If no image is present, the image binary section consists of exactly four |
| null bytes ($00 00 00 00). |
| |
| 4.4. Unused |
| |
| This section is never used, to the best of the author's knowledge. It is |
| always 4 null ($00) bytes. |
| |
| Null padding $00 00 00 00 |
| |
| 4.5. Version information |
| |
| This section of the tag has the exact same format as the header. Unlike |
| the header, this section is required for the tag to be considered valid. |
| |
| Sync string "18273645" |
| Null padding $00 00 |
| Xing encoder version <8-byte numerical ASCII string> |
| Null padding $00 00 |
| MusicMatch version <8-byte numerical ASCII string> |
| Null padding $00 00 |
| Space padding 226 * $20 |
| |
| 4.6. Audio meta-data |
| |
| The audio meta-data is the heart of the MusicMatch tag. It contains most |
| of the pertinent information found in other tagging formats (song title, |
| album title, artist, etc.) and some that are unique to this format (mood, |
| prefernce, situation). |
| |
| In all versions of the MusicMatch format up to and including 3.00, this |
| section is always 7868 bytes in length. All subsequent versions allowed |
| three possible lengths for this section: 7936, 8004, and 8132 bytes. The |
| conditions under which a particular length from these three possibilities |
| was used is unknown. In all cases, this section is padded with dashes |
| ($2D) to achieve this constant size. |
| |
| Due to the great number of fields in this portion of the tag, they are |
| divided amongst the next four sections of the document: single-line text |
| fields, non-text fields, multi-line text fields, and internet addresses. |
| This clarification is somewhat arbitrary and somewhat inaccurate (some of |
| the fields described as "non-text" are indeed ASCII strings). However, the |
| clarification does allow for easier description of the meta-data as a |
| whole. At any rate, the actual fields in this section of the tag appear |
| sequentially in the order presented. |
| |
| |
| 4.6.1. Single-line text fields |
| |
| The first group entries in this section of the tag are variable-length |
| ASCII text strings. Each of these strings are preceded by a two-byte field |
| describing the size of the following string (again, in LSB order). |
| Multiple entries in a text field are separated by a semicolon ($3B). An |
| empty (and non-existant) text field is indicated by a size field of 0 ($00 |
| 00). |
| |
| The first three of these entries are fairly-self explanatory: song title, |
| album title, and artist name. |
| |
| The final five entries are a little less common: Genre, Tempo, Mood, |
| Situation, and Preference. These fields can contain any information, but |
| do to the interface and default set-up for the Jukebox application, they |
| typically are limited to a subset of possibilities. |
| |
| The Genre entry differs from the ID3v1 tagging format in that it allows |
| a full-text genre description, whereas ID3v1 maps a number to a list of |
| genres. Again, the genre description could be anything, but the interface |
| in Jukebox typically limited most users to the standard ID3v1 genres. |
| |
| The Tempo entry is intended to describe the general tempo of the song. The |
| Jukebox application provided the following defaults: None, Fast, Pretty |
| fast, Moderate, Pretty slow, and Slow. |
| |
| The Mood entry describes what type of mood the audio establishes: Typical |
| values include the following: None, Wild, Upbeat, Morose, Mellow, Tranquil, |
| and Comatose. |
| |
| The Situation entry describes in which situation this music is best played. |
| Expect the following: None, Dance, Party, Romantic, Dinner, Background, |
| Seasonal, Rave, and Drunken Brawl. |
| |
| The Preference entry allows the user to rate the song. Possible values |
| include the following: None, Excellent, Very Good, Good, Fair, Poor, and |
| Bad Taste. |
| |
| Song title length $xx xx |
| Song title <ASCII string> |
| Album title length $xx xx |
| Album title <ASCII string> |
| Artist name length $xx xx |
| Artist name <ASCII string> |
| Genre length $xx xx |
| Genre <ASCII string> |
| Tempo length $xx xx |
| Tempo <ASCII string> |
| Mood length $xx xx |
| Mood <ASCII string> |
| Situation length $xx xx |
| Situation <ASCII string> |
| Preference length $xx xx |
| Preference <ASCII string> |
| |
| 4.6.2. Non-text fields |
| |
| The next group of fields is described here as "non-text". They are |
| probably better described as entries that are auto-created (i.e., not |
| entered in by a user), although this isn't entirely accurate, either, as |
| the track number field is determined by user input. At any rate, they've |
| been separated to clarify the presentation of the material. |
| |
| The "Song duration" entry consists of two fields: a size and text. The |
| text is formatted as "minutes:seconds", and thus the size field is |
| typically 4 ($04 00). |
| |
| The only field that is neither a string nor a LSB numerical value is the |
| creation date. It is 8-byte floating-point value. It can be interpreted |
| as a TDateTime in the Delphi programming language, where the integral |
| portion is the number of elapsed days since 1899-12-30, and the mantissa |
| portion represents the fractional portion of that day, where .0 would be |
| midnight, .5 would be noon, and .99999... would be just before midnight |
| of the next day. In practice, this field is typically unused and will be |
| filled with 8 null ($00) bytes. |
| |
| The next field is the play counter, presumably maintained by the Jukebox |
| application. Most of the time this field is unused, and is typically 0 |
| ($00 00 00 00). |
| |
| The next entry is a size/text combo and represents the original filename |
| and path. As these tags were created almost universally on Windows |
| machines, the entries are typically in the form of "C:\path\to\file.mp3". |
| |
| The next size/text entry is the album serial number fetched from the online |
| CDDB when a track is ripped with MusicMatch. |
| |
| The final field is the track number, usually entered automatically when |
| ripping, encoding, and tagging the audio off from a CD using CDDB. |
| |
| Song duration length $xx xx |
| Song duration <ASCII string> |
| Creation date <8-byte IEEE-64 float> |
| Play counter $xx xx xx xx |
| Original filename length $xx xx |
| Original filename <ASCII string> |
| Serial number length $xx xx |
| Serial number <ASCII string> |
| Track number $xx xx |
| |
| 4.6.3. Multi-line text fields |
| |
| The next three entries are typically multi-line entries. All line |
| separators use the Windows-standard carriage return ($0D 0A). As with the |
| single-line text entries, the text fields are preceded by LSB size fields |
| which indicate their length. |
| |
| Notes length $xx xx |
| Notes <ASCII string> |
| Artist bio length $xx xx |
| Artist bio <ASCII string> |
| Lyrics length $xx xx |
| Lyrics <ASCII string> |
| |
| 4.6.4. Internet addresses |
| |
| The final group of meta-data are internet addresses. As with other text |
| entries, the text fields are preceded by LSB size fields. |
| |
| Artist URL length $xx xx |
| Artist URL <ASCII string> |
| "Buy CD" URL length $xx xx |
| "Buy CD" URL <ASCII string> |
| Artist email length $xx xx |
| Artist email <ASCII string> |
| |
| 4.6.5. Padding |
| |
| The data fields are then followed by 16 null ($00) bytes. Presumably these |
| were intended for (up to 8) future text fields. |
| |
| The remainder of this section is padded with '-' ($2D) characters. |
| |
| 4.7. Data offsets |
| |
| This section of the tag was intended to give offsets into the file for each |
| of the five major required sections of the tag. The offsets, however, are |
| off by 1; for searching a file where the first position is offset 0, the |
| offset given here must be reduced by 1. In practice, however, these |
| offsets can often be invalid, since the data that comes before may be |
| increased or reduces (such as when an ID3v2 tag is appended to the file). |
| Therefore these offsets are best used to calculate the size of the sections |
| by finding the difference of two consecutive offsets. Obviously, the size |
| of the audio meta-data section must be calculated in a different manner. |
| |
| Image extension offset $xx xx xx xx |
| Image binary offset $xx xx xx xx |
| Unused offset $xx xx xx xx |
| Version info offset $xx xx xx xx |
| Audio meta-data offset $xx xx xx xx |
| |
| 4.8. Footer |
| |
| Unlike the header, the footer is a required section of any MusicMatch tag, |
| and checking for its existance is an easy way to determine if a file has a |
| MusicMatch tag. It is always 48 bytes in length. The first 19 bytes is |
| the company name "Brava Software Inc." (Note: it seems that the company |
| name has officially changed to MusicMatch, as "Brava Software" is not |
| mentioned anywhere on their website), followed by 13 bytes of space ($20) |
| padding. The next 4 bytes is the tag version as a numerical ASCII string |
| (e.g., "3.05"), and should match the version string found in the Version |
| section and the (optional) header. This is followed by 12 bytes of space |
| ($20) padding. |
| |
| Signature "Brava Software Inc." |
| Space padding 13 * $20 |
| Tag version <4-byte numerical ASCII string> |
| Space padding 12 * $20 |
| |
| 5. Identifying and parsing a MusicMatch tag |
| |
| Finding and parsing a MusicMatch tag is not difficult to do, but due to |
| lack of foresight and questionable design decisions by MusicMatch, care |
| must be taken to ensure it is done correctly. |
| |
| <unfinished /> |
| |
| 6. Converting to ID3v2 |
| |
| As of Jukebox 4.0, MusicMatch has abandoned the MusicMatch tagging format |
| in favor of the open standard ID3v2. The Jukebox application will convert |
| old tags to ID3v2 upon request, but as this is a closed application that |
| serves a limited number of platforms (currently on Windows and Macintosh), |
| having a public specification for performing this mapping is necessary. As |
| ID3v2 can encapsulate all of the information found in the original |
| MusicMatch format while being infinitely more flexible, the decision to |
| convert shouldn't be a difficult one. |
| |
| <unfinished /> |
| |
| 7. Copyright |
| |
| Copyright (C) Scott Thomas Haug 2000. All Rights Reserved. |
| |
| This document and translations of it may be copied and furnished to others, |
| and derivative works that comment on or otherwise explain it or assist in |
| its implementation may be prepared, copied, published and distributed, in |
| whole or in part, without restriction of any kind, provided that a |
| reference to this document is included on all such copies and derivative |
| works. However, this document itself may not be modified in any way and |
| reissued as the original document. |
| |
| The limited permissions granted above are perpetual and will not be |
| revoked. |
| |
| This document and the information contained herein is provided on an 'AS |
| IS' basis and THE AUTHORS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, |
| INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION |
| HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF |
| MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. |
| |
| |
| 8. References |
| |
| [MMTrailer] Peter "The Videoripper" Luijer, |
| 'Description of the MusicMatch trailer in MP3 files' |
| |
| <url:http://members.xoom.com/videoripper/warez/mmtrailer.txt> |
| |
| [ID3v2] Martin Nilsson, 'ID3v2 informal standard'. |
| |
| <url:http://www.id3.org/id3v2.3.0.txt> |
| |
| [id3lib] Scott Thomas Haug, 'The ID3v1/ID3v2 Tagging Library' |
| |
| <url:http://www.id3lib.org> |
| |
| [ISO-8859-1] ISO/IEC DIS 8859-1. |
| '8-bit single-byte coded graphic character sets, Part 1: Latin |
| alphabet No. 1.' Technical committee / subcommittee: JTC 1 / SC 2 |
| |
| [JFIF] 'JPEG File Interchange Format, version 1.02' |
| |
| <url:http://www.w3.org/Graphics/JPEG/jfif.txt> |
| |
| [MPEG] ISO/IEC 11172-3:1993. |
| 'Coding of moving pictures and associated audio for digital storage |
| media at up to about 1,5 Mbit/s, Part 3: Audio.' |
| Technical committee / subcommittee: JTC 1 / SC 29 |
| and |
| ISO/IEC 13818-3:1995 |
| 'Generic coding of moving pictures and associated audio information, |
| Part 3: Audio.' |
| Technical committee / subcommittee: JTC 1 / SC 29 |
| and |
| ISO/IEC DIS 13818-3 |
| 'Generic coding of moving pictures and associated audio information, |
| Part 3: Audio (Revision of ISO/IEC 13818-3:1995)' |
| |
| [URL] T. Berners-Lee, L. Masinter & M. McCahill, 'Uniform Resource |
| Locators (URL)', RFC 1738, December 1994. |
| |
| <url:ftp://ftp.isi.edu/in-notes/rfc1738.txt> |
| |
| [UTF-8] F. Yergeau, 'UTF-8, a transformation format of ISO 10646', |
| RFC 2279, January 1998. |
| |
| <url:ftp://ftp.isi.edu/in-notes/rfc2279.txt> |
| |
| |
| 9. Author's Address |
| |
| Written by |
| |
| Scott Thomas Haug |
| Seattle, WA |
| USA |
