@calme1709/id3-js

ID3-JS

A library for reading and writing ID3 data.

How to use

---

First install the package

npm install --save @calme1709/id3-js

And then include the package in your code

import ID3JS from "@calme1709/id3-js";

or

const ID3JS = require("@calme1709/id3-js");

You can then proceed to use the library in your project

Writing ID3 data

---

Writing ID3 data replaces all the existing data with the data that is passed to the method. If you only want to replace the defined data and leave the rest as it is, use the update method.

Write to a file

import ID3JS from "@calme1709/id3-js";

ID3JS.write("./song.mp3", {
    title: "Song",
    artist: "Artist"
});

Write to a buffer

import fs from "fs";
import ID3JS from "@calme1709/id3-js";

let buffer = fs.readFileSync("./song.mp3");

buffer = ID3JS.write(buffer, {
    title: "Song",
    artist: "Artist"
});

Reading ID3 data

---

Read from a file

import ID3JS from "@calme1709/id3-js";

ID3JS.read("./song.mp3");

Read from a buffer

import fs from "fs";
import ID3JS from "@calme1709/id3-js";

const buffer = fs.readFileSync("./song.mp3");

ID3JS.read(buffer);

Updating ID3 data

---

Updating ID3 data only affects those properties which are defined in the new information, the existing data that will not be overwritten is left unaffected.

Update a file

import ID3JS from "@calme1709/id3-js";

ID3JS.update("./song.mp3", {
    title: "Song",
    artist: "Artist"
});

Update a buffer

import fs from "fs";
import ID3JS from "@calme1709/id3-js";

let buffer = fs.readFileSync("./song.mp3");

buffer = ID3JS.update(buffer, {
    title: "Song",
    artist: "Artist"
});

Removing ID3 data

---

Remove data from a file

import ID3JS from "@calme1709/id3-js";

ID3JS.remove("./song.mp3");

Remove data from a buffer

import fs from "fs";
import ID3JS from "@calme1709/id3-js";

let buffer = fs.readFileSync("./song.mp3");

buffer = ID3JS.remove(buffer);

Methods

---

write()

Writes the specified information to either the file at the passed path, or the passed buffer. Overwrites all information currently in the file, if you want to leave non defined information unaffected use the update method.

Overloads

Call	Description	Return
write(string, IFrames)	Writes the information passed to the file at the passed path, overwriting any existing data. Returns nothing.	undefined
write(buffer, IFrames)	Writes the information passed to the passed buffer and returns it.	Buffer

read()

Reads the ID3 information from the file at the passed path, or from the passed buffer.

Overloads

Call	Description	Return
read(string)	Reads the data from the file at the passed path and returns it.	IFrames
read(buffer)	Reads the data from the passed buffer and returns it.	IFrames

update()

Writes the specified information to either the file at the passed path, or the passed buffer. Leaves all information that is not defined untouched.

Overloads

Call	Description	Return
update(string, IFrames)	Writes the information passed to the file at the passed path. Returns nothing.	undefined
update(buffer, IFrames)	Writes the information passed to the passed buffer and returns it.	Buffer

remove()

Removes all ID3 data from either the file at the passed path, or the passed buffer.

Overloads

Call	Description	Return
remove(string)	Removes all ID3 data from the file at the passed path.	undefined
remove(buffer)	Removes all ID3 data from the passed buffer and returns it.	Buffer

Supported properties

---

Information in ID3 can be either of two types; either a standard text frame, or a special frame. Below is all of the properties that can be set, to make the usage of this library easier, all properties have been mapped to aliases, however the raw names will be supported in a future update.

Text Properties

• album
• bpm
• composer
• genre
• copyright
• date
• playlistDelay
• encodedBy
• textWriter
• fileType
• time
• contentGroup
• title
• subtitle
• initialKey
• language
• length
• mediaType
• originalTitle
• originalFilename
• originalTextwriter
• originalArtist
• originalYear
• fileOwner
• artist
• performerInfo
• conductor
• remixArtist
• partOfSet
• publisher
• trackNumber
• recordingDates
• internetRadioName
• internetRadioOwner
• size
• ISRC
• encodingTechnology
• year

Special Properties

There are four special properties supported, these are below with their types.

• comment: {     text: string;     language: string;     shortText: string; }

• image: Buffer

• unsynchronisedLyrics: {     text: string;     language: string;     shortText: string; }

• userDefinedText {     description: string;     value: string; }