JavaScript 库用于在浏览器中向 MP3 文件写入 ID3 标签,以及 Node.js
JavaScript library for writing ID3 (v2.3) tag to MP3 files in browsers and Node.js. It can't read the tag so use another lib to do it.
Note: the library removes existing ID3 tag (v2.2, v2.3 and v2.4).
Here is an online demonstration: egoroof.github.io/browser-id3-writer/
Find the changelog in CHANGELOG.md
Take latest version here or with npm:
npm install browser-id3-writer --saveThe library is only deployed in native JS modules, so in browsers you have to use script with type module:
Or bundle the library to your code.
In Nodejs it imports easily:
import { ID3Writer } from 'browser-id3-writer';In browsers you should first get ArrayBuffer of the song you would like to add ID3 tag.
For example you can create file input and add change event listener:
If you want to get arrayBuffer from a remote server you can use Fetch:
const request = await fetch(urlToSongFile);
if (!request.ok) {
// handle error
console.error(`Unable to fetch ${urlToSongFile}`);
}
const arrayBuffer = await request.arrayBuffer();
// go nextCreate a new ID3Writer instance with arrayBuffer of your song, set frames and add a tag:
// arrayBuffer of song or empty arrayBuffer if you just want only id3 tag without song
const writer = new ID3Writer(arrayBuffer);
writer
.setFrame('TIT2', 'Home')
.setFrame('TPE1', ['Eminem', '50 Cent'])
.setFrame('TALB', 'Friday Night Lights')
.setFrame('TYER', 2004)
.setFrame('TRCK', '6/8')
.setFrame('TCON', ['Soundtrack'])
.setFrame('TBPM', 128)
.setFrame('WPAY', 'https://google.com')
.setFrame('TKEY', 'Fbm')
.setFrame('APIC', {
type: 3,
data: coverArrayBuffer,
description: 'Super picture',
});
writer.addTag();Now you can save it to file as you want:
const taggedSongBuffer = writer.arrayBuffer;
const blob = writer.getBlob();
// or if you need url
const url = URL.createObjectURL(blob);For example you can save file using FileSaver.js:
saveAs(blob, 'song with tags.mp3');If you are writing chromium extension you can save file using Downloads API:
chrome.downloads.download({
url: url,
filename: 'song with tags.mp3',
});
// when finish downloading - clean memory
URL.revokeObjectURL(url);Simple example with blocking IO:
…You can also create only ID3 tag without song and use it as you want:
const writer = new ID3Writer(Buffer.alloc(0));
writer.padding = 0; // default 4096
writer.setFrame('TIT2', 'Home');
writer.addTag();
const id3Buffer = Buffer.from(writer.arrayBuffer);array of strings:
string
integer
object
writer.setFrame('COMM', {
description: 'description here',
text: 'text here',
language: 'eng',
});writer.setFrame('USLT', {
description: 'description here',
lyrics: 'lyrics here',
language: 'eng',
});writer.setFrame('IPLS', [
['role', 'name'],
['role', 'name'],
// ...
]);writer.setFrame('SYLT', {
type: 1,
text: [
['lyrics here', 0],
['lyrics here', 3500],
// ...
],
timestampFormat: 2,
language: 'eng',
description: 'description',
});text is an array of arrays of string and integer.
writer.setFrame('TXXX', {
description: 'description here',
value: 'value here',
});writer.setFrame('WXXX', {
description: 'description here',
value: 'https://google.com',
useUnicodeEncoding: false,
});The URL is always encoded as ISO-8859-1, as the spec requires. Only the
description follows useUnicodeEncoding, which behaves like it does on APIC:
set it to true only when the description contains non-Western characters,
as some readers apply the encoding to the URL as well and will not read it
back correctly.
writer
.setFrame('CHAP', {
id: 'chp0',
startTime: 0, // milliseconds
endTime: 3500,
startOffset: 0, // bytes, optional
endOffset: 1024,
subFrames: {
TIT2: 'Intro',
WXXX: { description: 'chapter url', value: 'https://google.com' },
},
})
.setFrame('CTOC', {
id: 'toc0',
ordered: true,
topLevel: true,
childElementIds: ['chp0'],
subFrames: { TIT2: 'Table of contents' },
});Both are defined by the
ID3v2 Chapter Frame Addendum rather than
the main spec. subFrames is optional and keyed by frame id; TIT2, TIT3,
TXXX, WXXX and APIC may be embedded. A CTOC frame can hold at most 255
entries because the entry count is stored in a single byte.
startOffset and endOffset are optional. Byte offsets are often not known
and stop being correct as soon as the audio is re-encoded, so when they are
omitted they are written as 0xFFFFFFFF, which the spec defines as "ignore
this and use the time instead".
writer.setFrame('PRIV', {
id: 'identifier',
data: dataArrayBuffer,
});writer.setFrame('APIC', {
type: 3,
data: coverArrayBuffer,
description: 'description here',
useUnicodeEncoding: false,
});useUnicodeEncoding should only be true when description contains non-Western characters.
When it's set to true some program might not be able to read the picture correctly.
See #42.
| Type | Name |
|---|---|
| 0 | Other |
| 1 | 32x32 pixels 'file icon' (PNG only) |
| 2 | Other file icon |
| 3 | Cover (front) |
| 4 | Cover (back) |
| 5 | Leaflet page |
| 6 | Media (e.g. label side of CD) |
| 7 | Lead artist/lead performer/soloist |
| 8 | Artist/performer |
| 9 | Conductor |
| 10 | Band/Orchestra |
| 11 | Composer |
| 12 | Lyricist/text writer |
| 13 | Recording location |
| 14 | During recording |
| 15 | During performance |
| 16 | Movie/video screen capture |
| 17 | A bright coloured fish |
| 18 | Illustration |
| 19 | Band/artist logotype |
| 20 | Publisher/Studio logotype |
| Type | Name |
|---|---|
| 0 | Other |
| 1 | Lyrics |
| 2 | Text transcription |
| 3 | Movement/part name (e.g. "Adagio") |
| 4 | Events (e.g. "Don Quijote enters the stage") |
| 5 | Chord (e.g. "Bb F Fsus") |
| 6 | Trivia/'pop up' information |
| Type | Name |
|---|---|
| 1 | Absolute time, 32 bit sized, using MPEG frames as unit |
| 2 | Absolute time, 32 bit sized, using milliseconds as unit |
暂无开放 Issues,或尚未同步最近议题。