mp3tag.js

https://mp3tag.js.org/docs/
Admin
A JavaScript library for reading, writing, and manipulating ID3 tags in MP3 files, supporting...
Tokens:5,676
Snippets:33
Trust Score:8.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install mp3tag.js via npm

Source: https://mp3tag.js.org/docs/index

This command installs the latest version of the mp3tag.js library using Node Package Manager (npm). The `--save` flag adds it as a dependency to your project's `package.json` file.

```Shell
npm install --save mp3tag.js@latest
```

--------------------------------

### Include mp3tag.js via UNPKG CDN

Source: https://mp3tag.js.org/docs/index

This HTML script tag allows you to quickly integrate mp3tag.js into your project by loading it directly from the UNPKG Content Delivery Network (CDN). It's suitable for rapid prototyping or when local installation is not preferred.

```HTML
<script src="http://unpkg.com/mp3tag.js/dist/mp3tag.min.js">
```

--------------------------------

### Basic MP3 Tag Reading and Writing with mp3tag.js

Source: https://mp3tag.js.org/docs/usage

Demonstrates the fundamental steps to initialize MP3Tag, read existing tags from a buffer, handle potential errors, and update common tags like title, artist, and album. The changes are then saved back to the buffer.

```javascript
const buffer = null // Replace this with the mp3 file's buffer
const verbose = true // Logs all processes using `console.log`
const mp3tag = new MP3Tag(buffer, verbose)

// Read the tags from the buffer
mp3tag.read()

// Handle error if there's any
if (mp3tag.error !== '') throw new Error(mp3tag.error)

console.log(mp3tag.tags)

// Please see `Tags and Frames`
mp3tag.tags.title = 'New Title'
mp3tag.tags.artist = 'New Artist'
mp3tag.tags.album = 'New Album'

mp3tag.save() // Saves the new changes
```

--------------------------------

### MP3Tag `tags.v2` ID3v2 User Defined URL Link Frame (WXXX)

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the 'WXXX' user-defined URL link frame. This frame is parsed and must be saved as an array of objects, where each object contains a 'description' and the 'url' link.

```APIDOC
ID: WXXX
Type: object[]
Description: WXXX frames are parsed and must be saved as an array.
```

```json
[
  {
    "description": "URL description",
    "url": "https://github.com"
  }
]
```

--------------------------------

### MP3Tag Class API Reference

Source: https://mp3tag.js.org/docs/mp3tag

Detailed API documentation for the `MP3Tag` class, including its properties and methods for managing ID3 tags in audio buffers.

```APIDOC
MP3Tag Class:
  Description: A class for reading, writing, and manipulating ID3 tags in MP3 file buffers.

  Properties:
    error:
      Type: string
      Description: Returns the error message if an error was thrown from the last operation (e.g., read or save).
    buffer:
      Type: ArrayBuffer | Buffer
      Description: The current buffer saved on the class instance.
    tags:
      Type: object
      Description: The tags object decoded from the buffer. Refer to 'Tags and Frames' for definitions.

  Methods:
    constructor(buffer[, verbose = false]):
      Description: Initializes a new MP3Tag instance with a buffer.
      Parameters:
        buffer: The audio buffer to process.
        verbose: (Optional) If true, enables verbose logging (defaults to false).
    read(options = {}):
      Return type: object
      Description: Reads the tags from the buffer. On success, sets 'tags' property; on failure, sets 'error' property. Always returns the decoded tags.
      Parameters:
        options: (Optional) An object to configure the reading process.
    static readBuffer(buffer, options = {}, verbose = false):
      Return type: object
      Description: A static version of the 'read' method. Throws an error if decoding is unsuccessful.
      Parameters:
        buffer: The audio buffer to process.
        options: (Optional) An object to configure the reading process.
        verbose: (Optional) If true, enables verbose logging (defaults to false).
    save(options = {}):
      Return type: ArrayBuffer | Buffer
      Description: Writes the 'tags' property to the buffer. On success, returns the updated buffer; on failure, sets 'error' property. Always returns the buffer.
      Parameters:
        options: (Optional) An object to configure the writing process.
    static writeBuffer(buffer, tags, options = {}, verbose = false):
      Return type: ArrayBuffer | Buffer
      Description: A static version of the 'save' method. Throws an error if encoding is unsuccessful.
      Parameters:
        buffer: The audio buffer to process.
        tags: The tags object to write to the buffer.
        options: (Optional) An object to configure the writing process.
        verbose: (Optional) If true, enables verbose logging (defaults to false).
    remove():
      Return type: boolean
      Description: Removes all ID3 tags from the buffer. Always returns true.
    getAudio(emptyNone = false):
      Return type: ArrayBuffer | Buffer
      Description: Extracts the audio portion from the buffer. If 'emptyNone' is false, returns the entire buffer if no audio is detected; otherwise, returns an empty buffer.
      Parameters:
        emptyNone: (Optional) If true, returns an empty buffer if no audio is detected (defaults to false).
    static getAudioBuffer(buffer, emptyNone = false):
      Return type: ArrayBuffer | Buffer
      Description: A static version of the 'getAudio' method.
      Parameters:
        buffer: The audio buffer to process.
        emptyNone: (Optional) If true, returns an empty buffer if no audio is detected (defaults to false).
```

--------------------------------

### MP3Tag `tags.v2` ID3v2 User Defined Text Information Frame (TXXX)

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the 'TXXX' user-defined text information frame. This frame is parsed and must be saved as an array of objects, where each object contains a 'description' and the 'text' content.

```APIDOC
ID: TXXX
Type: object[]
Description: TXXX frames are parsed and must be saved as an array.
```

```json
[
  {
    "description": "Text description",
    "text": "Any string here"
  }
]
```

--------------------------------

### MP3Tag `tags.v2` ID3v2 Frames General Notes

Source: https://mp3tag.js.org/docs/frames

Provides general information and important notes regarding the structure and validation of ID3v2 frames accessible via the `tags.v2` object. This includes information on unsupported frames, string formatting, and strict mode requirements for language codes.

```APIDOC
Note: ID3v2 Frames that are not mentioned here are not currently supported. Feel free to submit an issue!
Note: All string-typed frames are separated by '\\' and should not contain newline characters.
Note: If strict mode is enabled, all languages must follow ISO 639-2.
```

--------------------------------

### Include mp3tag.js as ES6 Module

Source: https://mp3tag.js.org/docs/index

This HTML script tag demonstrates how to include mp3tag.js as an ES6 module directly in your web page. It requires copying the `src` folder of the library to your project and specifying the correct path to `mp3tag.mjs`.

```HTML
<script src="/path/to/mp3tag.mjs" type="module">
```

--------------------------------

### APIDOC: mp3tag.js save() method changes (v2 to v3)

Source: https://mp3tag.js.org/docs/index

This section details the breaking changes to the default options of the `save()` method in mp3tag.js when upgrading from version 2 to 3. Specifically, `id3v1.include` and `id3v2.unsynch` now default to `false`, and `id3v2.footer` support has been removed.

```APIDOC
save()
  `save` method default options are changed:
  `id3v1.include` is set to false
  `id3v2.unsynch` is set to false
  `id3v2.footer` support is dropped
```

--------------------------------

### MP3Tag `tags.v2` ID3v2 URL Frames (W000-WZZZ)

Source: https://mp3tag.js.org/docs/frames

Describes the structure and validation rules for standard ID3v2 URL frames (IDs 'W000' to 'WZZZ', excluding 'WXXX'). It notes that if strict mode is enabled, all URLs are validated against a specific regular expression.

```APIDOC
ID: "W000" - "WZZZ" excluding WXXX
Type: string
Description: If strict mode is enabled, all URLs are checked if its a valid URL. The current RegExp used is `/^(https?):\/\/[^\s/$.?#]+\.[^\s]*/`
```

--------------------------------

### USER Frame Structure: Terms of Use

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the USER (Terms of Use) ID3 frame. It is parsed and saved as an object.

```APIDOC
  {
    language: 'eng',
    text: 'Text'
  }
```

--------------------------------

### Advanced MP3 Tag Manipulation with mp3tag.js

Source: https://mp3tag.js.org/docs/usage

Illustrates more sophisticated usage, including reading MP3 files from the filesystem, selectively ignoring ID3v1 tags during read, and accessing and setting specific ID3v2 frames like the 'COMM' (comment) tag. It also shows how to save with strict validation and padding options.

```javascript
const MP3Tag = require('mp3tag.js')
const fs = require('fs')

const buffer = fs.readFileSync('/path/to/mp3')
const verbose = true // Logs all processes using `console.log`
const mp3tag = new MP3Tag(buffer, verbose)

// Read the tags from the buffer
mp3tag.read({
  id3v1: false // Ignore ID3v1 tags when reading
})

// Handle error if there's any
if (mp3tag.error !== '') throw new Error(mp3tag.error)

console.log(mp3tag.tags)
mp3tag.tags.title = 'New Title'
mp3tag.tags.artist = 'New Artist'
mp3tag.tags.album = 'New Album'

// Access ID3v2 Tags
// Comment Tag. See more ID3v2 tags at id3.org
mp3tag.tags.v2.COMM = [{
  language: 'eng',
  descriptor: '',
  text: 'Comment tag'
}]

mp3tag.save({
  strict: true, // Strict mode, validates all inputs against the standards. See id3.org
  // ID3v2 Options
  id3v2: { padding: 4096 }
})
```

--------------------------------

### MP3Tag `tags.v2` ID3v2 Text Information Frames (T000-TZZZ)

Source: https://mp3tag.js.org/docs/frames

Describes the structure and validation rules for standard ID3v2 text information frames (IDs 'T000' to 'TZZZ', excluding 'TXXX'). It outlines specific formatting for set frames (e.g., TPOS, TRCK), time frames (ID3v2.3.0 and ID3v2.4.0), 'TKEY', and 'TSRC' frames.

```APIDOC
ID: "T000" - "TZZZ" excluding TXXX
Type: string
Description: Some of these frames have its own standards but are only applicable if the strict mode is enabled.
Set frames (TPOS, TRCK) format: '1/2' or just '1' and can be separated '1/2\\1'.
Time frames at ID3v2.3.0 (TDAT, TIME, TORY, TYER) format: 4 numerical characters.
Time frames at ID3v2.4.0 (TDEN, TDOR, TDRC, TDRL, TDTG) format: yyyy-MM-ddTHH:mm:ss (precision can be reduced). Valid timestamps: yyyy, yyyy-MM, yyyy-MM-dd, yyyy-MM-ddTHH, yyyy-MM-ddTHH:mm, yyyy-MM-ddTHH:mm:ss.
TKEY frame format: string with max length of three characters. Ground keys: "A","B","C","D","E", "F", "G". Halfkeys: "b", "#". Minor: "m". Example "Cbm". Off key: "o".
TSRC frame format: 12 alphanumeric characters.
```

--------------------------------

### MP3Tag `tags.v2` ID3v2 Comment and Unsynchronised Lyrics Frames (COMM, USLT)

Source: https://mp3tag.js.org/docs/frames

Documents the structure for 'COMM' (comment) and 'USLT' (unsynchronised lyrics) frames. These frames are parsed and must be saved as an array of objects, each containing 'language', 'descriptor', and 'text'. Strict mode enforces that there should only be one frame with the same language and content descriptor.

```APIDOC
ID: COMM and USLT
Type: object[]
Description: COMM and USLT frames are parsed and must be saved as an array. If the strict mode is enabled, there should only one frame with the same language and content descriptor.
```

```json
[
  {
    "language": "eng",
    "descriptor": "Content description",
    "text": "Lyrics or comment goes here"
  }
]
```

--------------------------------

### MP3Tag `tags` Properties Overview

Source: https://mp3tag.js.org/docs/frames

Documents the top-level properties available on the `tags` object, providing access to various ID3v1 and ID3v2 metadata fields such as title, artist, album, year, comment, track, and genre, along with direct access to raw v1 and v2 tag data and their details.

```APIDOC
title:
  Returns: ID3v2 TIT2 or ID3v1 title or an empty string
  Type: string
artist:
  Returns: ID3v2 TPE1 or ID3v1 artist or an empty string
  Type: string
album:
  Returns: ID3v2 TALB or ID3v1 album or an empty string
  Type: string
year:
  Returns: ID3v2 TYER or TDRC or ID3v1 year or an empty string
  Type: string
comment:
  Returns: ID3v2 COMM or ID3v1 comment or an empty string
  Type: string
track:
  Returns: ID3v2 TRCK or ID3v1 track or an empty string
  Type: string
genre:
  Returns: ID3v2 TCON or ID3v1 genre or an empty string
  Type: string
v1:
  Contains: all ID3v1 tags. Please refer below
  Type: object | undefined
v1Details:
  Description: ID3v1 tag details object containing the `size` and `version`
  Type: object | undefined
v2:
  Contains: all ID3v2 tags. Please refer below
  Type: object | undefined
v2Details:
  Description: ID3v2 tag details object containing the `size`, `flags`, and `version`
  Type: object | undefined
```

--------------------------------

### OWNE Frame Structure: Ownership

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the OWNE (Ownership) ID3 frame. It is parsed and saved as an object. Strict mode requires the date to be in YYYYMMDD format, currencyCode to be ISO 4217, and currencyPrice to follow N.nn format.

```APIDOC
  {
    currencyCode: 'USD',
    currencyPrice: '2.00',
    date: '20200424',       // YYYYMMDD date format
    seller: 'Seller'        // Seller's name
  }
```

--------------------------------

### MP3Tag `tags.v1` ID3v1 Frames

Source: https://mp3tag.js.org/docs/frames

Details the properties available under the `tags.v1` object, representing specific ID3v1 metadata fields such as title, artist, album, year, comment, track, and genre.

```APIDOC
title:
  Type: string
artist:
  Type: string
album:
  Type: string
year:
  Type: string
comment:
  Type: string
track:
  Type: string
genre:
  Type: string
```

--------------------------------

### PRIV Frame Structure: Private

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the PRIV (Private) ID3 frame. It is parsed as an array of objects. Strict mode requires unique data.

```APIDOC
  [
    {
      ownerId: 'owner string',
      data: [1, 2, 3, 4, 5, 6, 7, 8, 9] // Data bytes
    }
  ]
```

--------------------------------

### APIDOC: mp3tag.js mp3tag.tags structure change (v2 to v3)

Source: https://mp3tag.js.org/docs/index

This documentation highlights the restructuring of ID3v2 tags within the `mp3tag.tags` object in mp3tag.js from version 2 to 3. All ID3v2 tags (e.g., TIT2, TPE1) are now nested under `mp3tag.tags.v2`.

```APIDOC
mp3tag.tags
  All ID3v2 tags (TIT2, TPE1, ...) are moved to `mp3tag.tags.v2`
```

--------------------------------

### RVAD Frame Structure: Relative Volume Adjustment (ID3v2.3.0)

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the RVAD (Relative Volume Adjustment) ID3 frame, available in ID3v2.3.0. It is parsed and saved as an object.

```APIDOC
  {
    bitsvolume: 16,
    incdec: {
      right: true,
      left: true,
      rightback: false,
      leftback: false,
      center: false,
      bass: false
    },
    volumechange: {
      right: [0, 1],
      left: [0, 1],
      rightback: [],
      leftback: [],
      center: [],
      bass: []
    },
    peakvolume: {
      right: [0, 1],
      left: [0, 1],
      rightback: [],
      leftback: [],
      center: [],
      bass: []
    }
  }
```

--------------------------------

### Synchronised Lyrics/Text Frame (SYLT) Data Structure

Source: https://mp3tag.js.org/docs/frames

Describes the structure for the SYLT (Synchronised lyrics/text) ID3 frame. It must be saved as an array of objects. Strict mode rules include language encoding (ISO 639-2), type range (0-6), format (1 or 2), and specific lyric formatting ([mm:ss.xxx] String).

```JSON
[
  {
    "language": "eng",
    "format": 1,
    "type": 1,
    "descriptor": "Descriptions",
    "lyrics": "[mm:ss.xxx] Synced lyrics"
  }
]
```

```JSON
[
  {
    "language": "eng",
    "format": 1,
    "type": 1,
    "descriptor": "Descriptions",
    "data": [
      { "line": "LINE1", "time": 200 },
      { "line": "LINE2", "time": 10000 },
      { "line": "LINE3", "time": 2000000 }
    ]
  }
]
```

--------------------------------

### POPM Frame Structure: Popularimeter

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the POPM (Popularimeter) ID3 frame. It is parsed as an array of objects. Strict mode requires a unique email.

```APIDOC
  [
    {
      email: 'john@example.com',
      rating: 255,                // 0 is unknown, 1 is worst, and 255 is best ratings
      counter: 0                  // number of times the user played this
    }
  ]
```

--------------------------------

### APIC Frame Structure: Attached Picture

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the APIC (Attached Picture) ID3 frame. It is parsed as an array of objects. Strict mode requires a unique content descriptor, image types between 0-21, a valid MIME type (image/...), and a description under 64 characters.

```APIDOC
  [
    {
      format: 'image/jpeg',                // Image MIME
      type: 3,                             // See the APIC image types at id3.org
      description: 'Content description',
      data: [1, 2, 3, 4, 5, 6, 7, 8]       // Image bytes
    }
  ]
```

--------------------------------

### Event Timing Codes Frame (ETCO) Data Structure

Source: https://mp3tag.js.org/docs/frames

Specifies the structure for the ETCO (Event timing codes) ID3 frame. This frame is parsed and must be saved as an object. If strict mode is enabled, the format property must be either 1 or 2.

```JSON
{
  "format": 1,
  "data": [
    { "event": 0, "time": 200 },
    { "event": 130, "time": 10000 },
    { "event": 260, "time": 2000000 }
  ]
}
```

--------------------------------

### Synchronised Tempo Codes Frame (SYTC) Data Structure

Source: https://mp3tag.js.org/docs/frames

Outlines the structure for the SYTC (Synchronised tempo codes) ID3 frame. It is parsed and must be saved as an object. In strict mode, the format property must be either 1 or 2.

```JSON
{
  "format": 1,
  "data": [
    { "bpm": 0, "time": 200 },
    { "bpm": 130, "time": 10000 },
    { "bpm": 260, "time": 2000000 }
  ]
}
```

--------------------------------

### SIGN Frame Structure: Signature (ID3v2.4.0)

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the SIGN (Signature) ID3 frame, available in ID3v2.4.0. It is parsed as an array. Strict mode requires all frames to be unique.

```APIDOC
  [
    {
      group: 1,
      signature: [1, 2, 3, 4, 5, 6, 7, 8, 9] // Signature bytes
    }
  ]
```

--------------------------------

### MP3Tag.save Method Default Options

Source: https://mp3tag.js.org/docs/mp3tag

Default options object used when calling the `MP3Tag.save` method to configure tag writing behavior.

```JavaScript
  // Default Options
  {
    strict: false, // Use strict mode when validating
    /**
     * Encoding to use when writing ID3v1 tags. Valid options are:
     * 'utf-8', 'utf8', 'utf16', 'utf-16', 'utf16be', 'utf-16be', 'windows1251', ''
     */
    encoding: 'utf-8',
    /**
     * If true, returns an empty buffer instead as an audio if no audio was detected.
     * Otherwise, returns the entire buffer.
     */
    emptyAudioNone: false,
    id3v1: {
      include: false,          // Add ID3v1 tags to buffer
      encoding: 'utf-8'
    },
    id3v2: {
      include: true,           // Add ID3v2 tags to buffer
      unsynch: false,          // Use unsynchronisation scheme
      version: defaultVersion, // ID3v2 major version
      padding: 2048,           // Number of null bytes added after ID3v2 tag
      unsupported: false,      // Whether to write unsupported frames to buffer. Otherwise, skips
      encoding: 'utf-8'
    }
  }

```

--------------------------------

### MP3Tag.read Method Default Options

Source: https://mp3tag.js.org/docs/mp3tag

Default options object used when calling the `MP3Tag.read` method to configure tag parsing behavior.

```JavaScript
  // Default Options
  {
    id3v1: true, // include ID3v1
    id3v2: true, // include ID3v2
    unsupported: false, // if true, parses unsupported frames as an array of bytes. Otherwise, skip
    encoding: 'utf-8' // encoding to use when parsing ID3v1 tags
  }

```

--------------------------------

### UFID Frame Structure: Unique File Identifier

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the UFID (Unique File Identifier) ID3 frame. It is parsed as an array of objects. Strict mode requires a unique, non-empty owner identifier string and an ID byte length not exceeding 64 bytes.

```APIDOC
  [
    {
      ownerId: 'http://www.id3.org/dummy/ufid.html', // Non-empty owner ID
      id: [1, 2, 3, 4, 5, 6, 7]                      // Binary identifier
    }
  ]
```

--------------------------------

### Music CD Identifier Frame (MCDI) Data Structure

Source: https://mp3tag.js.org/docs/frames

Defines the structure for the MCDI (Music CD identifier) ID3 frame. This frame is parsed and must be saved as a single object containing an array of binary bytes.

```JSON
{
  "data": [1, 2, 3, 4, 5, 6, 7, 8]
}
```

--------------------------------

### RVA2 Frame Structure: Relative Volume Adjustment 2 (ID3v2.4.0)

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the RVA2 (Relative Volume Adjustment 2) ID3 frame, available in ID3v2.4.0. It is parsed as an array. Strict mode requires a unique identification string.

```APIDOC
  [{
    identification: 'identification',
    channels: [{
      type: 1,
      volumeadjust: 16,
      bitspeak: 16,
      peakvolume: [0, 1]
    }]
  }]
```

--------------------------------

### APIDOC: mp3tag.js mp3tag.errorCode removal (v2 to v3)

Source: https://mp3tag.js.org/docs/index

This entry documents the removal of the `mp3tag.errorCode` property in mp3tag.js during the v2 to v3 upgrade. Developers should now use the `mp3tag.error` property for error handling.

```APIDOC
mp3tag.errorCode
  `mp3tag.errorCode` was removed (use `mp3tag.error` instead)
```

--------------------------------

### GEOB Frame Structure: General Encapsulated Object

Source: https://mp3tag.js.org/docs/frames

Documents the structure for the GEOB (General Encapsulated Object) ID3 frame. It is parsed as an array of objects. Strict mode requires a unique content descriptor.

```APIDOC
  [
    {
      format: 'application/octet-stream',  // Object MIME
      filename: 'filename.bin',
      description: 'Content description',
      object: [1, 2, 3, 4, 5, 6, 7, 8, 9]  // Object bytes
    }
  ]
```
Tokens:
Raw