百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
B

browser-id3-writer

> 编程语言
开源

JavaScript 库用于在浏览器中向 MP3 文件写入 ID3 标签,以及 Node.js

198 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

JavaScript 库用于在浏览器中向 MP3 文件写入 ID3 标签,以及 Node.js

Browser ID3 Writer

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

Table of Contents

  • Installation
    • JS modules
  • Usage
    • Browser
      1. Get ArrayBuffer of song
      2. Add a tag
      3. Save file
    • Node.js
  • Supported frames
  • APIC picture types
  • SYLT content types
  • SYLT timestamp formats

Installation

Take latest version here or with npm:

bash
npm install browser-id3-writer --save

JS modules

The library is only deployed in native JS modules, so in browsers you have to use script with type module:

xml

Or bundle the library to your code.

In Nodejs it imports easily:

javascript
import { ID3Writer } from 'browser-id3-writer';

Usage

Browser

Get ArrayBuffer of song

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:

xml

If you want to get arrayBuffer from a remote server you can use Fetch:

javascript
const request = await fetch(urlToSongFile);
if (!request.ok) {
  // handle error
  console.error(`Unable to fetch ${urlToSongFile}`);
}
const arrayBuffer = await request.arrayBuffer();
// go next

Add a tag

Create a new ID3Writer instance with arrayBuffer of your song, set frames and add a tag:

javascript
// 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();

Save file

Now you can save it to file as you want:

javascript
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:

javascript
saveAs(blob, 'song with tags.mp3');

If you are writing chromium extension you can save file using Downloads API:

javascript
chrome.downloads.download({
  url: url,
  filename: 'song with tags.mp3',
});

// when finish downloading - clean memory
URL.revokeObjectURL(url);

Node.js

Simple example with blocking IO:

…

You can also create only ID3 tag without song and use it as you want:

javascript
const writer = new ID3Writer(Buffer.alloc(0));
writer.padding = 0; // default 4096
writer.setFrame('TIT2', 'Home');
writer.addTag();
const id3Buffer = Buffer.from(writer.arrayBuffer);

Supported frames

array of strings:

  • TPE1 (song artists)
  • TCOM (song composers)
  • TCON (song genres)

string

  • TLAN (language)
  • TIT1 (content group description)
  • TIT2 (song title)
  • TIT3 (song subtitle)
  • TALB (album title)
  • TPE2 (album artist)
  • TPE3 (conductor/performer refinement)
  • TPE4 (interpreted, remixed, or otherwise modified by)
  • TRCK (song number in album): '5' or '5/10'
  • TPOS (album disc number): '1' or '1/3'
  • TPUB (label name)
  • TKEY (initial key)
  • TMED (media type)
  • TDAT (album release date expressed as 'DDMM')
  • TSRC (isrc - international standard recording code)
  • TSSE (software/hardware and settings used for encoding)
  • TCOP (copyright message)
  • TCMP (iTunes compilation flag)
  • TEXT (lyricist / text writer)
  • WCOM (commercial information)
  • WCOP (copyright/Legal information)
  • WOAF (official audio file webpage)
  • WOAR (official artist/performer webpage)
  • WOAS (official audio source webpage)
  • WORS (official internet radio station homepage)
  • WPAY (payment)
  • WPUB (publishers official webpage)

integer

  • TLEN (song duration in milliseconds)
  • TYER (album release year)
  • TBPM (beats per minute)

object

  • COMM (comments):
javascript
writer.setFrame('COMM', {
  description: 'description here',
  text: 'text here',
  language: 'eng',
});
  • USLT (unsychronised lyrics):
javascript
writer.setFrame('USLT', {
  description: 'description here',
  lyrics: 'lyrics here',
  language: 'eng',
});
  • IPLS (involved people list):
javascript
writer.setFrame('IPLS', [
  ['role', 'name'],
  ['role', 'name'],
  // ...
]);
  • SYLT (synchronised lyrics):
javascript
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.

  • TXXX (user defined text):
javascript
writer.setFrame('TXXX', {
  description: 'description here',
  value: 'value here',
});
  • WXXX (user defined URL):
javascript
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.

  • CHAP (chapter) and CTOC (table of contents):
javascript
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".

  • PRIV (private frame):
javascript
writer.setFrame('PRIV', {
  id: 'identifier',
  data: dataArrayBuffer,
});
  • APIC (attached picture):
javascript
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.

APIC picture types

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

SYLT content types

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

SYLT timestamp formats

Type Name
1 Absolute time, 32 bit sized, using MPEG frames as unit
2 Absolute time, 32 bit sized, using milliseconds as unit

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

JavaScriptbrowserid3javascriptlibrary

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言