@catamphetamine/id3js v1.0.1

id3.js

id3.js is a JavaScript library for reading and parsing ID3 tags of MP3 files.

It could be used to get the information like:

• Title
• Author
• Album cover image
• etc

It parses both ID3v1 and ID3v2 tags.

It works both in Node.js and in web browsers.

See Demo.

This is an enhanced fork of the original ids3js:

• Added /browser and /node exports.
• Added getImageDataUrl() exported function.
• Added a demo page.

Install

$ npm install @catamphetamine/id3js --save

Usage

Pick a function for the task. Each function returns a Promise that resolves to an object. Example:

{
  "kind": "v2",
  "title": "REALiTi",
  "artist": "Grimes",
  "genre": "Dream Pop",
  "album": "REALiTi - Single",
  "year": "2015",
  "images": [
    {
      "type": "cover-front",
      "mime": "image/png",
      "description": null,
      "data": ArrayBuffer
    }
  ],
  "version": [
    3,
    0
  ],
  "encoder-settings": "Lavf52.39.0",
  "frames": [
    {
      "id": "TALB",
      "tag": "album",
      "value": "REALiTi - Single"
    },
    {
      "id": "TPE1",
      "tag": "artist",
      "value": "Grimes"
    },
    {
      "id": "TSSE",
      "tag": "encoder-settings",
      "value": "Lavf52.39.0"
    },
    {
      "id": "TCON",
      "tag": "genre",
      "value": "Dream Pop"
    },
    {
      "id": "TIT2",
      "tag": "title",
      "value": "REALiTi"
    },
    {
      "id": "APIC",
      "tag": "image",
      "value": {
        "type": "cover-front",
        "mime": "image/png",
        "description": null,
        "data": ArrayBuffer
      }
    }
  ]
}

Browser

From File

You may parse ID3 tags of a file input:

<input type="file"/>

import { fromFile } from '@catamphetamine/id3/browser';

document
  .querySelector('input[type="file"]')
  .addEventListener('change', async (event) => {
    const file = event.currentTarget.files[0];
    const tags = await fromFile(file);
    // tags now contains v1, v2 and merged tags
  });

This will read the data from the File instance using "slices", so the entire file is not loaded into memory but rather only the tags.

From Reader

You may parse ID3 tags of a FileReader instance:

import { fromReader } from '@catamphetamine/id3/browser';

fromReader(fileReader).then((tags) => {
  // tags now contains v1, v2 and merged tags
});

From URL

You may parse ID3 tags of a remote MP3 by URL:

import { fromUrl } from '@catamphetamine/id3/browser';

fromUrl('/audio/track.mp3').then((tags) => {
  // tags now contains v1, v2 and merged tags
});

This works by sending a HEAD request for the file and, based on the response, sending subsequent Range requests for the ID3 tags.

This is rather efficient as there is no need for the entire file to be downloaded.

The file URL must be readable by the application:

• Either located at the same domain as the application. This is called "same-origin" policy.
• Or located at another domain that allows external asynchronous HTTP requests via Cross-Origin Resource Sharing (CORS).

Browser (CDN)

This library could be imported in a web browser directly from a CDN URL. The API is the same as in non-CDN usage scenario.

<script type="module">
import * as id3 from '//unpkg.com/@catamphetamine/id3js@^1/lib/exports/browser.js';

id3.fromUrl('/audio/track.mp3').then((tags) => {
  // tags now contains v1, v2 and merged tags
});
</script>

Node

From Path

You may parse ID3 tags of a local file in Node:

import { fromPath } from '@catamphetamine/id3js/node';

fromPath('./track.mp3').then((tags) => {
  // tags now contains v1, v2 and merged tags
});

From URL

You may parse ID3 tags of a remote MP3 by URL. See "From URL" subsection of the "Browser" section of this document. Use the /node export instead of the /browser one.

From Reader

You may parse ID3 tags of a FileReader instance. See "From Reader" subsection of the "Browser" section of this document. Use the /node export instead of the /browser one.

Images

An MP3 may have images embedded in the ID3 tags. If this is the case, they can be accessed through the tag.images property and will look like so:

{
  "type": "cover-front",
  "mime": "image/jpeg",
  "description": null,
  "data": ArrayBuffer
}

As you can see, the binary image data is provided as an ArrayBuffer. To access it, you may use a DataView or typed array such as Uint8Array.

If using the binary image data is not your case, you could get a base64-encoded "data URL" of the image using the exported getImageDataUrl() function:

// Import from `/browser` or from `/node`.
import getImageDataUrl from '@catamphetamine/id3js/browser';
// import getImageDataUrl from '@catamphetamine/id3js/node';

// Get the album cover:
const dataUrl = await getImageDataUrl(tags)

// If there're several images embedded in the audio file:
let i = 0
while (i < tags.images.length) {
  const dataUrl = await getImageDataUrl(tags, i)
  i++
}

The result of the function is either null, if the image doesn't exist, or a URL like data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA... that could be rendered using a standard HTML image tag:

<img src={dataUrl}/>

Errors

It's recommended to wrap these functions' calls in a try/catch block to prevent your application from crashing if the library encounters an error while parsing an audio file.

import { fromFile } from '@catamphetamine/id3js/browser'

export default async function getAudioFileInfoFromId3Tags(file) {
  try {
    const tags = await fromFile(file)
    // tags now contains v1, v2 and merged tags
    return tags
  } catch (error) {
    // They say it might crash on some *.mp3 files
    // https://github.com/43081j/id3/pull/19
    // Catch the error so that it doesn't crash the app
    // because ID3 tags aren't essential to the app's operation.
    console.error(error)
    return {}
  }
}

License

MIT