Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
B

browser-id3-writer

> 编程语言
Open source

JavaScript library for writing ID3 tag to MP3 files in browsers and Node.js

198 stars0 likes1 views
WebsiteGitHub

About

JavaScript library for writing ID3 tag to MP3 files in browsers and 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 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

JavaScriptbrowserid3javascriptlibrary

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

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