Docs

Introduction

audio-tag reads a file's tags into a metadata object that is the same for every format, and also gives you each format's own structures: ID3v2 frames, MP4 atoms, Vorbis comments, RIFF and AIFF chunks. Writing takes the same metadata shape and changes only what you pass.

• Runs anywhere. The core uses only Uint8Array, so it works the same in browsers, Node, Deno, Bun and workers. It has no dependencies.
• Exact round trips. A tag read and written back unchanged gives identical bytes, including unknown, encrypted and oddly encoded frames.
• Strict writer, tolerant reader. Problems are reported as warnings; strict: true turns them into errors.

Install

npm install audio-tag

pnpm add audio-tag

yarn add audio-tag

bun add audio-tag

There are three entry points. Each one includes everything from audio-tag.

Offline docs: the package includes this website, with the docs and the playground. Open your installed copy with npx audio-tag --open (or yarn audio-tag --open, bunx audio-tag --open). It serves on port 5173; add --port 8080 to use another one.

Usage

The "any file" functions detect the format and call the right reader or writer. Pick your runtime:

import { readFromBlob, writeToBlob } from 'audio-tag/browser'

// reads only the tag regions of large files
const { format, metadata } = await readFromBlob(file)
console.log(format, metadata.title, metadata.artist, metadata.pictures?.[0])

const updated = await writeToBlob(file, { metadata: { title: 'New title', genre: ['Rock'] } })
// a File with the same name and type; the audio is never copied into memory

import { readFile, writeFile, readID3FromFile, writeID3ToFile, removeID3FromFile } from 'audio-tag/node'

const { metadata } = await readFile('song.m4a') // the format is detected
await writeFile('song.m4a', { metadata: { album: 'Album', track: { no: 1, of: 12 } } })

const { id3v2, id3v1, lyrics3, warnings } = await readID3FromFile('song.mp3')
await writeID3ToFile('song.mp3', { metadata: { title: 'x' } }, { version: 3 })
// in place when the tag still fits, otherwise through an atomic temp-file rename
await removeID3FromFile('song.mp3', { id3v1: true })

import { read, write } from 'audio-tag'

const result = read(bytes)
if (result.format === 'flac') console.log(result.streamInfo)

const { bytes: out, inPlace } = write(bytes, { metadata: { title: 'x' } })

Note: data that is no recognised audio format (a JPEG, a text file, a bare ID3v1 tag, empty input) throws an UnknownFormatError (format-unknown) and is never changed. Use the ID3 functions for a bare ID3v1 tag. A bare ID3v2 tag counts as MPEG audio ('mpeg') and is read as one.

Functions

Every format has its own functions, and one set handles any file. Use a format's own functions when you know the format, or want its own result type and options. They refuse other formats with an error that says so.

To branch on the format yourself, call detectFormat(bytes). It returns 'mpeg', 'mp4', 'flac', 'ogg', 'aiff', 'riff' or 'unknown'.

Metadata

metadata is the same for every format. Each format maps the fields to its own frames, atoms or comments, and a field the format has no place for is rejected on write.

Also available: setSubtitle, conductor, remixer, publisher, copyright, encodedBy, encoderSettings, isrc, mood, key, encodingTime and taggingTime.

Writing

A write changes only the fields you pass. undefined leaves a field alone and null removes it:

const cover = { type: 3, mimeType: 'image/jpeg', description: '', data: jpegBytes }

const out = await writeToBlob(file, {
  metadata: {
    title: 'New title', // set
    comments: null,     // remove
    pictures: [cover],  // replace all pictures
  },
})

Besides metadata, each format takes its own input: id3v2, id3v1 and lyrics3 for ID3 files (id3v2 is also the ID3 chunk of AIFF and WAV files), and mp4, flac, ogg, aiff and riff for theirs. Options that do not apply to the file, such as version for an MP4 file, are refused instead of ignored.

Tip: the byte-level write() returns inPlace: true when the file length and the audio position did not change, so only the tag bytes need to be saved.

Results by format

read() returns a result narrowed by format. Every result has metadata, layout (the byte offsets the playground's byte map draws) and warnings, plus the format's own view:

Errors and warnings

Reading never fails on small problems: each one becomes a { code, message } entry in warnings. Errors carry a code too.

Warning: the per-format functions refuse other formats (format-mp4 from the ID3 functions, format-not-flac, format-not-riff and so on). Check with detectFormat() first, or use read() and write().

Formats

MP3 · ID3

ID3v1 and v1.1, ID3v2.2, 2.3 and 2.4, and Lyrics3 v1 and v2.00. The library covers unsynchronisation, synchsafe sizes, zlib frame compression, encryption and grouping hooks, CRC-32, tag restrictions, SEEK, appended tags with footers, every frame layout of every version, and conversion between versions. It passes all 274 cases of the official ID3v1 test suite.

MP4 · M4A

.m4a, .m4b, .mp4 and .mov files keep their tags in metadata atoms, not ID3. When the new metadata fits in the file's free space, the file is rewritten in place. Otherwise every chunk offset (stco/co64) is moved, so the audio stays playable. Ratings and play counts are rejected.

FLAC

Tags live in a Vorbis comment block (TITLE=..., repeated for several values) and picture blocks. Field names follow MusicBrainz Picard, as RFC 9639 suggests. Unchanged blocks keep their bytes, and a write uses the old padding, so it is usually in place.

Ogg

Vorbis, Opus and FLAC-in-Ogg comment headers, with the same field names as FLAC. Covers are METADATA_BLOCK_PICTURE fields. A write rewrites only the header pages, with new CRCs. A cover that needs more pages renumbers the following pages, which rewrites the whole file.

AIFF · AIFF-C

Rich metadata goes in an ID3 chunk, created at the end of the file when missing, so the sound data does not move. The NAME, AUTH, (c) , ANNO and COMT chunks are read as fallbacks, and existing NAME/AUTH/(c) chunks are kept in step (ASCII only, as the spec requires).

WAV

The same idea as AIFF: an id3 chunk for rich metadata, and the LIST/INFO list (INAM, IART, IPRD and others) as a fallback, kept in step. Several values are joined with "; ", and INFO text is ISO 8859-1 unless a CSET chunk says otherwise.

Note: some taggers put ID3 tags in front of FLAC, Ogg, AIFF or WAV files. They are kept on write and noted on read.

Where the specs disagree

The specifications contradict themselves in a few places. Each decision is marked with a // SPEC: comment in the code:

• The Lyrics3v2 page's prose says 1064 bytes and 6-digit field sizes, but its own example uses 1065 bytes and 5-digit sizes. The example wins.
• The v2.3 LINK frame lists a 3-byte frame ID; the reader accepts 3 or 4 bytes.
• Genres 126 to 147 are only named by the official test suite.
• Apple's QuickTime spec defines only mdta metadata. The iTunes item list follows ExifTool, mutagen, AtomicParsley and Picard.
• The spec gives no unit for v2.3 RVAD/EQUA values, so they are not converted to v2.4 RVA2/EQU2.
• RFC 9639 defines no Vorbis comment field names, so they come from MusicBrainz Picard, as the RFC suggests.
• No AIFF spec defines the ID3 chunk; it is implemented as ExifTool documents it.
• RIFF INFO text is ISO 8859-1 by the spec, but many writers put UTF-8 there. Valid UTF-8 is read as UTF-8, with a warning.
• RFC 3533 gives a page on which no packet ends a granule position of -1, while the Vorbis spec says header pages have 0. Header pages get 0, or -1 when no packet ends on them.

Field mapping

Where each metadata field is written in each format. AIFF and WAV files keep every field in their ID3 chunk, as the ID3v2 columns show; the WAV INFO and AIFF text columns are the extra copies kept in step when the file already has those chunks. MP4 freeform items are shown as ----:NAME; their full key is ----:com.apple.iTunes:NAME.

ID3v2 frames

Every frame of ID3v2.2, v2.3 and v2.4 is read, written and validated, along with the chapter and accessibility addenda and 8 common unofficial frames (RGAD, XRVA, and iTunes' TCMP and sort-order frames). Frames the library does not know are kept byte for byte.

ID3v1 genres

How tags are built

The byte layout of every structure the library reads and writes, as the specs define it. Sizes are in bytes; BE and LE mean big- and little-endian. The playground's byte map shows these regions in your own files.

ID3v2

Frame headers: v2.2 is ID (3) · size (3); v2.3 is ID (4) · size (4, plain BE) · flags (2); v2.4 is ID (4) · size (4, synchsafe) · flags (2).

Text encodings: $00 ISO-8859-1, $01 UTF-16 with BOM, and in v2.4 also $02 UTF-16BE and $03 UTF-8.

ID3v1 · Lyrics3

Lyrics3 sits just before the ID3v1 tag: v1 is "LYRICSBEGIN" · lyrics · "LYRICSEND"; v2.00 is "LYRICSBEGIN" · fields (3-letter ID, 5-digit size, data) · size of the tag (6 digits) · "LYRICS200".

MP4

Every atom is size (4, BE, including the header) · type (4) · data. The iTunes items live in moov/udta/meta/ilst (handler mdir), one atom per item, each with a data atom: type (4) · locale (4) · value. Freeform items (----) add mean and name atoms. When the metadata grows and no free space is left, every chunk offset in stco (32-bit) and co64 (64-bit) is updated so the audio is still found.

FLAC · Vorbis

A FLAC file starts with "fLaC", then metadata blocks (header: last-block flag (1 bit) · type (7 bits) · length (24 bits, BE)), then the audio frames. A Vorbis comment is vendor length (4, LE) · vendor · number of fields (4, LE) · each field: length (4, LE) · NAME=value in UTF-8.

Ogg

Each page is "OggS" · version · header type · granule position (8, LE) · serial (4) · sequence (4) · CRC-32 (4) · number of segments · segment table, then the data. The comment packet is the codec's second header packet: 0x03 "vorbis" for Vorbis, "OpusTags" for Opus, a VORBIS_COMMENT block for FLAC in Ogg.

WAV

"RIFF" · size (4, LE) · "WAVE" · chunks: ID (4) · size (4, LE) · data, plus a pad byte when the size is odd. fmt holds the format, data the audio, LIST (type INFO) the text tags, id3 a whole ID3v2 tag.

AIFF

"FORM" · size (4, BE) · "AIFF" or "AIFC" · chunks: ID (4) · size (4, BE) · data, plus a pad byte when the size is odd. COMM holds channels, sample frames, sample size and rate, SSND the audio, NAME/AUTH/(c) /ANNO/COMT the text, ID3 a whole ID3v2 tag.

Low-level ID3 API

Build, validate, convert and serialize ID3v2 tags frame by frame. Every frame type is a member of a discriminated union (frame.type), with fields named as in the spec.

import { createTag, createFrame, TextEncoding, validateID3v2, writeID3v2, readID3v2, convertID3v2 } from 'audio-tag'

const tag = createTag(4, [
  createFrame('text', 'TIT2', { encoding: TextEncoding.UTF8, values: ['Title'] }),
])
const issues = validateID3v2(tag)          // [] when valid; each issue cites its section
const { bytes } = writeID3v2(tag, { padding: 1024 })
const parsed = readID3v2(bytes)            // { tag, warnings, totalSize }
const { tag: v23 } = convertID3v2(tag, 3)  // TDRC -> TYER/TDAT/TIME, UTF-8 -> UTF-16

Bundle sizes

Each bundle loads on its own, raw and gzipped as served. Importing only the functions you need lets a bundler drop the other formats; npm run size measures single imports against their budgets.

Build info

Each build writes dist/build-info.json: the version, the git commit, the build time and the byte sizes above. This page shows version 0.1.0, built 2026-10-10.