Node ID3

https://github.com/zazama/node-id3
Admin
Node ID3 is a JavaScript library for reading, writing, and updating ID3 tags in audio files,...
Tokens:32,307
Snippets:348
Trust Score:8.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### ReadOptions Usage Example

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/types.md

Example of reading tags from a file while excluding specific frames and disabling raw data output.

```javascript
const tags = NodeID3.read('./song.mp3', {
  exclude: ['APIC'],
  noRaw: true
})
```

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

### Install node-id3

Source: https://github.com/zazama/node-id3/blob/0.2/README.md

Install the package via npm.

```sh
npm install node-id3
```

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

### Initialize node-id3 and define tags

Source: https://github.com/zazama/node-id3/blob/0.2/README.md

Import the library and define common variables and tag objects used in subsequent examples.

```javascript
const NodeID3 = require('node-id3')

/* Variables found in the following usage examples */

const filebuffer = Buffer.from("Some Buffer of a (mp3) file")
const filepath = './path/to/(mp3)file'

const tags = {
    title: "Tomorrow",
    artist: "Kevin Penkin",
    album: "TVアニメ「メイドインアビス」オリジナルサウンドトラック",
    APIC: "./example/mia_cover.jpg",
    TRCK: "27"
}
```

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

### Promise API Usage

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Examples of how to import and use the Promise-based API for reading ID3 tags.

```javascript
const { Promise: ID3Promise } = require('node-id3')

// Or
const NodeID3 = require('node-id3')
const tags = await NodeID3.Promise.read('./song.mp3')
```

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

### Add Chapter Information to MP3

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Defines chapter segments with start and end times to be written into the ID3 tags.

```javascript
const NodeID3 = require('node-id3')

const tags = {
  title: 'Long Track',
  chapter: [
    {
      elementID: 'chapter1',
      startTimeMs: 0,
      endTimeMs: 60000,
      tags: {
        title: 'Introduction',
        artist: 'John Doe'
      }
    },
    {
      elementID: 'chapter2',
      startTimeMs: 60000,
      endTimeMs: 180000,
      tags: {
        title: 'Main Story'
      }
    }
  ]
}

NodeID3.write(tags, './podcast.mp3')
```

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

### Complete audio file processing with Async/Await

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Demonstrates reading, updating, and creating ID3 tags using the Promise-based API.

```javascript
const NodeID3 = require('node-id3')
const fs = require('fs').promises

async function processAudioFile() {
  const filePath = './music/song.mp3'
  
  try {
    // Read existing tags
    console.log('Reading existing tags...')
    let tags = await NodeID3.Promise.read(filePath)
    console.log('Current title:', tags.title)
    
    // Update with new tags
    console.log('Updating tags...')
    const updates = {
      title: 'New Title',
      artist: 'New Artist',
      album: 'New Album'
    }
    await NodeID3.Promise.update(updates, filePath)
    
    // Verify update
    tags = await NodeID3.Promise.read(filePath)
    console.log('Updated title:', tags.title)
    
    // Create standalone tag buffer
    console.log('Creating tag buffer...')
    const tagBuffer = await NodeID3.Promise.create(tags)
    console.log('Tag buffer size:', tagBuffer.length)
    
  } catch (err) {
    console.error('Error processing file:', err.message)
  }
}

processAudioFile()
```

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

### Define private frames

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Example structure for storing proprietary data in private ID3 frames.

```javascript
const tags = {
  private: [
    {
      ownerIdentifier: 'Company Inc.',
      data: Buffer.from([0x01, 0x02, 0x03])
    }
  ]
}
```

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

### Compare Callback and Promise API usage

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Demonstrates the syntax difference between the legacy callback style and the preferred Promise-based approach for writing tags.

```javascript
// Callback style
NodeID3.write(tags, './song.mp3', (err) => {
  if (err) console.error(err)
  else console.log('Done')
})

// Promise style (preferred)
await NodeID3.Promise.write(tags, './song.mp3')
```

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

### Define invalid language code

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/errors.md

Example of a tag object containing a language code that exceeds the standard 3-character limit.

```javascript
const tags = {
  comment: {
    language: 'TOOLONG',  // > 3 chars; may cause issues in readers
    text: 'Comment'
  }
}
```

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

### Importing and Wrapping Node-ID3 Functions

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Demonstrates how to import specific functions using destructuring or create custom wrapper functions for preprocessing.

```javascript
// Export only what you need
const { write, read, TagConstants } = require('node-id3')

// Or create wrapper with custom defaults
const NodeID3 = require('node-id3')

const customWrite = (tags, path) => {
  // Custom preprocessing
  return NodeID3.write(tags, path)
}
```

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

### Using Alias or Raw IDs

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/00-START-HERE.md

Demonstrates the interchangeability of friendly aliases and raw ID3 frame IDs when defining tags.

```javascript
{ title: 'Song' }  // Friendly alias
{ TIT2: 'Song' }   // Raw frame ID
```

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

### Module Entry Point Implementation

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

The internal definition of the module exports within index.js.

```javascript
module.exports = {
    TagConstants: ID3Definitions.TagConstants,
    create,
    write,
    update,
    read,
    removeTags,
    removeTagsFromBuffer,
    Promise: PromiseExport
}
```

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

### Write tags using friendly aliases

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/frame-identifiers.md

Use standard alias keys to write metadata to an MP3 file.

```javascript
const NodeID3 = require('node-id3')

const tags = {
  title: 'Song Title',
  artist: 'Artist Name',
  album: 'Album Name'
}

NodeID3.write(tags, './song.mp3')
```

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

### Import node-id3

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

The main entry point for accessing the library functionality.

```javascript
const NodeID3 = require('node-id3')
```

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

### create(tags: Tags, fn: (buffer: Buffer) => void)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Creates an ID3 tag buffer asynchronously and returns the result via a callback function.

```APIDOC
## create(tags: Tags, fn: (buffer: Buffer) => void)

### Description
Creates an ID3 tag buffer asynchronously. The result is passed to the provided callback function.

### Parameters
- **tags** (Tags) - Required - Object containing tags to create
- **fn** ((buffer: Buffer) => void) - Required - Callback receiving the created tag buffer

### Returns
- **void**

### Example
```javascript
const NodeID3 = require('node-id3')

const tags = { title: 'Song', artist: 'Artist' }

NodeID3.create(tags, (buffer) => {
  console.log('Tag buffer created, size:', buffer.length)
})
```
```

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

### Read and write tags using buffers

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Demonstrates processing file data as a buffer for I/O operations.

```javascript
const NodeID3 = require('node-id3')
const fs = require('fs')

// Read file into buffer
const fileBuffer = fs.readFileSync('./song.mp3')

// Write tags to buffer
const tags = { title: 'Title', artist: 'Artist' }
const taggedBuffer = NodeID3.write(tags, fileBuffer)

// Write modified buffer back
fs.writeFileSync('./song.mp3', taggedBuffer)
```

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

### Accessing the Promise API

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Demonstrates how to import or destructure the Promise namespace from the node-id3 package.

```javascript
const NodeID3 = require('node-id3')
const { Promise: NodeID3Promise } = NodeID3

// Or destructure:
const { Promise: ID3Promise } = require('node-id3')
```

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

### Access ID3_FRAME_OPTIONS

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Shows how to retrieve frame configuration settings such as whether a frame supports multiple values or requires a specific merge key.

```javascript
ID3_FRAME_OPTIONS = {
  "TXXX": { multiple: true, updateCompareKey: "description" },
  "WXXX": { multiple: true, updateCompareKey: "description" },
  "APIC": { multiple: false },
  "COMM": { multiple: false },
  "CHAP": { multiple: true },
  // ... more frames
}
```

```javascript
const defs = require('./src/ID3Definitions')
const opts = defs.ID3_FRAME_OPTIONS['TXXX']
console.log(opts.multiple)        // true
console.log(opts.updateCompareKey) // 'description'
```

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

### Use Promises

Source: https://github.com/zazama/node-id3/blob/0.2/README.md

Access promise-based versions of the library methods.

```javascript
const NodeID3Promise = require('node-id3').Promise

NodeID3.write(tags, fileOrBuffer)
NodeID3.update(tags, fileOrBuffer)
NodeID3.create(tags)
NodeID3.read(filepath)
NodeID3.removeTags(filepath)
```

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

### Perform basic ID3 tag operations

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/00-START-HERE.md

Demonstrates reading tags, writing tags, and using the Promise-based API for asynchronous operations.

```javascript
const NodeID3 = require('node-id3')

// Read tags
const tags = NodeID3.read('./song.mp3')
console.log(tags.title, tags.artist)

// Write tags
NodeID3.write({
  title: 'Song Title',
  artist: 'Artist Name',
  album: 'Album Name'
}, './song.mp3')

// Use Promises
const tags = await NodeID3.Promise.read('./song.mp3')
```

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

### Use SplitBuffer for Null-Terminated Buffers

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Demonstrates splitting a buffer at the first null terminator.

```javascript
const ID3Util = require('./src/ID3Util')

const buffer = Buffer.from('text\x00remaining')
const split = ID3Util.splitNullTerminatedBuffer(buffer)
console.log(split.value.toString())      // 'text'
console.log(split.remainder.toString())  // 'remaining'
```

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

### Process File with Error Handling

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/errors.md

Demonstrates reading, updating, and verifying tags with specific error code checks for file system issues.

```javascript
const NodeID3 = require('node-id3')

async function processFile(filepath) {
  try {
    // Read
    const tags = await NodeID3.Promise.read(filepath)
    console.log('Read:', tags.title)
    
    // Update
    await NodeID3.Promise.update(
      { title: 'New Title' },
      filepath
    )
    
    // Verify
    const updated = await NodeID3.Promise.read(filepath)
    console.log('Updated to:', updated.title)
    
  } catch (err) {
    if (err.code === 'ENOENT') {
      console.error('File not found')
    } else if (err.code === 'EACCES') {
      console.error('Permission denied')
    } else {
      console.error('Operation failed:', err.message)
    }
  }
}
```

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

### Batch Update Multiple Files

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Iterate through a directory to apply tag updates to multiple MP3 files.

```javascript
const files = fs.readdirSync('./music').filter(f => f.endsWith('.mp3'))
for (const file of files) {
  NodeID3.update({ artist: 'Various' }, `./music/${file}`)
}
```

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

### Promise API Method Signatures

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Available methods for the Promise-based API, supporting both file paths and buffers.

```javascript
Promise.write(tags: Tags, filebuffer: Buffer): Promise<Buffer>
Promise.write(tags: Tags, filepath: string): Promise<boolean>

Promise.read(filebuffer: Buffer, options?: Object): Promise<Tags>
Promise.read(filepath: string, options?: Object): Promise<Tags>

Promise.create(tags: Tags): Promise<Buffer>

Promise.update(tags: Tags, filebuffer: Buffer, options?: Object): Promise<Buffer>
Promise.update(tags: Tags, filepath: string, options?: Object): Promise<boolean>

Promise.removeTags(filepath: string): Promise<Buffer>
Promise.removeTags(filebuffer: Buffer): Promise<Buffer>
```

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

### Batch Process Multiple Files

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Iterates through a directory to read and inspect tags for all MP3 files.

```javascript
const NodeID3 = require('node-id3')
const fs = require('fs')
const path = require('path')

const musicDir = './music'
const files = fs.readdirSync(musicDir)
  .filter(f => f.endsWith('.mp3'))

files.forEach((filename) => {
  const filepath = path.join(musicDir, filename)
  const tags = NodeID3.read(filepath)
  
  if (!tags.artist) {
    console.log('No artist:', filename)
  }
})
```

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

### Define stringToEncodedBuffer and bufferToDecodedString Functions

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Functions for text encoding and decoding using iconv-lite.

```javascript
function stringToEncodedBuffer(str: string, encodingByte: number): Buffer
function bufferToDecodedString(buffer: Buffer, encodingByte: number): string
```

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

### Perform Basic ID3 Tag Operations

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Demonstrates reading, writing, updating, and removing ID3 tags from an MP3 file using the synchronous API.

```javascript
const NodeID3 = require('node-id3')

// Read tags
const tags = NodeID3.read('./song.mp3')
console.log(tags.title, tags.artist)

// Write tags
const success = NodeID3.write({
  title: 'Song Title',
  artist: 'Artist Name',
  album: 'Album Name'
}, './song.mp3')

// Update tags (preserves unmodified fields)
NodeID3.update({ year: '2024' }, './song.mp3')

// Remove all tags
NodeID3.removeTags('./song.mp3')
```

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

### Update multiple value frames

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/frame-identifiers.md

Demonstrates how frames with merge keys, such as TXXX, are updated by merging based on the description field.

```javascript
// Initial write
NodeID3.write({
  TXXX: [
    { description: 'key1', value: 'value1' },
    { description: 'key2', value: 'value2' }
  ]
}, './song.mp3')

// Update - merges by description
NodeID3.update({
  TXXX: [
    { description: 'key1', value: 'updated1' },  // Updates existing
    { description: 'key3', value: 'value3' }      // Adds new
  ]
}, './song.mp3')

// Result: key1 (updated), key2 (preserved), key3 (added)
```

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

### create(tags: Tags)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Creates an ID3 tag buffer synchronously without writing to a file.

```APIDOC
## create(tags: Tags)

### Description
Creates an ID3 tag buffer synchronously. Returns a Buffer containing ID3v2.3.0 tag data.

### Parameters
- **tags** (Tags) - Required - Object containing tags to create

### Returns
- **Buffer** - Buffer containing ID3v2.3.0 tag data

### Example
```javascript
const NodeID3 = require('node-id3')

const tags = {
  title: 'Song Title',
  artist: 'Artist Name',
  album: 'Album Name'
}

const tagBuffer = NodeID3.create(tags)
console.log('ID3 tag created, size:', tagBuffer.length)
```
```

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

### create() function signatures

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Creates an ID3 tag buffer from the provided tags object.

```javascript
create(tags: Tags): Buffer
create(tags: Tags, fn: (buffer: Buffer) => void): void
```

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

### Add Album Cover with node-id3

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Requires an image buffer and specific tag constants to attach a picture to an MP3 file.

```javascript
const NodeID3 = require('node-id3')
const fs = require('fs')

const tags = {
  title: 'Song Title',
  image: {
    mime: 'image/jpeg',
    type: { id: NodeID3.TagConstants.AttachedPicture.PictureType.FRONT_COVER },
    description: 'Front Cover',
    imageBuffer: fs.readFileSync('./cover.jpg')
  }
}

NodeID3.write(tags, './song.mp3')
```

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

### Write ID3 tags to a buffer synchronously

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Use this method to prepend ID3 tags to a file buffer synchronously. Returns a new buffer containing the tagged data.

```javascript
write(tags: Tags, filebuffer: Buffer): Buffer
```

```javascript
const NodeID3 = require('node-id3')
const fs = require('fs')

const tags = {
  title: 'Song Title',
  artist: 'Artist Name',
  album: 'Album Name'
}

const fileBuffer = fs.readFileSync('./song.mp3')
const taggedBuffer = NodeID3.write(tags, fileBuffer)
fs.writeFileSync('./song.mp3', taggedBuffer)
```

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

### Optimize Bulk File Processing

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Compare memory-based buffer operations with direct file I/O to optimize performance during bulk tag updates.

```javascript
// Fast - read buffer, modify, write back
const buf = fs.readFileSync(path)
const modified = NodeID3.write(tags, buf)
fs.writeFileSync(path, modified)

// Slower - file I/O on each operation
const result = NodeID3.write(tags, path)
```

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

### Create ID3 tags with Promise.create

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Generates an ID3 tag buffer from a provided tags object using an asynchronous Promise-based approach.

```javascript
const NodeID3 = require('node-id3')

async function createTags() {
  try {
    const tags = {
      title: 'Song Title',
      artist: 'Artist Name',
      album: 'Album Name'
    }
    
    const tagBuffer = await NodeID3.Promise.create(tags)
    console.log('Tag buffer created, size:', tagBuffer.length, 'bytes')
  } catch (err) {
    console.error('Error creating tags:', err)
  }
}

createTags()
```

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

### ID3FrameBuilder Constructor

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Initializes a new instance of the ID3FrameBuilder class for constructing an ID3 frame.

```APIDOC
## new ID3FrameBuilder(identifier)

### Description
Initializes a new builder instance for constructing an ID3 frame with a specific identifier.

### Parameters
- **identifier** (string) - Required - 4-character frame ID (e.g., 'TIT2')

### Example
```javascript
const ID3FrameBuilder = require('./src/ID3FrameBuilder');
const builder = new ID3FrameBuilder('TIT2');
```
```

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

### Initialize ID3FrameBuilder

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Constructor for the ID3FrameBuilder class used to construct ID3 frames.

```javascript
const builder = new ID3FrameBuilder(identifier: string)
```

```javascript
const ID3FrameBuilder = require('./src/ID3FrameBuilder')

const builder = new ID3FrameBuilder('TIT2')
```

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

### NodeID3.create()

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Creates an ID3 tag buffer.

```APIDOC
## NodeID3.create(tags, [fn])

### Description
Creates an ID3 tag buffer from the provided tags object.

### Signatures
- create(tags: Tags): Buffer
- create(tags: Tags, fn: (buffer: Buffer) => void): void
```

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

### read(filebuffer: string | Buffer, options: Object)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Synchronously reads ID3 tags from a file or buffer with configuration options.

```APIDOC
## read(filebuffer: string | Buffer, options: Object)

### Description
Reads ID3 tags from a file or buffer synchronously with specific configuration options.

### Parameters
- **filebuffer** (string | Buffer) - Required - Filepath string or Buffer with file data
- **options** (Object) - Required - Configuration object
  - **include** (string[]) - Optional - Only read specified frame identifiers
  - **exclude** (string[]) - Optional - Do not read specified frame identifiers
  - **onlyRaw** (boolean) - Optional - Return only raw frame data, skip processed tags
  - **noRaw** (boolean) - Optional - Do not include raw frame data in response

### Returns
- **Tags** (Object) - Object with parsed tags
```

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

### Convert Between Formats

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Read tags from an existing file and write them to a new file, effectively converting the ID3 format.

```javascript
const tags = NodeID3.read(oldFile)
delete tags.raw  // Remove raw frame data
NodeID3.write(tags, newFile)  // Writes as v2.3.0
```

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

### Create tags as buffer

Source: https://github.com/zazama/node-id3/blob/0.2/README.md

Generate a buffer containing the ID3 tags.

```javascript
const success = NodeID3.create(tags) // Returns ID3-Tag Buffer
// async version
NodeID3.create(tags, function(buffer) {  })
```

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

### read(filebuffer: string | Buffer, options: Object, fn: Function)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Asynchronously reads ID3 tags from a file or buffer with configuration options and a callback.

```APIDOC
## read(filebuffer: string | Buffer, options: Object, fn: Function)

### Description
Reads ID3 tags from a file or buffer asynchronously with configuration options.

### Parameters
- **filebuffer** (string | Buffer) - Required - Filepath string or Buffer with file data
- **options** (Object) - Required - Configuration object (include, exclude, onlyRaw, noRaw)
- **fn** (Function) - Required - Callback with error and tags (err: NodeJS.ErrnoException | null, tags: Tags | null) => void

### Returns
- **void**
```

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

### Optimize ID3 Write Performance

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/00-START-HERE.md

Use in-memory buffer operations to minimize disk I/O compared to direct file path writes.

```javascript
// Fast: one file I/O
const buf = fs.readFileSync(path)
const modified = NodeID3.write(tags, buf)
fs.writeFileSync(path, modified)

// Slower: three I/O operations
NodeID3.write(tags, path)  // write triggers read internally
```

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

### write(tags, filebuffer)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Synchronously writes ID3 tags to a provided buffer and returns a new buffer with the tags prepended.

```APIDOC
## write(tags: Tags, filebuffer: Buffer)

### Description
Writes ID3 tags to a buffer synchronously. Returns a new buffer containing the tags.

### Parameters
- **tags** (Tags) - Required - Object containing tags to write
- **filebuffer** (Buffer) - Required - Buffer containing file data

### Returns
- **Buffer** - New buffer with ID3 tags prepended
```

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

### Use async/await

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/00-START-HERE.md

Performs tag operations asynchronously using the Promise-based API.

```javascript
const tags = await NodeID3.Promise.read('./song.mp3')
await NodeID3.Promise.update({ title: 'New' }, './song.mp3')
```

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

### Handling Callback Signatures

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Note that callback parameter order varies between functions; the Promise API is recommended for consistent error handling.

```javascript
// write/update callback - Error first (for files)
NodeID3.write(tags, filepath, (err) => {})

// read callback - Error first
NodeID3.read(filepath, (err, tags) => {})

// create callback - Result first (no error param)
NodeID3.create(tags, (buffer) => {})

// Promise API - Consistent error handling
await NodeID3.Promise.write(tags, filepath)  // Rejects on error
```

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

### getBuffer()

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Constructs and returns the complete ID3 frame as a Buffer.

```APIDOC
## builder.getBuffer()

### Description
Constructs the complete frame including the header and accumulated data.

### Returns
- **Buffer** - The complete frame (header + data).
```

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

### write(tags, filepath, fn)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Asynchronously writes ID3 tags to a file at the specified path.

```APIDOC
## write(tags: Tags, filepath: string, fn: (err: NodeJS.ErrnoException | Error | null) => void)

### Description
Writes ID3 tags to a file at the specified path asynchronously.

### Parameters
- **tags** (Tags) - Required - Object containing tags to write
- **filepath** (string) - Required - Path to file to write tags to
- **fn** (Function) - Required - Callback with error (null on success)
```

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

### Define chapters and table of contents

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Structure chapter and table of contents data for ID3 tags.

```javascript
{
  chapter: [{
    elementID: 'ch1',
    startTimeMs: 0,
    endTimeMs: 60000,
    tags: { title: 'Introduction' }
  }],
  tableOfContents: [{
    elementID: 'toc',
    elements: ['ch1', 'ch2'],
    tags: { title: 'Table of Contents' }
  }]
}
```

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

### write(tags, filebuffer, fn)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Asynchronously writes ID3 tags to a buffer and returns the result via a callback.

```APIDOC
## write(tags: Tags, filebuffer: Buffer, fn: (err: null, buffer: Buffer) => void)

### Description
Writes ID3 tags to a buffer asynchronously.

### Parameters
- **tags** (Tags) - Required - Object containing tags to write
- **filebuffer** (Buffer) - Required - Buffer containing file data
- **fn** (Function) - Required - Callback with error and resulting buffer
```

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

### Batch Update with Promises

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Updates tags across multiple files concurrently using the Promise-based API.

```javascript
const NodeID3 = require('node-id3')
const fs = require('fs').promises
const path = require('path')

async function addArtistToAll(artist) {
  const files = await fs.readdir('./music')
  
  const updates = files
    .filter(f => f.endsWith('.mp3'))
    .map(f => path.join('./music', f))
    .map(filepath =>
      NodeID3.Promise.update(
        { artist },
        filepath
      ).catch(err => console.error(filepath, err))
    )
  
  await Promise.all(updates)
  console.log('Updated all files')
}

addArtistToAll('Default Artist')
```

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

### update(tags, filebuffer, options)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Synchronously updates ID3 tags in a buffer and returns the updated buffer.

```APIDOC
## update(tags: Tags, filebuffer: Buffer, options?: Object)

### Description
Updates ID3 tags in a buffer, preserving existing tags not being overwritten.

### Parameters
- **tags** (Tags) - Required - Tags to update
- **filebuffer** (Buffer) - Required - Buffer containing file data
- **options** (Object) - Optional - Read options (include, exclude, onlyRaw, noRaw)

### Returns
- **Buffer** - Buffer with updated tags
```

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

### Add Table of Contents to MP3

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Creates a structured table of contents referencing specific element IDs.

```javascript
const NodeID3 = require('node-id3')

const tags = {
  title: 'Audiobook',
  tableOfContents: [{
    elementID: 'toc',
    isOrdered: true,
    elements: ['chapter1', 'chapter2', 'chapter3'],
    tags: {
      title: 'Table of Contents'
    }
  }]
}

NodeID3.write(tags, './audiobook.mp3')
```

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

### Optimize Reading for Large Collections

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Uses the include option to fetch only necessary frames and skips raw data to improve performance when processing multiple files.

```javascript
const NodeID3 = require('node-id3')

// Read only essential fields for faster processing
const options = {
  include: ['TIT2', 'TPE1', 'TALB'],  // Title, Artist, Album
  noRaw: true  // Skip raw frame data
}

const files = ['file1.mp3', 'file2.mp3']

files.forEach(file => {
  const tags = NodeID3.read(file, options)
  console.log(`${tags.title} - ${tags.artist}`)
})
```

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

### Promise.write(tags, filepath)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Writes ID3 tags directly to a file at the specified path.

```APIDOC
## Promise.write(tags: Tags, filepath: string)

### Description
Writes ID3 tags directly to a file on the filesystem.

### Parameters
- **tags** (Tags) - Required - Object containing tags to write
- **filepath** (string) - Required - Path to file

### Returns
- **Promise<boolean>** - Resolves with true on success

### Example
```javascript
const NodeID3 = require('node-id3');

async function writeTagsToFile() {
  try {
    const tags = { title: 'Tomorrow', artist: 'Kevin Penkin' };
    await NodeID3.Promise.write(tags, './music/song.mp3');
  } catch (err) {
    console.error('Write error:', err.message);
  }
}
```
```

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

### Add User-Defined URL Fields

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Use the userDefinedUrl array to attach custom web links to the ID3 tag.

```javascript
const NodeID3 = require('node-id3')

const tags = {
  title: 'Song',
  userDefinedUrl: [
    { description: 'Official Video', url: 'https://example.com/video' },
    { description: 'Lyrics', url: 'https://example.com/lyrics' }
  ]
}

NodeID3.write(tags, './song.mp3')
```

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

### Promise Namespace

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

The Promise namespace provides asynchronous versions of the standard library methods.

```APIDOC
## NodeID3.Promise

### Description
An object containing asynchronous versions of the library methods that return Promises.

### Methods
- read(filepath)
- write(tags, filepath)
- update(tags, filepath)
- removeTags(filepath)
```

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

### write(tags, filepath)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Synchronously writes ID3 tags to a file at the specified path.

```APIDOC
## write(tags: Tags, filepath: string)

### Description
Writes ID3 tags to a file at the specified path synchronously.

### Parameters
- **tags** (Tags) - Required - Object containing tags to write
- **filepath** (string) - Required - Path to file to write tags to

### Returns
- **boolean | Error** - true on success, Error object on failure
```

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

### Type checking utilities

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Simple utility functions for verifying data types.

```javascript
function isFunction(value: any): boolean
```

```javascript
function isString(value: any): boolean
```

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

### Write tags to a file

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/00-START-HERE.md

Writes provided tag objects to a specified MP3 file.

```javascript
NodeID3.write({ title: 'Song' }, './song.mp3')
```

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

### Promise.write(tags, filebuffer)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Writes ID3 tags to a provided Buffer and returns a new Buffer containing the tags.

```APIDOC
## Promise.write(tags: Tags, filebuffer: Buffer)

### Description
Writes ID3 tags to a buffer. This method is useful when working with file data already loaded into memory.

### Parameters
- **tags** (Tags) - Required - Object containing tags to write
- **filebuffer** (Buffer) - Required - Buffer with file data

### Returns
- **Promise<Buffer>** - Resolves with new buffer containing tags

### Example
```javascript
const NodeID3 = require('node-id3');
const fs = require('fs').promises;

async function writeTagsToBuffer() {
  try {
    const fileBuffer = await fs.readFile('./song.mp3');
    const tags = { title: 'Song Title', artist: 'Artist Name' };
    const taggedBuffer = await NodeID3.Promise.write(tags, fileBuffer);
    await fs.writeFile('./song.mp3', taggedBuffer);
  } catch (err) {
    console.error('Error:', err);
  }
}
```
```

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

### Using Alias vs Raw Frame IDs

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Functions accept either friendly aliases or raw ID3v2 frame identifiers, and these can be mixed within the same object.

```javascript
// Friendly alias
{ title: 'Song' }

// Raw frame ID
{ TIT2: 'Song' }

// Mixed
{ title: 'Song', TPE1: 'Artist' }
```

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

### update(tags, filebuffer, options, fn)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Asynchronously updates ID3 tags in a buffer using a callback function.

```APIDOC
## update(tags: Tags, filebuffer: Buffer, options?: Object, fn: Function)

### Description
Asynchronously updates ID3 tags in a buffer.

### Parameters
- **tags** (Tags) - Required - Tags to update
- **filebuffer** (Buffer) - Required - Buffer containing file data
- **options** (Object) - Optional - Read options
- **fn** (Function) - Required - Callback with error and updated buffer

### Returns
- **void**
```

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

### Promise.read(filebuffer, options)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Reads ID3 tags from a file or buffer using Promises, with optional configuration.

```APIDOC
## Promise.read(filebuffer: Buffer | string, options?: Object)

### Description
Reads ID3 tags from a file or buffer using Promises.

### Signature
`Promise.read(filebuffer: Buffer | string, options?: Object): Promise<Tags>`

### Parameters
- **filebuffer** (Buffer | string) - Required - Buffer or filepath
- **options** (Object) - Optional - Read options (include, exclude, onlyRaw, noRaw)

### Returns
- **Promise<Tags>** - Resolves with parsed tags object

### Rejects
- File system errors, invalid ID3 data
```

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

### Verify NodeID3 Module Exports

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Use this script to check the availability of core functions and constants in the node-id3 library.

```javascript
const NodeID3 = require('node-id3')

// Verify all exports exist
console.log(typeof NodeID3.write)              // 'function'
console.log(typeof NodeID3.read)               // 'function'
console.log(typeof NodeID3.create)             // 'function'
console.log(typeof NodeID3.update)             // 'function'
console.log(typeof NodeID3.removeTags)         // 'function'
console.log(typeof NodeID3.removeTagsFromBuffer) // 'function'
console.log(typeof NodeID3.TagConstants)       // 'object'
console.log(typeof NodeID3.Promise)            // 'object'
console.log(typeof NodeID3.Promise.read)       // 'function'
```

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

### Manage multiple values in frames

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Update frames that support multiple values, such as user-defined text, which merge based on description keys.

```javascript
// Write
NodeID3.write({
  userDefinedText: [
    { description: 'KEY1', value: 'value1' },
    { description: 'KEY2', value: 'value2' }
  ]
}, './song.mp3')

// Update - merges by description key
NodeID3.update({
  userDefinedText: [
    { description: 'KEY1', value: 'updated' },
    { description: 'KEY3', value: 'new' }
  ]
}, './song.mp3')

// Result: KEY1 (updated), KEY2 (preserved), KEY3 (added)
```

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

### Define User-Defined Text Fields

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Structure for custom TXXX frames using an array of objects.

```javascript
{
  userDefinedText: [
    { description: 'CUSTOM_KEY', value: 'Custom Value' }
  ]
}
```

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

### read(filebuffer: string | Buffer, fn: Function)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Asynchronously reads ID3 tags from a file or buffer using a callback.

```APIDOC
## read(filebuffer: string | Buffer, fn: Function)

### Description
Reads ID3 tags from a file or buffer asynchronously.

### Parameters
- **filebuffer** (string | Buffer) - Required - Filepath string or Buffer with file data
- **fn** (Function) - Required - Callback with error and tags (err: NodeJS.ErrnoException | null, tags: Tags | null) => void

### Returns
- **void**
```

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

### Handle Promise Rejections

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/errors.md

Use try/catch blocks to handle errors when performing asynchronous ID3 operations.

```javascript
const NodeID3 = require('node-id3')

async function safeTags() {
  try {
    const tags = await NodeID3.Promise.read('./song.mp3')
    console.log('Tags:', tags)
  } catch (err) {
    console.error('Promise rejected:', err.message)
    console.error('Error code:', err.code)
  }
}

safeTags()
```

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

### read() function signatures

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Reads ID3 tags from a file or buffer, with optional configuration objects.

```javascript
read(filebuffer: string | Buffer): Tags
read(filebuffer: string | Buffer, options: Object): Tags
read(filebuffer: string | Buffer, fn: (err: Error | null, tags: Tags | null) => void): void
read(filebuffer: string | Buffer, options: Object, fn: (err: Error | null, tags: Tags | null) => void): void
```

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

### Perform Promise-based ID3 Tag Operations

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Demonstrates reading and updating ID3 tags using the asynchronous Promise-based API.

```javascript
const NodeID3 = require('node-id3')

async function processTags() {
  const tags = await NodeID3.Promise.read('./song.mp3')
  await NodeID3.Promise.update({ title: 'New Title' }, './song.mp3')
}
```

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

### Define Simple Text Tags

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/README.md

Standard object structure for basic ID3 text frames.

```javascript
{
  title: 'Song Title',
  artist: 'Artist Name',
  album: 'Album Name',
  year: '2024',
  trackNumber: '1/12',
  genre: 'Rock'
}
```

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

### Handle File Write Callback Errors

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/errors.md

Use this pattern to catch file system or operation errors when writing ID3 tags to a file.

```javascript
NodeID3.write(tags, './song.mp3', (err) => {
  if (err) {
    console.error('Error:', err.message)
    console.error('Code:', err.code)
  } else {
    console.log('Success')
  }
})
```

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

### Handle unsupported text encoding

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/errors.md

Illustrates that providing an invalid encoding byte causes the library to fall back to the default ISO-8859-1 encoding.

```javascript
const buffer = ID3Util.stringToEncodedBuffer('text', 5)
// 5 is invalid encoding byte
// Falls back to ISO-8859-1 (default)
```

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

### Perform Asynchronous Operations with Callbacks

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/usage-patterns.md

Handles file reading and updating using standard Node.js callback patterns.

```javascript
const NodeID3 = require('node-id3')

NodeID3.read('./song.mp3', (err, tags) => {
  if (err) {
    console.error('Error:', err.message)
  } else {
    console.log('Title:', tags.title)
    
    // Update with callback
    NodeID3.update({ title: 'New Title' }, './song.mp3', (err) => {
      if (!err) {
        console.log('Updated')
      }
    })
  }
})
```

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

### NodeID3.write(tags, file)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/frame-identifiers.md

Writes ID3 tags to a file using either friendly aliases, raw frame IDs, or a mix of both.

```APIDOC
## NodeID3.write(tags, file)

### Description
Writes ID3 tags to the specified file. Tags can be provided as an object using friendly aliases (e.g., 'title'), raw frame IDs (e.g., 'TIT2'), or a combination of both.

### Parameters
- **tags** (Object) - Required - An object containing the tag data to write.
- **file** (String) - Required - The path to the .mp3 file.

### Example
```javascript
const NodeID3 = require('node-id3');
const tags = {
  title: 'Song Title', // Alias
  TPE1: 'Artist Name' // Raw ID
};
NodeID3.write(tags, './song.mp3');
```
```

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

### update(tags, filepath, options, fn)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Asynchronously updates ID3 tags in a file using a callback function.

```APIDOC
## update(tags: Tags, filepath: string, options?: Object, fn: Function)

### Description
Asynchronously updates ID3 tags in a file.

### Parameters
- **tags** (Tags) - Required - Tags to update
- **filepath** (string) - Required - Path to file
- **options** (Object) - Optional - Read options
- **fn** (Function) - Required - Callback with error (null on success)

### Returns
- **void**
```

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

### Add album art

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/00-START-HERE.md

Attaches an image buffer to the ID3 tags of a file, specifying the MIME type and frame type.

```javascript
NodeID3.write({
  image: {
    mime: 'image/jpeg',
    type: { id: 3 },  // Front cover
    imageBuffer: fs.readFileSync('./cover.jpg')
  }
}, './song.mp3')
```

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

### Use encodeSize and decodeSize

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Converts a number to a 4-byte buffer and back using ID3v2 size encoding.

```javascript
const ID3Util = require('./src/ID3Util')

const size = 1000
const encoded = ID3Util.encodeSize(size)  // 4-byte buffer
const decoded = ID3Util.decodeSize(encoded)  // 1000
```

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

### Write tags to file

Source: https://github.com/zazama/node-id3/blob/0.2/README.md

Write tags to an existing file, removing any existing tags.

```javascript
const success = NodeID3.write(tags, filepath) // Returns true/Error
// async version
NodeID3.write(tags, file, function(err) {  })
```

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

### Handle Read Callback Errors

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/errors.md

Check the error parameter to identify file system issues when reading tags from a file.

```javascript
NodeID3.read('./song.mp3', (err, tags) => {
  if (err) {
    console.error('Read error:', err.code)
  } else {
    console.log('Tags:', tags)
  }
})
```

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

### Use terminationBuffer

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Generates 1 or 2-byte null termination buffers based on encoding.

```javascript
const ID3Util = require('./src/ID3Util')

const term1 = ID3Util.terminationBuffer(0x00)  // Buffer: [0x00]
const term2 = ID3Util.terminationBuffer(0x01)  // Buffer: [0x00, 0x00]
```

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

### read(filebuffer: string | Buffer)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Synchronously reads ID3 tags from a file or buffer without additional options.

```APIDOC
## read(filebuffer: string | Buffer)

### Description
Reads ID3 tags from a file or buffer synchronously.

### Parameters
- **filebuffer** (string | Buffer) - Required - Filepath string or Buffer with file data

### Returns
- **Tags** (Object) - Object with parsed tags (includes raw property with raw frame data)
```

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

### NodeID3.Promise.write

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Writes ID3 tags to a file or buffer.

```APIDOC
## Promise.write(tags, file)

### Description
Writes the provided tags to the specified file path or buffer.

### Parameters
- **tags** (Tags) - Required - The ID3 tags to write.
- **file** (Buffer|string) - Required - The target file path or buffer.

### Returns
- **Promise<Buffer|boolean>** - Returns a buffer if input was a buffer, or a boolean indicating success if input was a file path.
```

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

### Use stringToEncodedBuffer and bufferToDecodedString

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Encodes and decodes strings using specific ID3 encoding bytes.

```javascript
const ID3Util = require('./src/ID3Util')

const encoded = ID3Util.stringToEncodedBuffer('Hello', 0x03)  // UTF-8
const decoded = ID3Util.bufferToDecodedString(encoded, 0x03)  // 'Hello'
```

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

### Access FRAME_IDENTIFIERS

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/internals-and-utilities.md

Demonstrates how to access the mapping of friendly aliases to ID3 frame IDs for different versions.

```javascript
FRAME_IDENTIFIERS = {
  v2: { /* 3-char IDs */ },
  v3: { /* 4-char IDs */ },
  v4: { /* 4-char IDs */ }
}
```

```javascript
const defs = require('./src/ID3Definitions')
console.log(defs.FRAME_IDENTIFIERS.v3.title)  // 'TIT2'
console.log(defs.FRAME_IDENTIFIERS.v3.artist) // 'TPE1'
```

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

### write() function signatures

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/module-exports.md

Writes ID3 tags to a file or buffer, supporting both synchronous and asynchronous operations.

```javascript
write(tags: Tags, filebuffer: Buffer): Buffer
write(tags: Tags, filepath: string): boolean | Error
write(tags: Tags, filebuffer: Buffer, fn: (err: null, buffer: Buffer) => void): void
write(tags: Tags, filepath: string, fn: (err: Error | null) => void): void
```

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

### Writing tags to a file

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/promise-api.md

Defines the signature and usage for writing ID3 tags directly to a file path using the Promise API.

```javascript
Promise.write(tags: Tags, filepath: string): Promise<boolean>
```

```javascript
const NodeID3 = require('node-id3')

async function writeTagsToFile() {
  try {
    const tags = {
      title: 'Tomorrow',
      artist: 'Kevin Penkin',
      album: 'Made in Abyss'
    }
    
    await NodeID3.Promise.write(tags, './music/song.mp3')
    console.log('Tags written successfully')
  } catch (err) {
    console.error('Write error:', err.message)
  }
}

writeTagsToFile()
```

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

### Create ID3 tag buffer asynchronously

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Generates an ID3 tag buffer and returns it via a callback function.

```javascript
const NodeID3 = require('node-id3')

const tags = { title: 'Song', artist: 'Artist' }

NodeID3.create(tags, (buffer) => {
  console.log('Tag buffer created, size:', buffer.length)
})
```

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

### update(tags, filepath, options)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/api-reference-core-functions.md

Synchronously updates ID3 tags in a file at the specified path.

```APIDOC
## update(tags: Tags, filepath: string, options?: Object)

### Description
Updates ID3 tags in a file, preserving existing tags not being overwritten.

### Parameters
- **tags** (Tags) - Required - Tags to update
- **filepath** (string) - Required - Path to file
- **options** (Object) - Optional - Read options (include, exclude, onlyRaw, noRaw)

### Returns
- **boolean | Error** - true on success, Error object on failure
```

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

### Write tags using raw frame IDs

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/frame-identifiers.md

Use raw ID3 frame identifiers (e.g., TIT2, TPE1) to write metadata.

```javascript
const NodeID3 = require('node-id3')

const tags = {
  TIT2: 'Song Title',
  TPE1: 'Artist Name',
  TALB: 'Album Name'
}

NodeID3.write(tags, './song.mp3')
```

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

### NodeID3.read(file, options)

Source: https://github.com/zazama/node-id3/blob/0.2/_autodocs/frame-identifiers.md

Reads ID3 tags from a file, with options to include or exclude specific frame IDs.

```APIDOC
## NodeID3.read(file, options)

### Description
Reads ID3 tags from the specified file. You can filter which frames to include or exclude using their frame IDs.

### Parameters
- **file** (String) - Required - The path to the .mp3 file.
- **options** (Object) - Optional - Configuration object.
  - **include** (Array) - Optional - List of frame IDs to include.
  - **exclude** (Array) - Optional - List of frame IDs to exclude.

### Example
```javascript
const NodeID3 = require('node-id3');
const tags = NodeID3.read('./song.mp3', {
  include: ['TIT2', 'TPE1']
});
```
```
Tokens:
Raw