git.maemo.org Git - someplayer/blob - src/taglib/ape/ape-tag-format.txt

   1 ================================================================================
   2 = APE Tag Specification, Version 2.000
   3 ================================================================================
   4
   5 Original Content     (C) 2004, Frank Klemm <frank.klemm@elster.offl.uni-jena.de>
   6 Formatting / Editing (C) 2004, Scott Wheeler <wheeler@kde.org>
   7
   8 ================================================================================
   9 = Contents
  10 ================================================================================
  11
  12 1   - APE Tag General Structure
  13 2   - APE Tag Header / Footer Format
  14 3   - APE Tag Flags
  15 4   - APE Tag Item Format
  16 5   - APE Tag Item Supported Keys
  17 6   - APE Tag Item Content
  18 7   - Data Types
  19 7.1 - Data Types / UTF-8
  20 7.2 - Data Types / Dates
  21 7.3 - Data Types / Timestamps
  22
  23 ================================================================================
  24 = 1 - APE Tag General Structure
  25 ================================================================================
  26
  27 Member of Basic Components of SV8 Stream Note:
  28
  29 It is strongly recommended that the data size be stored in the tags.  The size
  30 should normally be in the roughly one kilobyte, never more than 8 kilobytes.
  31
  32 Larger data should be stored externally using link entries.  Linked data is much
  33 easier to process by normal programs, so for instance JPEG data should not be
  34 included inside the audio file.
  35
  36 APE Tag Version 2.000 (with header, recommended):
  37
  38 /================================\
  39 | APE Tag Header    | 32 bytes   |
  40 |-------------------|------------|
  41 | APE Tag Item 1    | > 10 bytes |
  42 | APE Tag Item 2    | > 10 bytes |
  43 | APE Tag Item n-1  | > 10 bytes |
  44 | APE Tag Item n    | > 10 bytes |
  45 |-------------------|------------|
  46 | APE Tag Footer    | 32 bytes   |
  47 \================================/
  48
  49
  50 APE tag items should be sorted ascending by size.  When streaming, parts of the
  51 APE tag may be dropped to reduce the danger of drop outs between tracks.  This
  52 is not required, but is strongly recommended.  It would be desirable for the i
  53 tems to be sorted by importance / size, but this is not feasible.  This
  54 convention should only be broken when adding less important small items and it
  55 is not desirable to rewrite the entire tag.  An APE tag at the end of a file
  56 (the recommended location) must have at least a footer; an APE tag at the
  57 beginning of a file (strongly discouraged) must have at least a header.
  58
  59 APE Tag Version 1.000 (without header, deprecated)
  60
  61 /================================\
  62 | APE Tag Item 1    | > 10 bytes |
  63 | APE Tag Item 2    | > 10 bytes |
  64 | APE Tag Item n-1  | > 10 bytes |
  65 | APE Tag Item n    | > 10 bytes |
  66 |-------------------|------------|
  67 | APE Tag Footer    | 32 bytes   |
  68 \================================/
  69
  70 ================================================================================
  71 = 2 - APE Tag Header / Footer Format
  72 ================================================================================
  73
  74 Contains number, length and attributes of all tag items
  75
  76 Header and Footer are different in 1 bit in the Tags Flags to distinguish
  77 between them.
  78
  79 Member of APE Tag 2.0
  80
  81 /===========================================================================\
  82 | Preamble       | 8 bytes | { 'A', 'P', 'E', 'T', 'A', 'G', 'E', 'X' }     |
  83 |----------------|---------|------------------------------------------------|
  84 | Version Number | 4 bytes | 1000 = Version 1.000, 2000 = Version 2.000     |
  85 |----------------|---------|------------------------------------------------|
  86 | Tag Size       | 4 bytes | Tag size in bytes including footer and all tag |
  87 |                |         | items excluding the header (for 1.000          |
  88 |                |         | compatibility)                                 |
  89 |----------------|---------|------------------------------------------------|
  90 | Item Count     | 4 bytes | Number of items in the tag                     |
  91 |----------------|---------|------------------------------------------------|
  92 | Tag Flags      | 4 bytes | Global flags                                   |
  93 |----------------|---------|------------------------------------------------|
  94 | Reserved       | 8 bytes | Must be zeroed                                 |
  95 \===========================================================================/
  96
  97 ================================================================================
  98 = 3 - APE Tag Flags
  99 ================================================================================
 100
 101 The general flag structure for either items or headers / footers is the same.
 102 Bits 31, 30 and 29 are specific to headers / footers, whereas 2 through 0 are
 103 item specific.
 104
 105 Note: APE Tags from Version 1.0 do not use any of the following.  All flags in
 106 that version are zeroed and ignored when reading.
 107
 108 /=================================================================\
 109 | Contains Header | Bit 31      | 1 - has header | 0 - no header  |
 110 |-----------------|-------------|---------------------------------|
 111 | Contains Footer | Bit 30      | 1 - has footer | 0 - no footer  |
 112 |-----------------|-------------|---------------------------------|
 113 | Is Header       | Bit 29      | 1 - is header  | 0 - is footer  |
 114 |-----------------|-------------|---------------------------------|
 115 | Undefined       | Bits 28 - 3 | Undefined, must be zeroed       |
 116 |-----------------|-------------|---------------------------------|
 117 | Encoding        | Bits 2 - 1  | 00 - UTF-8                      |
 118 |                 |             | 01 - Binary Data *              |
 119 |                 |             | 10 - External Reference **      |
 120 |                 |             | 11 - Reserved                   |
 121 |-----------------|-------------|---------------------------------|
 122 | Read Only       | Bit 0       | 1 - read only  | 0 - read/write |
 123 \=================================================================/
 124
 125  (*) Should be ignored by tools for editing text values
 126 (**) Allowed external reference formats:
 127      - http://host/directory/filename.ext
 128      - ftp://host/directory/filename.ext
 129      - filename.ext
 130      - /directory/filename.ext
 131      - DRIVE:/directory/filename.ext
 132
 133      Note: External references are also UTF-8 encoded.
 134
 135 ================================================================================
 136 = 4 - APE Tag Item Format
 137 ================================================================================
 138
 139 APE Tag Items are stored as key-value pairs.  APE Tags Item Key are case
 140 sensitive, however it is illegal to use keys which only differ in case and
 141 it is recommended that tag reading not be case sensitive.
 142
 143 Every key can only occur (at most) once. It is not possible to repeat a key
 144 to signify updated contents.
 145
 146 Tags can be partially or completely repeated in the streaming format.  This
 147 makes it possible to display an artist and / or title if it was missed at the
 148 beginning of the stream.  It is recommended that the important information like
 149 artist, album and title should occur approximately every 2 minutes in the
 150 stream and again 5 to 10 seconds before the end.  However, care should be tak
 151 en not to replicate this information too often or during passages with high
 152 bitrate demands to avoid unnecessary drop-outs.
 153
 154 /==============================================================================\
 155 | Content Size   | 4 bytes       | Length of the value in bytes                |
 156 |----------------|---------------|---------------------------------------------|
 157 | Flags          | 4 bytes       | Item flags                                  |
 158 |----------------|---------------|---------------------------------------------|
 159 | Key            | 2 - 255 bytes | Item key                                    |
 160 |----------------|---------------|---------------------------------------------|
 161 | Key Terminator | 1 byte        | Null byte that indicates the end of the key |
 162 |----------------|---------------|---------------------------------------------|
 163 | Value          | variable      | Content (formatted according to the flags)  |
 164 \==============================================================================/
 165
 166 ================================================================================
 167
 168 Sections 5 - 7 haven't yet been converted from:
 169
 170 http://www.personal.uni-jena.de/~pfk/mpp/sv8/apetag.html