1
================================================================================
2
= APE Tag Specification, Version 2.000
3
================================================================================
5
Original Content (C) 2004, Frank Klemm <frank.klemm@elster.offl.uni-jena.de>
6
Formatting / Editing (C) 2004, Scott Wheeler <wheeler@kde.org>
8
================================================================================
10
================================================================================
12
1 - APE Tag General Structure
13
2 - APE Tag Header / Footer Format
15
4 - APE Tag Item Format
16
5 - APE Tag Item Supported Keys
17
6 - APE Tag Item Content
19
7.1 - Data Types / UTF-8
20
7.2 - Data Types / Dates
21
7.3 - Data Types / Timestamps
23
================================================================================
24
= 1 - APE Tag General Structure
25
================================================================================
27
Member of Basic Components of SV8 Stream Note:
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.
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.
36
APE Tag Version 2.000 (with header, recommended):
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
\================================/
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.
59
APE Tag Version 1.000 (without header, deprecated)
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
\================================/
70
================================================================================
71
= 2 - APE Tag Header / Footer Format
72
================================================================================
74
Contains number, length and attributes of all tag items
76
Header and Footer are different in 1 bit in the Tags Flags to distinguish
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
\===========================================================================/
97
================================================================================
99
================================================================================
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
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.
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
\=================================================================/
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
130
- /directory/filename.ext
131
- DRIVE:/directory/filename.ext
133
Note: External references are also UTF-8 encoded.
135
================================================================================
136
= 4 - APE Tag Item Format
137
================================================================================
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.
143
Every key can only occur (at most) once. It is not possible to repeat a key
144
to signify updated contents.
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.
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
\==============================================================================/
166
================================================================================
168
Sections 5 - 7 haven't yet been converted from:
170
http://www.personal.uni-jena.de/~pfk/mpp/sv8/apetag.html