Add meta

Author: dy

README.md

@@ -81,6 +81,30 @@ Works with any async iterable source.
 | `application` | `'audio'`, `'voip'`, or `'lowdelay'` | opus |
 
 
+### Metadata
+
+Splice tags, pictures, markers and regions into encoded bytes. Available for `wav`, `mp3`, `flac`.
+
+```js
+import encode from 'encode-audio'
+import { wav } from 'encode-audio/meta'
+
+let bytes = await encode.wav(channelData, { sampleRate: 44100 })
+let out = wav(bytes, {
+  meta: { title: 'Hare Krishna', artist: 'Prabhupada', year: '1966' },
+  markers: [{ sample: 44100, label: 'verse' }],
+  regions: [{ sample: 88200, length: 44100, label: 'chorus' }]
+})
+```
+
+Each codec sub-package also exposes its writer directly:
+
+```js
+import { writeMeta } from '@audio/encode-mp3/meta'
+let tagged = writeMeta(mp3Bytes, { meta: { title: 'foo' } })
+```
+
+
 ## See also
 
 * [audio-decode](https://github.com/audiojs/audio-decode) – decode any audio format to raw samples.

meta.js

@@ -0,0 +1,11 @@
+/**
+ * Meta writers — re-export from codec packages.
+ * @module encode-audio/meta
+ *
+ * import { wav, mp3, flac } from 'encode-audio/meta'
+ * let out = wav(bytes, { meta, markers, regions })
+ */
+
+export { writeMeta as wav } from '@audio/encode-wav/meta'
+export { writeMeta as mp3 } from '@audio/encode-mp3/meta'
+export { writeMeta as flac } from '@audio/encode-flac/meta'

package.json

@@ -13,13 +13,15 @@
       "default": "./audio-encode.js"
     },
     "./stream": "./stream.js",
+    "./meta": "./meta.js",
     "./package.json": "./package.json"
   },
   "files": [
     "audio-encode.js",
     "audio-encode.d.ts",
     "stream.js",
     "stream.d.ts",
+    "meta.js",
     "LICENSE"
   ],
   "workspaces": [

packages/encode-flac/meta.js

@@ -0,0 +1,112 @@
+/**
+ * FLAC metadata writer — Vorbis comments, pictures.
+ * @module @audio/encode-flac/meta
+ */
+
+const TE = new TextEncoder()
+
+// ── Constants ───────────────────────────────────────────────────────────
+
+const STREAMINFO = 0, VORBIS_COMMENT = 4, PICTURE = 6, PADDING = 1
+
+const VORBIS_MAP_REV = {
+  title: 'TITLE', artist: 'ARTIST', album: 'ALBUM', albumartist: 'ALBUMARTIST',
+  composer: 'COMPOSER', genre: 'GENRE', year: 'DATE', track: 'TRACKNUMBER',
+  disc: 'DISCNUMBER', bpm: 'BPM', key: 'KEY', comment: 'COMMENT',
+  copyright: 'COPYRIGHT', isrc: 'ISRC', publisher: 'PUBLISHER', software: 'ENCODER',
+  lyrics: 'LYRICS'
+}
+
+// ── Binary helpers ──────────────────────────────────────────────────────
+
+function u24be(b, o) { return (b[o] << 16) | (b[o + 1] << 8) | b[o + 2] }
+function wu32le(b, o, v) { b[o] = v; b[o + 1] = v >>> 8; b[o + 2] = v >>> 16; b[o + 3] = v >>> 24 }
+function wu32be(b, o, v) { b[o] = (v >>> 24) & 0xff; b[o + 1] = (v >>> 16) & 0xff; b[o + 2] = (v >>> 8) & 0xff; b[o + 3] = v & 0xff }
+function fourcc(b, o) { return String.fromCharCode(b[o], b[o + 1], b[o + 2], b[o + 3]) }
+
+// ── Block builders ──────────────────────────────────────────────────────
+
+function buildVorbisComment(meta) {
+  let vendor = TE.encode('audio')
+  let entries = []
+  for (let k in VORBIS_MAP_REV) {
+    let v = meta[k]
+    if (v == null || v === '') continue
+    entries.push(TE.encode(`${VORBIS_MAP_REV[k]}=${v}`))
+  }
+  let size = 4 + vendor.length + 4
+  for (let e of entries) size += 4 + e.length
+  let out = new Uint8Array(size)
+  let pos = 0
+  wu32le(out, pos, vendor.length); pos += 4
+  out.set(vendor, pos); pos += vendor.length
+  wu32le(out, pos, entries.length); pos += 4
+  for (let e of entries) { wu32le(out, pos, e.length); pos += 4; out.set(e, pos); pos += e.length }
+  return out
+}
+
+function buildFlacPicture(p) {
+  let mimeBytes = TE.encode(p.mime || 'image/jpeg')
+  let descBytes = TE.encode(p.description || '')
+  let size = 4 + 4 + mimeBytes.length + 4 + descBytes.length + 16 + 4 + p.data.length
+  let out = new Uint8Array(size)
+  let pos = 0
+  wu32be(out, pos, p.type ?? 3); pos += 4
+  wu32be(out, pos, mimeBytes.length); pos += 4
+  out.set(mimeBytes, pos); pos += mimeBytes.length
+  wu32be(out, pos, descBytes.length); pos += 4
+  out.set(descBytes, pos); pos += descBytes.length
+  pos += 16  // width/height/depth/colors = 0
+  wu32be(out, pos, p.data.length); pos += 4
+  out.set(p.data, pos)
+  return out
+}
+
+function buildFlacBlock(type, body, last) {
+  let out = new Uint8Array(4 + body.length)
+  out[0] = (last ? 0x80 : 0) | (type & 0x7f)
+  out[1] = (body.length >> 16) & 0xff
+  out[2] = (body.length >> 8) & 0xff
+  out[3] = body.length & 0xff
+  out.set(body, 4)
+  return out
+}
+
+/** Splice meta into FLAC bytes. Returns new Uint8Array. */
+export function writeMeta(bytes, { meta = {} } = {}) {
+  if (bytes.length < 4 || fourcc(bytes, 0) !== 'fLaC') return bytes
+  let off = 4, streamInfo = null, others = []
+  while (off + 4 <= bytes.length) {
+    let hdr = bytes[off]
+    let last = !!(hdr & 0x80), type = hdr & 0x7f
+    let size = u24be(bytes, off + 1)
+    let body = bytes.subarray(off + 4, off + 4 + size)
+    if (type === STREAMINFO) streamInfo = body
+    else if (type !== VORBIS_COMMENT && type !== PICTURE && type !== PADDING) others.push({ type, body })
+    off += 4 + size
+    if (last) break
+  }
+  let audioStart = off
+  if (!streamInfo) return bytes
+
+  let blocks = []
+  blocks.push({ type: STREAMINFO, body: streamInfo })
+  for (let o of others) blocks.push(o)
+  blocks.push({ type: VORBIS_COMMENT, body: buildVorbisComment(meta) })
+  if (meta.pictures) for (let p of meta.pictures) blocks.push({ type: PICTURE, body: buildFlacPicture(p) })
+
+  let headerSize = 4
+  let encoded = []
+  for (let i = 0; i < blocks.length; i++) {
+    let b = buildFlacBlock(blocks[i].type, blocks[i].body, i === blocks.length - 1)
+    encoded.push(b)
+    headerSize += b.length
+  }
+  let audioPart = bytes.subarray(audioStart)
+  let out = new Uint8Array(headerSize + audioPart.length)
+  out.set(TE.encode('fLaC'), 0)
+  let pos = 4
+  for (let e of encoded) { out.set(e, pos); pos += e.length }
+  out.set(audioPart, pos)
+  return out
+}

packages/encode-flac/package.json

@@ -7,11 +7,13 @@
   "types": "flac-encode.d.ts",
   "exports": {
     ".": "./flac-encode.js",
+    "./meta": "./meta.js",
     "./package.json": "./package.json"
   },
   "files": [
     "flac-encode.js",
     "flac-encode.d.ts",
+    "meta.js",
     "LICENSE"
   ],
   "keywords": [

packages/encode-mp3/meta.js

@@ -0,0 +1,102 @@
+/**
+ * ID3v2 metadata writer for MP3 files.
+ * @module @audio/encode-mp3/meta
+ */
+
+const TE = new TextEncoder()
+
+// ── Constants ───────────────────────────────────────────────────────────
+
+const ID3_MAP_REV = {
+  title: 'TIT2', artist: 'TPE1', album: 'TALB', albumartist: 'TPE2',
+  composer: 'TCOM', genre: 'TCON', year: 'TDRC', track: 'TRCK',
+  disc: 'TPOS', bpm: 'TBPM', key: 'TKEY', copyright: 'TCOP',
+  isrc: 'TSRC', publisher: 'TPUB', software: 'TENC',
+  comment: 'COMM', lyrics: 'USLT'
+}
+
+// ── Binary helpers ──────────────────────────────────────────────────────
+
+function synchsafe(b, o) { return (b[o] << 21) | (b[o + 1] << 14) | (b[o + 2] << 7) | b[o + 3] }
+function wSynchsafe(b, o, v) { b[o] = (v >>> 21) & 0x7f; b[o + 1] = (v >>> 14) & 0x7f; b[o + 2] = (v >>> 7) & 0x7f; b[o + 3] = v & 0x7f }
+
+// ── ID3v2 builder ───────────────────────────────────────────────────────
+
+function buildId3Frame(id, body) {
+  let out = new Uint8Array(10 + body.length)
+  out.set(TE.encode(id), 0)
+  wSynchsafe(out, 4, body.length)
+  out.set(body, 10)
+  return out
+}
+
+function buildId3v2(meta) {
+  let frames = []
+  for (let k in ID3_MAP_REV) {
+    let v = meta[k]
+    if (v == null || v === '') continue
+    let id = ID3_MAP_REV[k]
+    let body
+    if (id === 'COMM' || id === 'USLT') {
+      let txt = TE.encode(String(v))
+      body = new Uint8Array(1 + 3 + 1 + txt.length + 1)
+      body[0] = 3
+      body.set(TE.encode('eng'), 1)
+      body[4] = 0
+      body.set(txt, 5)
+      body[body.length - 1] = 0
+    } else {
+      let enc = TE.encode(String(v))
+      body = new Uint8Array(1 + enc.length)
+      body[0] = 3
+      body.set(enc, 1)
+    }
+    frames.push(buildId3Frame(id, body))
+  }
+  if (meta.pictures) {
+    for (let p of meta.pictures) {
+      let mime = TE.encode((p.mime || 'image/jpeg') + '\0')
+      let desc = TE.encode((p.description || '') + '\0')
+      let body = new Uint8Array(1 + mime.length + 1 + desc.length + p.data.length)
+      body[0] = 3
+      let pos = 1
+      body.set(mime, pos); pos += mime.length
+      body[pos++] = p.type ?? 3
+      body.set(desc, pos); pos += desc.length
+      body.set(p.data, pos)
+      frames.push(buildId3Frame('APIC', body))
+    }
+  }
+
+  if (!frames.length) return null
+  let totalFrameSize = frames.reduce((n, f) => n + f.length, 0)
+  let out = new Uint8Array(10 + totalFrameSize)
+  out[0] = 0x49; out[1] = 0x44; out[2] = 0x33
+  out[3] = 4; out[4] = 0; out[5] = 0
+  wSynchsafe(out, 6, totalFrameSize)
+  let pos = 10
+  for (let f of frames) { out.set(f, pos); pos += f.length }
+  return out
+}
+
+function stripMp3Tags(bytes) {
+  let start = 0, end = bytes.length
+  if (bytes.length >= 10 && bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33) {
+    start = 10 + synchsafe(bytes, 6)
+  }
+  if (bytes.length >= 128 && bytes[end - 128] === 0x54 && bytes[end - 127] === 0x41 && bytes[end - 126] === 0x47) {
+    end -= 128
+  }
+  return bytes.subarray(start, end)
+}
+
+/** Splice ID3v2 tag into MP3 bytes. Returns new Uint8Array. */
+export function writeMeta(bytes, { meta = {} } = {}) {
+  let audio = stripMp3Tags(bytes)
+  let tag = buildId3v2(meta)
+  if (!tag) return audio
+  let out = new Uint8Array(tag.length + audio.length)
+  out.set(tag, 0)
+  out.set(audio, tag.length)
+  return out
+}

packages/encode-mp3/package.json

@@ -7,11 +7,13 @@
   "types": "mp3-encode.d.ts",
   "exports": {
     ".": "./mp3-encode.js",
+    "./meta": "./meta.js",
     "./package.json": "./package.json"
   },
   "files": [
     "mp3-encode.js",
     "mp3-encode.d.ts",
+    "meta.js",
     "LICENSE"
   ],
   "keywords": [