Tags and Frames
`tags.v1` ID3v1 Frames
title
Type: string
artist
Type: string
album
Type: string
year
Type: string
comment
Type: string
track
Type: string
genre
Type: string
`tags.v2` ID3v2 Frames
Submit an issue
Note: ID3v2 Frames that are not mentioned here are not
currently supported. Feel free to submit an issue!
Note: All string-typed frames are separated by '\\' and
should not contain newline characters.
Note: If strict mode is enabled, all languages must follow
ISO 639-2.
Text information frames
ID: "T000" - "TZZZ" excluding TXXX
Type: string
Some of these frames have its own standards but are only applicable if the
strict mode is enabled.
Set frames such as "TPOS" and
"TRCK" should follow this format: '1/2' or just '1' and can be
separated '1/2\\1'.
Time frames at ID3v2.3.0 such as
"TDAT", "TIME", "TORY", and "TYER" should have
4 numerical characters.
Time frames at ID3v2.4.0 such as
"TDEN", "TDOR", "TDRC", "TDRL", and
"TDTG" should follow this format: yyyy-MM-ddTHH:mm:ss (year, "-",
month, "-", day, "T", hour (out of 24), ":", minutes, ":", seconds), but
the precision may be reduced by removing as many time indicators as wanted.
Hence valid timestamps are
yyyy, yyyy-MM,
yyyy-MM-dd, yyyy-MM-ddTHH,
yyyy-MM-ddTHH:mm, and yyyy-MM-ddTHH:mm:ss.
"TKEY" frame is represented as a
string with a maximum length of three characters. The ground keys are
represented with "A","B","C","D","E", "F" and "G" and halfkeys represented
with "b" and "#". Minor is represented as "m". Example "Cbm". Off key is
represented with an "o" only.
"TSRC" frame should have 12
alphanumeric characters.
User defined text information frame
ID: TXXX
Type: object[]
TXXX frames are parsed and must be saved as an array
[
{
description: 'Text description',
text: 'Any string here'
}
]
URL frames
ID: "W000" - "WZZZ" excluding WXXX
Type: string
If strict mode is enabled, all URLs are checked if its a valid URL.
The current RegExp used is
/^(https?):\/\/[^\s/$.?#]+\.[^\s]*/
User defined URL link frame
ID: WXXX
Type: object[]
WXXX frames are parsed and must be saved as an array
[
{
description: 'URL description',
url: 'https://github.com'
}
]
Comment and Unsynchronised lyrics frames
ID: COMM and USLT
Type: object[]
COMM and USLT frames are parsed and must be saved as an array. If the
strict mode is enabled, there should only one frame with the same language
and content descriptor.
[
{
language: 'eng',
descriptor: 'Content description',
text: 'Lyrics or comment goes here'
}
]
Attached picture frame
ID: APIC
Type: object[]
APIC frame is parsed and must be saved as an array. If strict mode is
enabled, there should only one frame with the same content descriptor, types
should be in range of 0 - 21, format should be a valid MIME type
(
/(image\/[a-z0-9!#$&.+\-^_]+){0,129}/), and description
should not exceed 64 characters.
[
{
format: 'image/jpeg', // Image MIME
type: 3, // See the APIC image types at id3.org
description: 'Content description',
data: [1, 2, 3, 4, 5, 6, 7, 8] // Image bytes
}
]
Involved People List frame
ID: IPLS
Type: string
IPLS frame is parsed and must be saved as a string
General encapsulated object frame
ID: GEOB
Type: object[]
GEOB frame is parsed and must be saved as an array. If strict mode is
enabled, there should only one frame with the same content descriptor.
[
{
format: 'application/octet-stream', // Object MIME
filename: 'filename.bin',
description: 'Content description',
object: [1, 2, 3, 4, 5, 6, 7, 8, 9] // Object bytes
}
]
Unique file identifier frame
ID: UFID
Type: object[]
UFID frame is parsed and must be saved as an array. If strict mode is
enabled, there should only one frame with the same Owner Identifier and it
must be a non-empty string, and ID bytelength must not exceed 64 bytes.
[
{
ownerId: 'http://www.id3.org/dummy/ufid.html', // Non-empty owner ID
id: [1, 2, 3, 4, 5, 6, 7] // Binary identifier
}
]
Terms of use frame
ID: USER
Type: object
USER frame is parsed and must be saved as an object.
{
language: 'eng',
text: 'Text'
}
Ownership frame
ID: OWNE
Type: object
OWNE frame is parsed and must be saved as an object. If strict mode is
enabled, date must match the format
YYYYMMDD, currencyCode must
be encoded with
ISO 4217, and
the currencyPrice must follow the format N.nn.
{
currencyCode: 'USD',
currencyPrice: '2.00',
date: '20200424', // YYYYMMDD date format
seller: 'Seller' // Seller's name
}
Play Count frame
ID: PCNT
Type: string
PCNT frame is parsed and must be saved as a numerical string
Popularimeter frame
ID: POPM
Type: object[]
POPM frame is parsed and must be saved as an array. If strict mode is
enabled, there should only one frame with the same email
[
{
email: 'john@example.com',
rating: 255, // 0 is unknown, 1 is worst, and 255 is best ratings
counter: 0 // number of times the user played this
}
]
Private frame
ID: PRIV
Type: object[]
PRIV frame is parsed and must be saved as an array. If strict mode is
enabled, there should only one frame with the same data.
[
{
ownerId: 'owner string',
data: [1, 2, 3, 4, 5, 6, 7, 8, 9] // Data bytes
}
]
Relative Volume Adjustment frame
ID: RVAD
Type: object
RVAD frame is only available in ID3v2.3.0. RVAD frame is parsed and must be
saved as an object.
{
bitsvolume: 16,
incdec: {
right: true,
left: true,
rightback: false,
leftback: false,
center: false,
bass: false
},
volumechange: {
right: [0, 1],
left: [0, 1],
rightback: [],
leftback: [],
center: [],
bass: []
},
peakvolume: {
right: [0, 1],
left: [0, 1],
rightback: [],
leftback: [],
center: [],
bass: []
}
}
Relative Volume Adjustment 2 frame
ID: RVA2
Type: object
RVA2 frame is only available in ID3v2.4.0. RVAD frame is parsed and must be
saved as an array. If strict mode is enabled, there should only one frame
with the same identification string.
[{
identification: 'identification',
channels: [{
type: 1,
volumeadjust: 16,
bitspeak: 16,
peakvolume: [0, 1]
}]
}]
Signature frame
ID: SIGN
Type: object[]
SIGN frame is only available in ID3v2.4.0. SIGN frame is parsed and must be
saved as an array. If strict mode is enabled, all frames must be unique.
[
{
group: 1,
signature: [1, 2, 3, 4, 5, 6, 7, 8, 9] // Signature bytes
}
]
Synchronised lyrics/text frame
ID: SYLT
Type: object[]
SYLT frame is parsed and must be saved as an array. If strict mode is
enabled, there should only one frame with the same language and content
descriptor, language must be encoded with
ISO 639-2,
type should be in range of 0 - 6, format should be either 1 or 2, and lyrics
must follow the format for each line: [mm:ss.xxx] String to display during
the time
[
{
language: 'eng',
format: 1,
type: 1,
descriptor: 'Descriptions',
lyrics: '[mm:ss.xxx] Synced lyrics'
}
]
// OR
[
{
language: 'eng',
format: 1,
type: 1,
descriptor: 'Descriptions',
data: [
{ line: 'LINE1', time: 200 },
{ line: 'LINE2', time: 10000 },
{ line: 'LINE3', time: 2000000 }
]
}
]
Music CD identifier frame
ID: MCDI
Type: object
MCDI frame is parsed and must be saved as an object.
{
data: [1, 2, 3, 4, 5, 6, 7, 8] // Binary bytes
}
Synchronised tempo codes frame
ID: SYTC
Type: object
SYTC frame is parsed and must be saved as an object. If strict mode is
enabled, format must be either 1 or 2.
{
format: 1,
data: [
{ bpm: 0, time: 200 },
{ bpm: 130, time: 10000 },
{ bpm: 260, time: 2000000 }
]
}
Event timing codes frame
ID: ETCO
Type: object
ETCO frame is parsed and must be saved as an object. If strict mode is
enabled, format must be either 1 or 2.
{
format: 1,
data: [
{ event: 0, time: 200 },
{ event: 130, time: 10000 },
{ event: 260, time: 2000000 }
]
}