npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mp3tag

v1.0.5

Published

A library for reading/writing mp3 tag data

Downloads

183

Readme

mp3tag - A mp3 tag editing library

This library is not a complete implementation for all ID3 tags. It has basic support for the most common v2.3 and v2.4 features. More advanced features, like frame encryption are not yet supported.

Detailed information about the meaning of certain frame fields/flags can be found in the file format reference at: http://id3.org/id3v2.3.0

Check out retagger for an example project on how to use this library.

Basic CLI usage

Installation:

npm install -g mp3tag

Help command:

mp3tag --help

Printing out the most common tags and an overview of the available tags:

mp3tag --in "./input.mp3" --show-data

Saving the cover image into a file:
If no fileName is provided then the file is exported as cover.png or cover.jpeg depending on the cover's MIME type.

mp3tag --in "./input.mp3" --export-cover [fileName]

Setting a new album and writing the changes into a new file:
If no output file is provided, the changes are written back into the input file. If possible without rewriting the whole file (if the file has a padding area).

mp3tag --in "./input.mp3" --set-album "test" --write "./output.mp3"

Basic API usage (using async/await)

Install dependency:

npm install --save mp3tag

Code example:

const mp3tag = require('mp3tag');
const tagData = await mp3tag.readHeader('./file.mp3');

const buffer = tagData.getFrameBuffer('TALB');
if (buffer) {
  console.log("Album: " + tagData.decoder.decodeString(buffer));
} else {
  console.log("No album frame");
}

API

mp3tag.readHeader(path:string) -> Promise<TagData>

Reads in the source file at the specified path and returns a promise, which resolves to the parsed TagData object.

All frames are loaded into memory when constructing this object so that the frame content can be read/written without performing any File-IO.

TagData.getDecoder() -> Decoder

Returns the Decoder object, which can be used to decode/encode the binary frame buffers.

TagData.getFrame(id:string) -> Frame

If the parsed file contains a frame with the given id then it is returned. When accessing the Frame's content, getFrameBuffer()/setFrameBuffer() should be used instead.

TagData.getFrames(id:string) -> Frame[]

Returns all frames, which have the given frame id. (A mp3 file may contain multiple frames with the same id)

TagData.getFrameBuffer(id:string) -> Buffer

Directly returns the frame content as Buffer. The frame's buffer should only be modified using setFrameBuffer() to ensure proper frame alignment.

The binary frame content of text frames can be decoded as follows: tagData.decoder.decodeString(buffer)

TagData.getFrameBuffers(id:string) -> Buffer[]

Same as getFrameBuffer() but may return multiple Buffer objects if there are multiple Frames with the same id.

TagData.setFrameBuffer(id:string, buffer:Buffer)

Assigns the given Buffer object as the frame's new content. The frame will be created if the has no such frame and the frame will be resized to fit the passed buffer. The buffer is only assigend by reference and not copied, so modifying the assigned buffer will modify the frame's content.

TagData.removeFrame(id:string)

Removes all frames with the given id.

TagData.getAudioBuffer() -> Promise<Buffer>

Loads the whole audio data from the file into a Buffer and returns a promise, which resolves to this buffer.

TagData.save() -> Promise<void>

Writes all changes back into the source file. When writing back the changes, the file's padding area resized to accomodate all changes without rewriting the audio data if possible.

TagData.writeToFile(path:string) -> Promise<void>

Writes the change frames and audio data into the specified file.

Decoder.decodeString(buffer:Buffer) -> string

Decodes the content of text frames. The buffer's first byte specifies the used buffer encoding and the remaining bytes are treated as string content.

Ids of text frames typically start with T (eg. TALB)

Decoder.decodeComment(buffer:Buffer) -> Comment

The decoded comment object contains three string properties: {language,short,long}

The comment is stored in the COMM frame.

Decoder.encodeComment(comment:Comment) -> Buffer

Encodes a comment object back into a buffer.

Decoder.decodePopularity(buffer:Buffer) -> Popularity

The decoded popularity object has the following fields:

  • email:string - The user's email
  • rating:number - Rating value [0-255]
  • playCount:number - Number of times this has been played.

The popularity object is stored in the POPM frame.

Decoder.decodePicture(buffer:Buffer) -> Picture

The decoded picture object contains the following properties:

  • mimeType:string
  • pictureType:number - 0x3 = cover picture
  • description:string
  • pictureData:Data - a reference to the picture's data, which is basically a Buffer wrapper. The buffer can be retrieved by calling toBuffer() on it.

The picture is stored in the APIC frame.

Decoder.encodePicture(picture:Picture) -> Buffer

Encodes a given picture data (see above) into a buffer to be written into an APIC frame.