jsmediatags

The onSuccess callback returns an object containing the tag type, version, and a tags object. The tags object contains both human-readable shortcuts and raw tag data.

Common Structure:

{
  "type": "<the tag type: ID3, MP4, etc.>",
  "tags": {
    "<shortcut name>": "<points to a tags data>",
    "<tag name>": {
      "id": "<tag name>",
      "data": "<the actual tag data>"
    }
  }
}

Supported Shortcuts:

• title
• artist
• album
• year
• comment
• track
• genre
• picture
• lyrics

You can include the library in your web application by copying dist/jsmediatags.min.js into your project and adding a <script> tag, or by using cdnjs.

Once loaded, you can access it via the global window.jsmediatags object or as a CommonJS module if using a bundler.

// As a global Object
var jsmediatags = window.jsmediatags;

// As a CommonJS Module
var jsmediatags = require("jsmediatags");

React Native requires buffer and react-native-fs as additional dependencies:

npm install --save jsmediatags buffer react-native-fs

To use jsmediatags in a NodeJS environment, install it via npm:

npm install jsmediatags --save

The simple API fetches all available tags for a given file path. Use jsmediatags.read(file, options) where options contains onSuccess and onError callbacks.

// Simple API - will fetch all tags
var jsmediatags = require("jsmediatags");

jsmediatags.read("./music-file.mp3", {
  onSuccess: function(tag) {
    console.log(tag);
  },
  onError: function(error) {
    console.log(':(', error.type, error.info);
  }
});

To optimize performance by reading only specific tags, instantiate a new jsmediatags.Reader(path), call .setTagsToRead([...]) with an array of tag names, and then call .read(options). The options object includes an onSuccess callback where the requested tags are accessible via tag.tags.

new jsmediatags.Reader("filename.mp3")
  .setTagsToRead(["COMM", "TCON", "WXXX"])
  .read({
    onSuccess: function(tag) {
      var tags = tag.tags;
      alert(tags.COMM.data + " - " + tags.TCON.data + ", " + tags.WXXX.data);
    }
  });

To read all available tags from a media file, use the jsmediatags.read() method. The method accepts a file path (or URL) and an options object containing an onSuccess callback. The callback receives a tag object, where the actual metadata is located in tag.tags.

jsmediatags.read("filename.mp3", {
  onSuccess: function(tag) {
    var tags = tag.tags;
    alert(tags.artist + " - " + tags.title + ", " + tags.album);
  }
});

Usage in React Native is identical to the standard API. You can use the callback pattern or wrap the Reader in a Promise for async/await compatibility.

const jsmediatags = require('jsmediatags');

new jsmediatags.Reader('/path/to/song.mp3')
  .read({
    onSuccess: (tag) => {
      console.log('Success!');
      console.log(tag);
    },
    onError: (error) => {
      console.log('Error');
      console.log(error);
    }
  });

// Or wrap it with a promise
new Promise((resolve, reject) => {
  new jsmediatags.Reader('/path/to/song.mp3')
    .read({
      onSuccess: (tag) => {
        console.log('Success!');
        resolve(tag);
      },
      onError: (error) => {
        console.log('Error');
        reject(error);
      }
    });
})
  .then(tagInfo => {
    // handle the onSuccess return
  })
  .catch(error => {
    // handle errors
  });

For more control, use the jsmediatags.Reader class. This allows you to specify exactly which tags you want to read using .setTagsToRead(), which can improve performance by avoiding reading unnecessary data.

// Advanced API
var jsmediatags = require("jsmediatags");

new jsmediatags.Reader("http://www.example.com/music-file.mp3")
  .setTagsToRead(["title", "artist"])
  .read({
    onSuccess: function(tag) {
      console.log(tag);
    },
    onError: function(error) {
      console.log(':(', error.type, error.info);
    }
  });

The picture tag contains an array buffer of the image bytes and a content type. To display it in a browser, convert the buffer to a Base64 string.

const { data, format } = result.tags.picture;
let base64String = "";
for (const i = 0; i < data.length; i++) {
  base64String += String.fromCharCode(data[i]);
}
img.src = `data:${data.format};base64,${window.btoa(base64String)}`;

The browser implementation supports reading from remote URLs (must include the scheme, e.g., https://), Blob objects, and File objects (e.g., from an <input type="file"> change event).

// From remote host
jsmediatags.read("http://www.example.com/music-file.mp3", {
  onSuccess: function(tag) {
    console.log(tag);
  },
  onError: function(error) {
    console.log(error);
  }
});

// From Blob
jsmediatags.read(blob, ...);

// From File
inputTypeFile.addEventListener("change", function(event) {
  var file = event.target.files[0];
  jsmediatags.read(file, ...);
}, false);

The Reader class is used in the Advanced API to control the reading process.

jsmediatags.Reader
  .setTagsToRead(tags: Array<string>) // Specify which tags to read
  .setFileReader(fileReader: typeof MediaFileReader) // Use this particular file reader
  .setTagReader(tagReader: typeof MediaTagReader) // Use this particular tag reader
  .read({onSuccess, onError}) // Read the tags