DJWrap MPEG audio wrapping format v1.1.0 (C) Copyright 2003-2004 Oscar Sundbom REVISION HISTORY February 22, 2003 - Oscar Sundbom - Document created February 25, 2003 - Oscar Sundbom - Minor revisions March 7, 2003 - Oscar Sundbom - Copyright information added March 23, 2004 - Oscar Sundbom - Redundancy part added, copyright info slightly modified and version upped to 1.1.0. Contact information updated. April 29, 2004 - Oscar Sundbom - Added further safeguarding of data by extending the format. June 29, 2004 - Oscar sundbom - Format changed to make both tags ID3v2.4.0 COPYRIGHT This document is (C) Copyright 2003 Oscar Sundbom. It may be distributed freely, only in its entirety and as long as no modifications to its contents are made. The document may be altered ONLY if it's added upon in such a way that the contents aren't changed. This means you are fully allowed to convert it to any format necessary, i e HTML or PDF, as long as only the layout is changed, with- out making it unreadable. If layout alterations are made, the date, the name of person who did it and a description of the alterations must be added to the end of the REVISION HISTORY above. Contact information to that person must also be added to the end of this document, under the CONTACT INFORMATION heading. The information provided in this document may be used freely in any way. The authors do not, however, accept any responsibilty on the correctness of this document outside the specifics describing the DJWrap format of the version shown at the top of this document. The authors do not accept any responsibility on any harm that may occur due to the use or misuse of the information in this document. All modifications to this document, and to the format it describes, must be sent to the project's maintainer, who may at his or her discretion chose whether to accept it and add it to the next revision of this document For contact information, see the end of this document. INTRODUCTION The DJWrap format is an effort to create an open format for combining several MPEG audio streams into one, without losing information about the original files and without disturbing the stream with erroneous or misplaced data. To this is added MD5 checksumming of each individual substream as well as an extendable data format which will, to the furthest extent, provide both backward and forward compatibility. The method of combining several streams into one is, in this document, referred to as "wrapping". TERMINOLOGY/NOTATION All binary numbers are stored in big endian (Network) order and are synchsafe as described in the ID3v2 specification. This means that the highest ordered bit (bit 7) is guaranteed to be cleared (0), so that there is no chance an ID3v2 unaware file reader/player will treat it as a valid MPEG header. Binary numbers come in the following flavours: sByte: A synchsafe byte with possible values between 0 and 127. Takes 8 bits. sWord: A synchsafe word with possible values between 0 and 16383. Takes 16 bits. sQuad: A synchsafe quad with possible values between 0 and (2^28)-1. Takes 32 bits. fQuad: A synchsafe quad with possible values between 0 and (2^32)-1. Takes 40 bits. See www.id3.org for more info and terminology which is necessary to know to understand this document. FORMAT Each DJWrapped MPEG file begins with an ID3v2 tag. It is preferred that this tag is of the same version as the redundancy bit (described below) and there- fore is of version 2.4.0 or above. This tag contains all information about the file. The data is put into such a tag to maintain full compatibility with (up to date) audio players and file readers, since id3s are about the only commonly accepted metadata possible in raw MPEG audio streams. The DJWrap ID3 takes full advantage of ID3v2's possibilites and does therefore not have a fixed length. It does, however, require the first ID3 frame to be of type TENC with the contents "DJWrap File vX.Y.Z", where X, Y and Z stand for the major, minor and revision version numbers. So for a file adhering to the first version of the format, the string would read: "DJWrap File v1.0.0", excluding the quotes ("). Other than that limitation, the rest of the ordering is totally free. The file must, though, contain the following ID3 frames: §A COMM (Comment) frame containing the following text: "This file is in DJWrap format, an open format for storing multiple MPEG streams in one file. For more info, go to: http://djwrap.sourceforge.net" Several GEOB (General Encapsulated Object) frames, one for each wrapped stream, describing the file. The GEOB frames are composed of the following headers: Text encoding - One byte set to null (0). MIME Type - A null-terminated string that must be "application/djwrap" File name - A null-terminated string containing the name of the file before it was wrapped into the current file. Content description - A null-terminated string of the format "DJWrap Track n", where n is a number ordering the substream in the file. n begins at 1, not 0. Following this is the actual encapsulated object, which is merely more information about the substream and not the actual MPEG data itself. This data is stored as binary data in the following format: sWord Size Contains the length of the binary data, not including itself. fQuad Offset The offset of the substream, counting from the end of the ID3v2 tag measured in bytes. This should usually be zero for the first substream. The reason for not using the absolute offset (counting from the start of the file) is that the initial ID3 tag, which this data resides in, can grow larger as more info about the collection is added. Otherwise this value would be useless when that happens. fQuad Length The length of the substream, measured in bytes. 32xsByte MD5SUM A hexadecimal string containing the substreams MD5 sum. For more info about MD5, see RFC1321. These bytes are all ASCII characters (0-9 and A-F), so they can safely be stored in 7 bits. Total size of v1.0.0 data: 42 bytes, 44 with the Size entry. -- New in 1.1.0: fQuad MetaOff Meta offset modifier. How many bytes of the initial data of the stream is meta data (ie. ID3v2). fQuad MetaLen Meta length modifier. How many bytes of data of the stream is meta data (including the initial part described above). This considers both ID3v2 and ID3v1. 32xsByte DataMD5 An MD5 checksum, in the same format as MD5SUM above, that only regards non-meta data (ie. audio). This allows meta data to be trashed, modified and even removed without altering the verifiability of the "real" data. Total size of v1.1.0 data: 84 bytes, 86 with the Size entry. These previous entries have been added to further safe guard the data from errors, be they human or otherwise. Version 1.1.0 only considers the meta data described above in the entries to which they are described, so as not to cause confusion what to check against when things don't really measure up. To clarify: The MetaOff is the number of bytes to skip ahead and MetaLen is the number of bytes to subtract from the total size to get the number of bytes to checksum on. Any information following this before the end of the data according to Size and the end of the frame according to the frame header is to be treated as undefined but is probably the result of an update to this format. This will manifest itself by another version number in the TENC frame than that of this document. Though it is not required, it is advisable to put some padding at the end of this tag, so that other tags can be added after the wrapping without the need to rewrite the whole file. RETAGGER PROTECTION (REDUNDANCY) To add protection from buggy retagging software, which don't preserve ID3v2 frames they don't modify, a redundancy bit is, as of version 1.1.0, added to DJWrap files. These follow the format of an appended ID3v2.4.0 tag as described on http://www.id3.org, with the exception that the tag identifier is "DJW" instead of "ID3", in the header, and "WJD" instead of "3DI" in the footer. The data within the tag is of the same format as described above. This tag is appended to the end of the wrapped file and the footer should be looked for both at the end of the file and, if the stream ends in an ID3v1 tag ("TAG"), and/or ID3v2 tag (with footer), also before these tags, as they may have been added afterwards. This redundancy not only protects the meta data from certain tagging software, but also adds extra protection in transfers. If the checksum of a substream doesn't match the meta data in the beginning, it might be that the stream is corrupt or the meta data is corrupt. Software can then check against the check- sum in the redundancy tag. The off chance that both one of the tags and the stream are damaged while still matching checksums is so tiny, that it might as well happen with just one checksum. Adhering to the ID3v2 tag format, with the exception of the identifier, has the advantage that no special parser code needs to be written, as long as DJW/WJD are treated as valid ID3v2 tag identifiers. Leaving the data in the initial tag allows for unwrapping of partially transferred data, while the additional redundancy part is placed after all data, so as not to interfere with the identification and parsing of MPEG data in the file. Any wrapping software that finds a wrap containing only the redundancy part, with the initial ID3v2 tag removed, should allow its users to correct this, by adding the data from the redundancy part to any existing ID3 tag, or adding a new tag to the beginning of the file. Note to take care in identifying an existing ID3 tag as part of the wrap and not part of a substream. CONTACT INFORMATION This document, the format it describes and the whole DJWrap project is currently maintained by Oscar Sundbom. Oscar Sundbom can be reached by e-mail at: moosecomrade@users.sourceforge.net You should always be able to get the latest version of this document at the projects homepage: http://djwrap.sourceforge.net