node-id3
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.3 • Public • Published

    node-id3

    GitHub package.json version Travis (.org) Codecov Code Climate maintainability npm

    node-id3 is an ID3-Tag library written in JavaScript.

    Installation

    npm install node-id3
    

    Usage

    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"
    }

    Write tags to file

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

    Write tags to filebuffer

    const success = NodeID3.write(tags, filebuffer) // Returns Buffer
    // async version
    NodeID3.write(tags, file, function(err, buffer) {  })

    Update existing tags of file or buffer

    This will write new/changed values but keep all others

    const success = NodeID3.update(tags, filepath) //  Returns true/Error
    const success = NodeID3.update(tags, filebuffer) //  Returns Buffer
    NodeID3.update(tags, filepath, function(err, buffer) {  })
    NodeID3.update(tags, filebuffer, function(err, buffer) {  })
    
    // Possible options
    const options = {
        include: ['TALB', 'TIT2'],    // only read the specified tags (default: all)
        exclude: ['APIC']            // don't read the specified tags (default: [])
    }
    
    NodeID3.update(tags, filepath, options)
    const success = NodeID3.update(tags, filebuffer, options)
    NodeID3.update(tags, filepath, options, function(err, buffer) {  })
    NodeID3.update(tags, filebuffer, options, function(err, buffer) {  })

    Create tags as buffer

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

    Reading ID3-Tags

    const tags = NodeID3.read(file)
    NodeID3.read(file, function(err, tags) {})
    /*
        tags: {
            title: "Tomorrow",
            artist: "Kevin Penkin",
            image: {
              mime: "image/jpeg",
              type: {
                id: 3,
                name: "front cover"
              },
              description: String,
              imageBuffer: Buffer
            },
            raw: {
              TIT2: "Tomorrow",
              TPE1: "Kevin Penkin",
              APIC: Object (See above)
            }
          }
    */
    
    // Possible options
    const options = {
        include: ['TALB', 'TIT2'],    // only read the specified tags (default: all)
        exclude: ['APIC'],            // don't read the specified tags (default: [])
        onlyRaw: false,               // only return raw object (default: false)
        noRaw: false                  // don't generate raw object (default: false)
    }
    const tags = NodeID3.read(file, options)

    Removing ID3-Tags from file/buffer

    const success = NodeID3.removeTags(filepath)  //  returns true/Error
    NodeID3.removeTags(filepath, function(err) {  })
    
    let bufferWithoutID3Frame = NodeID3.removeTagsFromBuffer(filebuffer)  //  Returns Buffer

    Using Promises (available starting with v0.2)

    const NodeID3Promise = require('node-id3').Promise
    
    NodeID3.write(tags, fileOrBuffer)
    NodeID3.update(tags, fileOrBuffer)
    NodeID3.create(tags)
    NodeID3.read(filepath)
    NodeID3.removeTags(filepath)

    Supported aliases/fields

    album:
    bpm:
    composer:
    genre:
    copyright:
    date:
    playlistDelay:
    encodedBy:
    textWriter:
    fileType:
    time:
    contentGroup:
    title:
    subtitle:
    initialKey:
    language:
    length:
    mediaType:
    originalTitle:
    originalFilename:
    originalTextwriter:
    originalArtist:
    originalYear:
    fileOwner:
    artist:
    performerInfo: // (album artist)
    conductor:
    remixArtist:
    partOfSet:
    publisher:
    trackNumber:
    recordingDates:
    internetRadioName:
    internetRadioOwner:
    size:
    ISRC:
    encodingTechnology:
    year:
    comment: {
      language: "eng",
      text: "mycomment"
    }
    unsynchronisedLyrics: {
      language: "eng",
      text: "lyrics"
    }
    userDefinedText: [{
      description: "txxx name",
      value: "TXXX value text"
    }, {
      description: "txxx name 2",
      value: "TXXX value text 2"
    }] // Care, update doesn't delete non-passed array items!
    image: {
      mime: "image/png",
      type: {
        id: 3,
        name: "front cover
      }, // See https://en.wikipedia.org/wiki/ID3#ID3v2_embedded_image_extension
      description: "image description",
      imageBuffer: (file buffer)
    },
    popularimeter: {
      email: "mail@example.com",
      rating: 192,  // 1-255
      counter: 12
    },
    private: [{
      ownerIdentifier: "AbC",
      data: "asdoahwdiohawdaw"
    }, {
      ownerIdentifier: "AbCSSS",
      data: Buffer.from([0x01, 0x02, 0x05])
    }],
    chapter: [{
      elementID: "Hey!", // THIS MUST BE UNIQUE!
      startTimeMs: 5000,
      endTimeMs: 8000,
      startOffsetBytes: 123, // OPTIONAL!
      endOffsetBytes: 456,   // OPTIONAL!
      tags: {                // OPTIONAL
        title: "abcdef",
        artist: "akshdas"
      }
    }],
    tableOfContents: [{
      elementID: "toc1",    // THIS MUST BE UNIQUE!
      isOrdered: false,     // OPTIONAL, tells a player etc. if elements are in a specific order
      elements: ['chap1'],  // OPTIONAL but most likely needed, contains the chapter/tableOfContents elementIDs
      tags: {               // OPTIONAL
        title: "abcdef"
      }  
    }],
    commercialUrl: ["commercialurl.com"], // array or single string
    copyrightUrl: "example.com",
    fileUrl: "example.com",
    artistUrl: ["example.com"], // array or single string
    audioSourceUrl: "example.com",
    radioStationUrl: "example.com",
    paymentUrl: "example.com",
    publisherUrl: "example.com",
    userDefinedUrl: [{
      description: "URL description"
      url: "https://example.com/"
    }] // array or single object
    

    Supported raw IDs

    You can also use the currently supported raw tags like TALB instead of album etc.

    album:                "TALB"
    bpm:                  "TBPM"
    composer:             "TCOM"
    genre:                "TCON"
    copyright:            "TCOP"
    date:                 "TDAT"
    playlistDelay:        "TDLY"
    encodedBy:            "TENC"
    textWriter:           "TEXT"
    fileType:             "TFLT"
    time:                 "TIME"
    contentGroup:         "TIT1"
    title:                "TIT2"
    subtitle:             "TIT3"
    initialKey:           "TKEY"
    language:             "TLAN"
    length:               "TLEN"
    mediaType:            "TMED"
    originalTitle:        "TOAL"
    originalFilename:     "TOFN"
    originalTextwriter:   "TOLY"
    originalArtist:       "TOPE"
    originalYear:         "TORY"
    fileOwner:            "TOWN"
    artist:               "TPE1"
    performerInfo:        "TPE2"    (album artist)
    conductor:            "TPE3"
    remixArtist:          "TPE4"
    partOfSet:            "TPOS"
    publisher:            "TPUB"
    trackNumber:          "TRCK"
    recordingDates:       "TRDA"
    internetRadioName:    "TRSN"
    internetRadioOwner:   "TRSO"
    size:                 "TSIZ"
    ISRC:                 "TSRC"
    encodingTechnology:   "TSSE"
    year:                 "TYER"
    comment:              "COMM"
    image:                "APIC"
    unsynchronisedLyrics  "USLT"
    userDefinedText       "TXXX"
    popularimeter         "POPM"
    private               "PRIV"
    chapter               "CHAP"
    tableOfContents       "CTOC"
    commercialUrl         "WCOM"
    copyrightUrl          "WCOP"
    fileUrl               "WOAF"
    artistUrl             "WOAR"
    audioSourceUrl        "WOAS"
    radioStationUrl       "WORS"
    paymentUrl            "WPAY"
    publisherUrl          "WPUB"
    userDefinedUrl        "WXXX"
    

    Install

    npm i node-id3

    DownloadsWeekly Downloads

    1,427

    Version

    0.2.3

    License

    MIT

    Unpacked Size

    122 kB

    Total Files

    16

    Last publish

    Collaborators

    • zazama