node-id3

To use node-id3 in your project, install it using npm:

npm install node-id3

Use NodeID3.write(tags, filepath) to write tags to an existing file. Warning: This method removes all existing tags in the file and replaces them with the provided tags object. It returns true on success or throws an Error.

const NodeID3 = require('node-id3')
const tags = {
    title: "Tomorrow",
    artist: "Kevin Penkin",
    album: "TVアニメ「メイドインアビス」オリジナルサウンドトラック",
    APIC: "./example/mia_cover.jpg",
    TRCK: "27"
}
const filepath = './path/to/(mp3)file'

const success = NodeID3.write(tags, filepath)

If you are working with file buffers instead of file paths, use NodeID3.write(tags, filebuffer). This returns a new Buffer containing the file with the new tags. It will remove existing tags and add yours.

const NodeID3 = require('node-id3')
const filebuffer = Buffer.from("Some Buffer of a (mp3) file")
const tags = { title: "Tomorrow" }

const newBuffer = NodeID3.write(tags, filebuffer)

To strip all ID3 metadata:

• Use NodeID3.removeTags(filepath) to remove tags from a file. Returns true or Error.
• Use NodeID3.removeTagsFromBuffer(filebuffer) to return a new Buffer without the ID3 frames.

const NodeID3 = require('node-id3')

// From file
NodeID3.removeTags('./path/to/file.mp3')

// From buffer
const cleanBuffer = NodeID3.removeTagsFromBuffer(filebuffer)

Use NodeID3.create(tags) to generate a standalone Buffer containing only the ID3 tags. This is useful if you want to manually prepend the tags to a file or stream.

const NodeID3 = require('node-id3')
const tags = { title: "Tomorrow" }

const tagBuffer = NodeID3.create(tags)

Use NodeID3.update(tags, target) to modify tags without removing existing ones. It will overwrite existing tags that match the keys in your tags object but preserve others. target can be a filepath or a filebuffer.

Options:

• include: Array of tag names to read (default: all).
• exclude: Array of tag names to ignore (default: []).

Return Values:

• For filepath: Returns true or Error.
• For filebuffer: Returns a new Buffer.

const NodeID3 = require('node-id3')
const tags = { title: "New Title" }
const options = {
    include: ['TALB', 'TIT2'],
    exclude: ['APIC']
}

// Update file
NodeID3.update(tags, './path/to/file.mp3', options)

// Update buffer
const updatedBuffer = NodeID3.update(tags, filebuffer, options)

Use NodeID3.read(file, options) to extract tags. file can be a file path or a buffer.

Options:

• include: Array of tags to read.
• exclude: Array of tags to ignore.
• onlyRaw: Boolean. If true, returns only the raw object (default: false).
• noRaw: Boolean. If true, does not generate the raw object (default: false).

Return Format: Returns an object containing title, artist, album, image (with mime, type, description, and imageBuffer), and a raw object containing the original ID3 frame IDs (e.g., TIT2, TPE1).

const NodeID3 = require('node-id3')
const tags = NodeID3.read('./path/to/file.mp3')

/* 
Example output structure:
{
    title: "Tomorrow",
    artist: "Kevin Penkin",
    image: { mime: "image/jpeg", ... },
    raw: { TIT2: "Tomorrow", TPE1: "Kevin Penkin" }
}
*/

Starting with v0.2, you can use the Promise-based API by accessing the .Promise property on the main module. This allows you to use async/await syntax for all core methods.

const NodeID3Promise = require('node-id3').Promise

async function manageTags() {
    const tags = { title: 'New Title' }
    await NodeID3Promise.write(tags, './file.mp3')
    const readTags = await NodeID3Promise.read('./file.mp3')
    await NodeID3Promise.removeTags('./file.mp3')
}

The update() function merges new tags into existing ones. It is useful when you only want to change specific fields without overwriting the entire tag set.

• Behavior: It reads the current tags, applies the new values, and writes the result back to the file or buffer.
• Synchronous usage: update(tags, filebuffer, options).
• Asynchronous usage: update(tags, filebuffer, options, callback).
• Options: The options object can be used to control how updates are handled (e.g., for multiple-value frames).

Note: update() automatically maps common aliases to their correct ID3v2.3 frame identifiers.

const NodeID3 = require('node-id3');

const tags = {
  title: 'New Title'
};

// Updates only the title in the existing file
NodeID3.update(tags, './music.mp3');

The read() function extracts ID3 tags from a file path or a Buffer.

• Synchronous usage: read(filebuffer, options). Returns an object containing the tags.
• Asynchronous usage: read(filebuffer, options, callback). The callback receives (error, tags).
• Options: An optional object to configure the reading process.

If filebuffer is a string, it reads the file from disk. If it is a Buffer, it reads from the provided memory buffer.

const NodeID3 = require('node-id3');

// Synchronous read
const tags = NodeID3.read('./music.mp3');
console.log(tags);

// Asynchronous read
NodeID3.read('./music.mp3', (error, tags) => {
  if (error) console.error(error);
  else console.log(tags);
});

The write() function allows you to write a set of tags to either a file path (string) or a Buffer.

• Synchronous usage: Call write(tags, filebuffer). It returns true on success, a Buffer if a buffer was passed, or an Error object.
• Asynchronous usage: Pass a callback function as the third argument: write(tags, filebuffer, callback).

If filebuffer is a string, the function reads the file, removes existing tags, prepends the new tags, and writes the file back using 'binary' encoding.

const NodeID3 = require('node-id3');

const tags = {
  title: 'Song Title',
  artist: 'Artist Name'
};

// Synchronous write to a file
NodeID3.write(tags, './music.mp3');

// Asynchronous write to a file
NodeID3.write(tags, './music.mp3', (error) => {
  if (error) console.error(error);
  else console.log('Tags written successfully');
});