Add separate ID3v1 support

README.md

@@ -73,6 +73,33 @@ NodeID3.update(tags, filepath, options, function(err, buffer) {  })
 NodeID3.update(tags, filebuffer, options, function(err, buffer) {  })
 ```
 
+### ID3v1 tags
+
+ID3v1 operations are separate from the existing ID3v2 `write()` and `update()` functions. Applications that maintain
+both formats must map compatible fields and call the ID3v1 API explicitly.
+
+ID3v1 supports title, artist, and album fields up to 30 bytes, a four-byte year, and a 28-byte ID3v1.1 comment. It
+also supports numeric track numbers and genre IDs from 0 through 255. Values must already be expressed in their ID3v1
+representation; genre names and ID3v2 track forms such as `3/12` are not converted automatically.
+
+Text is encoded as Latin-1. By default, unsupported characters become `?`, embedded nulls are removed, and fields are
+truncated to their encoded byte limits. Use `id3v1Truncation: 'error'` to reject lossy values before changing a file.
+
+The dedicated APIs read, replace, or remove only the final 128-byte ID3v1 tag. `writeId3v1()` always writes ID3v1.1;
+the `version` property returned by `readId3v1()` reports the layout that was read.
+
+```javascript
+NodeID3.write(tags, filepath) // Optional, separate ID3v2 operation
+NodeID3.writeId3v1({ title: 'Tomorrow', trackNumber: 3 }, filepath)
+
+const id3v1 = NodeID3.readId3v1(filepath) // ID3v1 object or null
+const removed = NodeID3.removeId3v1(filebuffer) // Buffer without the trailing ID3v1 tag
+
+NodeID3.readId3v1(filepath, function(err, tag) {  })
+NodeID3.writeId3v1({ title: 'Tomorrow' }, filebuffer, function(err, buffer) {  })
+NodeID3.removeId3v1(filepath, function(err) {  })
+```
+
 ### Create tags as buffer
 
 The create method will return a buffer of your ID3-Tag. You can use it to e.g. write it into a file yourself instead of using the write method.
@@ -133,11 +160,14 @@ let bufferWithoutID3Frame = NodeID3.removeTagsFromBuffer(filebuffer)  //  Return
 ```javascript
 const NodeID3Promise = require('node-id3').Promise
 
-NodeID3.write(tags, fileOrBuffer)
-NodeID3.update(tags, fileOrBuffer)
-NodeID3.create(tags)
-NodeID3.read(filepath)
-NodeID3.removeTags(filepath)
+NodeID3Promise.write(tags, fileOrBuffer)
+NodeID3Promise.update(tags, fileOrBuffer)
+NodeID3Promise.create(tags)
+NodeID3Promise.read(filepath)
+NodeID3Promise.readId3v1(filepath)
+NodeID3Promise.writeId3v1({ title: 'Tomorrow' }, fileOrBuffer)
+NodeID3Promise.removeId3v1(fileOrBuffer)
+NodeID3Promise.removeTags(filepath)
 ```
 
 ## Supported aliases/fields

index.d.ts

@@ -699,34 +699,96 @@ declare module "node-id3" {
             }
          }
       }
+
+      /**
+       * ID3v1 tag management
+       */
+      export type Id3v1Truncation = "truncate" | "error"
+      export interface Id3v1WriteOptions {
+         id3v1Truncation?: Id3v1Truncation
+      }
+      export interface Id3v1Tag {
+         title?: string,
+         artist?: string,
+         album?: string,
+         year?: string,
+         comment?: string,
+         trackNumber?: number,
+         genreId?: number,
+         version: "1.0" | "1.1"
+      }
+      export interface Id3v1WriteTag {
+         title?: string,
+         artist?: string,
+         album?: string,
+         year?: string,
+         comment?: string,
+         trackNumber?: number,
+         genreId?: number,
+         version?: "1.0" | "1.1"
+      }
+
       export function write(tags: Tags, filebuffer: Buffer): Buffer
       export function write(tags: Tags, filebuffer: Buffer, fun: (err: null, buffer: Buffer) => void): void
       export function write(tags: Tags, filepath: string): true | Error
       export function write(tags: Tags, filepath: string, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
+
       export function create(tags: Tags): Buffer
       export function create(tags: Tags, fn: (buffer: Buffer) => void): void
+
       export function read(filebuffer: string | Buffer): Tags
       export function read(filebuffer: string | Buffer, options: Object): Tags
       export function read(filebuffer: string | Buffer, fn: (err: NodeJS.ErrnoException | null, tags: Tags | null) => void): void
       export function read(filebuffer: string | Buffer, options: Object, fn: (err: NodeJS.ErrnoException | null, tags: Tags | null) => void): void
+
       export function update(tags: Tags, filebuffer: Buffer, options?: Object): Buffer
       export function update(tags: Tags, filepath: string, options?: Object): true | Error
       export function update(tags: Tags, filepath: string, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
       export function update(tags: Tags, filepath: string, options: Object, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
       export function update(tags: Tags, filebuffer: Buffer, fn: (err: NodeJS.ErrnoException | null, buffer?: Buffer) => void): void
       export function update(tags: Tags, filebuffer: Buffer, options: Object, fn: (err: NodeJS.ErrnoException | null, buffer?: Buffer) => void): void
+
       export function removeTags(filepath: string): true | Error
       export function removeTags(filepath: string, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
+
+      export function readId3v1(filebuffer: string | Buffer): Id3v1Tag | null
+      export function readId3v1(filebuffer: string | Buffer, fn: (err: NodeJS.ErrnoException | Error | null, tag: Id3v1Tag | null) => void): void
+
+      export function writeId3v1(tag: Id3v1WriteTag, filebuffer: Buffer, options?: Id3v1WriteOptions): Buffer
+      export function writeId3v1(tag: Id3v1WriteTag, filepath: string, options?: Id3v1WriteOptions): true | Error
+      export function writeId3v1(tag: Id3v1WriteTag, filebuffer: Buffer, fn: (err: NodeJS.ErrnoException | Error | null, buffer?: Buffer) => void): void
+      export function writeId3v1(tag: Id3v1WriteTag, filepath: string, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
+      export function writeId3v1(tag: Id3v1WriteTag, filebuffer: Buffer, options: Id3v1WriteOptions, fn: (err: NodeJS.ErrnoException | Error | null, buffer?: Buffer) => void): void
+      export function writeId3v1(tag: Id3v1WriteTag, filepath: string, options: Id3v1WriteOptions, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
+
+      export function removeId3v1(filebuffer: Buffer): Buffer
+      export function removeId3v1(filepath: string): true | Error
+      export function removeId3v1(filebuffer: Buffer, fn: (err: NodeJS.ErrnoException | Error | null, buffer?: Buffer) => void): void
+      export function removeId3v1(filepath: string, fn: (err: NodeJS.ErrnoException | Error | null) => void): void
+
       export const Promise: {
          write(tags: Tags, filebuffer: Buffer) : Promise<Buffer>,
          write(tags: Tags, filepath: string) : Promise<boolean>,
+
          create(tags: Tags) : Promise<Buffer>,
+
          read(filebuffer: Buffer, options?: Object) : Promise<Tags>,
          read(filepath: string, options?: Object) : Promise<Tags>,
-         update(tags: Tags, filebuffer: Buffer) : Promise<Buffer>,
-         update(tags: Tags, filepath: string) : Promise<boolean>,
+
+         update(tags: Tags, filebuffer: Buffer, options?: Object) : Promise<Buffer>,
+         update(tags: Tags, filepath: string, options?: Object) : Promise<boolean>,
+
+
+         removeId3v1(filebuffer: Buffer) : Promise<Buffer>,
+         removeId3v1(filepath: string) : Promise<boolean>,
+
          removeTags(filepath: string) : Promise<Buffer>,
-         removeTags(filebuffer: Buffer) : Promise<Buffer>
+         removeTags(filebuffer: Buffer) : Promise<Buffer>,
+
+         readId3v1(filebuffer: string | Buffer) : Promise<Id3v1Tag | null>,
+
+         writeId3v1(tag: Id3v1WriteTag, filebuffer: Buffer, options?: Id3v1WriteOptions) : Promise<Buffer>,
+         writeId3v1(tag: Id3v1WriteTag, filepath: string, options?: Id3v1WriteOptions) : Promise<boolean>,
       }
    }
    export = NodeID3

index.js

@@ -1,8 +1,12 @@
 const fs = require('fs')
 const ID3Definitions = require("./src/ID3Definitions")
-const ID3Util = require('./src/ID3Util')
-const ID3Helpers = require('./src/ID3Helpers')
-const { isFunction, isString } = require('./src/util')
+const ID3Util = require('./src/ID3Util')
+const ID3Helpers = require('./src/ID3Helpers')
+const { isFunction, isString } = require('./src/util')
+const ID3v1 = require('./src/ID3v1')
+const readId3v1 = ID3v1.readId3v1
+const writeId3v1 = ID3v1.writeId3v1
+const removeId3v1 = ID3v1.removeId3v1
 
 /*
 **  Used specification: http://id3.org/id3v2.3.0
@@ -316,16 +320,22 @@ const PromiseExport = {
     write: (tags, file) => makePromise(write.bind(null, tags, file)),
     update: (tags, file, options) => makePromise(update.bind(null, tags, file, options)),
     read: (file, options) => makePromise(read.bind(null, file, options)),
-    removeTags: (filepath) => makePromise(removeTags.bind(null, filepath))
+    removeTags: (filepath) => makePromise(removeTags.bind(null, filepath)),
+    readId3v1: (file) => makePromise(readId3v1.bind(null, file)),
+    writeId3v1: (tag, file, options) => makePromise(writeId3v1.bind(null, tag, file, options)),
+    removeId3v1: (file) => makePromise(removeId3v1.bind(null, file))
 }
 
 module.exports = {
     TagConstants: ID3Definitions.TagConstants,
     create,
     write,
-    update,
-    read,
-    removeTags,
+    update,
+    read,
+    readId3v1,
+    writeId3v1,
+    removeId3v1,
+    removeTags,
     removeTagsFromBuffer,
     Promise: PromiseExport
 }

package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-id3",
   "version": "0.2.9",
-  "description": "Pure JavaScript ID3v2 Tag writer and reader",
+  "description": "Pure JavaScript ID3 tag writer and reader",
   "author": "Jan Metzger <jan.metzger@gmx.net>",
   "main": "index.js",
   "repository": {
@@ -13,6 +13,7 @@
   },
   "keywords": [
     "ID3",
+    "ID3v1",
     "ID3v2",
     "metadata",
     "tags",