@audio/encode-wavpack 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, audiojs
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/LICENSE.wavpack

@@ -0,0 +1,25 @@
+                  Copyright (c) 1998 - 2025 David Bryant
+                          All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the copyright holder nor the names of its
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,49 @@
+# @audio/encode-wavpack [![npm](https://img.shields.io/npm/v/@audio/encode-wavpack)](https://www.npmjs.com/package/@audio/encode-wavpack) [![BSD-3-Clause](https://img.shields.io/badge/BSD--3--Clause-%E0%A5%90-white)](https://github.com/krishnized/license)
+
+Encode PCM audio samples to WavPack (.wv)
+
+```
+npm install @audio/encode-wavpack
+```
+
+```js
+import wavpack from '@audio/encode-wavpack'
+```
+
+[libwavpack](https://github.com/dbry/WavPack) (the reference WavPack 5 implementation, David Bryant) compiled to a single-file WASM ES module, encode-only (no file-input/decode side, no DSD — a leaner build than the full library). Lossless by default; hybrid/lossy on request. Block boundaries are decided purely by cumulative sample count, so output is byte-identical no matter how the input is chunked across `encode()` calls.
+
+```js
+let enc = await wavpack({ sampleRate: 48000, channels: 2, bitDepth: 16 })
+let chunk = enc.encode(channelData)  // → Uint8Array (any WavPack blocks this chunk completed)
+let tail = enc.flush()               // → Uint8Array (final block + APEv2 tag; frees the encoder)
+// concatenate chunk + tail for the complete .wv file
+```
+
+| Option | Default | |
+|---|---|---|
+| `sampleRate` | — | Required |
+| `channels` | `1` | |
+| `bitDepth` | `16` | `16`, `24`, `32` (integer) or `'float'` (32-bit IEEE-754) |
+| `hybrid` | `false` | Bitrate-per-sample (< 24, e.g. `4` ≈ 4 bits/sample) or kbps (≥ 24) — enables lossy hybrid mode. No `.wvc` correction file. |
+| `extraProcessing` | `0` | `0`-`6`, libwavpack's extra-processing level (`xmode`) |
+| `highQuality` | `false` | |
+| `veryHigh` | `false` | Implies `highQuality` |
+| `fast` | `false` | |
+| `blockSamples` | library default | Fixed WavPack block size, 16-131072 samples |
+| `meta` | — | APEv2 tags: `title`, `artist`, `album`, `albumartist`, `composer`, `genre`, `year`, `track`, `disc`, `comment`, `copyright`, `isrc`, `publisher`, `software`, `lyrics`, `pictures: [{mime, description, data}]` (written as `Cover Art (Front)`) |
+
+### Streaming
+
+```js
+let enc = await wavpack({ sampleRate: 44100, channels: 1, bitDepth: 16 })
+let a = enc.encode(chunk1)  // → Uint8Array (blocks completed so far, maybe empty)
+let b = enc.encode(chunk2)
+let c = enc.flush()         // → Uint8Array (final block + tag)
+// complete file = concat(a, b, c)
+```
+
+`encode()` returns whatever WavPack blocks were completed by that call — often nothing, since a block only closes once it has enough samples (`blockSamples`, or a size the library picks from the sample rate). `flush()` finalizes the last partial block, writes the APEv2 tag if `meta` was given, and frees the encoder — it must be the last call.
+
+## License
+
+[ॐ](https://github.com/krishnized/license/) · [BSD-3-Clause](./LICENSE), inherited from the bundled [libwavpack](./LICENSE.wavpack).

package/audio.d.ts

@@ -0,0 +1,15 @@
+// Generated from the audio.js manifest (params metadata is the source of truth).
+// Regenerate: node tools/dts.js in @audio/compile. Do not edit by hand.
+
+/** Automatable number — scalar, `t => value` fn, or breakpoint curve {t, v} */
+type Auto = number | ((t: number) => number) | { t: number[], v: number[] }
+/** Per-block param values as delivered by hosts (numbers arrive as 1-length Float32Array) */
+type Live = Record<string, Float32Array | string | boolean>
+type Ctx = { sampleRate: number, maxBlockSize: number, maxChannels: number, currentTime: number, duration?: number, events?: readonly any[], emit?: (name: string, ...args: any[]) => void, [k: string]: unknown }
+type Process = (inputs: Float32Array[][], outputs: Float32Array[][], params: Live) => void
+
+/** Codec plugin 'wv' — extends audio()'s openable formats / save() targets */
+export declare const wv: {
+  codec: 'wv'
+  encode(opts: { sampleRate: number, channels?: number }): ((chunk?: Float32Array[]) => Uint8Array) | Promise<(chunk?: Float32Array[]) => Uint8Array>
+}

package/audio.js

@@ -0,0 +1,19 @@
+// audio.js manifest — codec atom, encode half: opts → callable encoder
+// (enc(chunk) → bytes, enc() → flush+free), adapting the package's
+// { encode, flush, free } streaming shape. Hosts merge with the decode half
+// (@audio/decode-wavpack) by format name.
+
+import init from './wavpack-encode.js'
+
+export const wv = {
+	codec: 'wv',
+	encode: async (opts) => {
+		const c = await init(opts)
+		return (chunk) => {
+			if (chunk) return c.encode(chunk)
+			const out = c.flush()
+			c.free?.()
+			return out
+		}
+	},
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@audio/encode-wavpack",
+  "version": "1.0.0",
+  "description": "Encode PCM audio samples to WavPack (.wv) with libwavpack WASM",
+  "type": "module",
+  "main": "wavpack-encode.js",
+  "types": "wavpack-encode.d.ts",
+  "exports": {
+    ".": "./wavpack-encode.js",
+    "./audio": {
+      "types": "./audio.d.ts",
+      "default": "./audio.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "wavpack-encode.js",
+    "wavpack-encode.d.ts",
+    "src/wavpack.wasm.js",
+    "LICENSE",
+    "LICENSE.wavpack",
+    "audio.js",
+    "audio.d.ts"
+  ],
+  "keywords": [
+    "wavpack",
+    "wv",
+    "hybrid",
+    "lossless",
+    "audio",
+    "encode",
+    "encoder",
+    "wasm",
+    "libwavpack"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "BSD-3-Clause",
+  "author": "audiojs",
+  "homepage": "https://github.com/audiojs/encode/tree/main/packages/encode-wavpack",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/encode.git",
+    "directory": "packages/encode-wavpack"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bugs": "https://github.com/audiojs/encode/issues",
+  "scripts": {
+    "build": "bash build.sh",
+    "prepack": "npm run build",
+    "test": "node test.js"
+  },
+  "devDependencies": {
+    "tst": "^9.4.0",
+    "@audio/decode-wavpack": "^1.0.0"
+  },
+  "audio": "./audio.js",
+  "sideEffects": false,
+  "funding": "https://github.com/sponsors/audiojs"
+}

package/wavpack-encode.d.ts

@@ -0,0 +1,36 @@
+export interface WavpackMeta {
+	title?: string; artist?: string; album?: string; albumartist?: string; composer?: string;
+	genre?: string; year?: string | number; track?: string | number; disc?: string | number;
+	comment?: string; copyright?: string; isrc?: string; publisher?: string; software?: string;
+	lyrics?: string;
+	pictures?: { mime?: string; description?: string; data: Uint8Array }[];
+}
+
+export interface WavpackEncodeOptions {
+	sampleRate: number;
+	channels?: number;
+	/** 16, 24, 32-bit integer, or 'float' (32-bit IEEE-754). Default 16. */
+	bitDepth?: 16 | 24 | 32 | 'float';
+	/** Lossy hybrid mode: bitrate-per-sample (< 24, e.g. 4 = ~4 bits/sample) or kbps (>= 24). No .wvc correction file. */
+	hybrid?: false | number;
+	/** CONFIG_EXTRA_MODE level, 0-6. */
+	extraProcessing?: number;
+	/** CONFIG_HIGH_FLAG */
+	highQuality?: boolean;
+	/** CONFIG_VERY_HIGH_FLAG */
+	veryHigh?: boolean;
+	/** CONFIG_FAST_FLAG */
+	fast?: boolean;
+	/** Fixed WavPack block size in samples (16-131072). Library default if omitted. */
+	blockSamples?: number;
+	/** APEv2 tags. */
+	meta?: WavpackMeta;
+}
+
+export interface StreamEncoder {
+	encode(channels: Float32Array[]): Uint8Array;
+	flush(): Uint8Array;
+	free(): void;
+}
+
+export default function wavpack(opts: WavpackEncodeOptions): Promise<StreamEncoder>;

package/wavpack-encode.js

@@ -0,0 +1,153 @@
+/**
+ * WavPack encoder — libwavpack compiled to WASM (single-file module, host-neutral), encode-only
+ * build (no file-input/decode side, no DSD).
+ *
+ * @param {Object} opts
+ * @param {number} opts.sampleRate - required
+ * @param {number} [opts.channels=1]
+ * @param {16|24|32|'float'} [opts.bitDepth=16]
+ * @param {false|number} [opts.hybrid=false] - bitrate-per-sample (< 24, e.g. 4 = ~4 bits/sample)
+ *   or kbps (>= 24); enables lossy hybrid mode (CONFIG_HYBRID_FLAG). No .wvc correction file.
+ * @param {number} [opts.extraProcessing=0] - 0-6, CONFIG_EXTRA_MODE level (xmode)
+ * @param {boolean} [opts.highQuality] - CONFIG_HIGH_FLAG
+ * @param {boolean} [opts.veryHigh] - CONFIG_VERY_HIGH_FLAG (implies highQuality)
+ * @param {boolean} [opts.fast] - CONFIG_FAST_FLAG
+ * @param {number} [opts.blockSamples] - fixed WavPack block size, 16-131072 samples (library default if omitted)
+ * @param {object} [opts.meta] - APEv2 tags: title, artist, album, albumartist, composer, genre,
+ *   year, track, disc, comment, copyright, isrc, publisher, software, lyrics, pictures[]
+ * @returns {{ encode, flush, free }}
+ *
+ * encode(channels: Float32Array[]) -> Uint8Array (any WavPack blocks completed by this chunk)
+ * flush() -> Uint8Array (final partial block + APEv2 tag, if any; frees the encoder)
+ * free() -> void
+ */
+import createWavpackEncoder from './src/wavpack.wasm.js'
+
+const BIT_DEPTHS = new Set([8, 16, 24, 32])
+const APE_MAP = {
+	title: 'Title', artist: 'Artist', album: 'Album', albumartist: 'Album Artist',
+	composer: 'Composer', genre: 'Genre', year: 'Year', track: 'Track', disc: 'Disc',
+	comment: 'Comment', copyright: 'Copyright', isrc: 'ISRC', publisher: 'Publisher',
+	software: 'Encoder', lyrics: 'Lyrics',
+}
+const MIME_EXT = { 'image/jpeg': 'jpg', 'image/jpg': 'jpg', 'image/png': 'png', 'image/gif': 'gif', 'image/webp': 'webp' }
+
+let modP
+function getMod() {
+	if (modP) return modP
+	let p = createWavpackEncoder()
+	modP = p
+	return p.catch(e => { modP = null; throw e })
+}
+
+export default async function wavpack(opts = {}) {
+	let sampleRate = opts.sampleRate
+	if (!sampleRate) throw Error('sampleRate is required')
+	let channels = opts.channels || 1
+	let isFloat = opts.bitDepth === 'float'
+	let bitDepth = isFloat ? 32 : (opts.bitDepth || 16)
+	if (!isFloat && !BIT_DEPTHS.has(bitDepth)) throw Error('bitDepth must be 16, 24, 32 or \'float\'')
+	let xmode = opts.extraProcessing || 0
+	if (xmode < 0 || xmode > 6) throw Error('extraProcessing must be 0-6')
+	let quality = opts.veryHigh ? 2 : opts.highQuality ? 1 : 0
+	let hybrid = opts.hybrid ? 1 : 0
+	let bitrate = opts.hybrid || 0
+
+	let m = await getMod()
+	let h = m._we_create(sampleRate, channels, bitDepth, isFloat ? 1 : 0, hybrid, bitrate, xmode, quality, opts.fast ? 1 : 0, opts.blockSamples || 0)
+	if (!h || !m._we_ok(h)) throw Error(readError(m, h))
+	if (opts.meta) writeMeta(m, h, opts.meta)
+
+	let div = isFloat ? 0 : 2 ** (bitDepth - 1), max = div - 1
+	let freed = false
+
+	return { encode: encodeChunk, flush, free }
+
+	function encodeChunk(chData) {
+		if (freed) throw Error('Encoder already freed')
+		let n = chData[0] ? chData[0].length : 0
+		if (!n) return EMPTY
+		let dst = m._we_input(h, n)
+		if (!dst) throw Error(readError(m, h))
+		if (isFloat) {
+			let f32 = new Float32Array(m.HEAPU8.buffer, dst, n * channels)
+			for (let i = 0, k = 0; i < n; i++) for (let c = 0; c < channels; c++) f32[k++] = chData[c][i]
+		} else {
+			let i32 = m.HEAP32, k = dst >> 2
+			for (let i = 0; i < n; i++) for (let c = 0; c < channels; c++) {
+				let v = chData[c][i]
+				let s = v < 0 ? v * div : v * max
+				i32[k++] = s < -div ? -div : s > max ? max : Math.round(s)
+			}
+		}
+		if (!m._we_pack(h, n)) throw Error(readError(m, h))
+		return drain()
+	}
+
+	function flush() {
+		if (freed) throw Error('Encoder already freed')
+		if (!m._we_flush(h)) throw Error(readError(m, h))
+		let out = drain()
+		free()
+		return out
+	}
+
+	function free() {
+		if (freed) return
+		freed = true
+		m._we_destroy(h)
+		h = 0
+	}
+
+	function drain() {
+		let len = m._we_output_len(h)
+		if (!len) return EMPTY
+		let ptr = m._we_output_ptr(h)
+		let out = m.HEAPU8.slice(ptr, ptr + len)
+		m._we_output_reset(h)
+		return out
+	}
+}
+
+const EMPTY = new Uint8Array(0)
+const TE = new TextEncoder()
+
+function writeMeta(m, h, meta) {
+	for (let k in APE_MAP) {
+		let v = meta[k]
+		if (v == null || v === '') continue
+		let bytes = TE.encode(String(v))
+		let ok = withCStr(m, APE_MAP[k], item => withBytes(m, bytes, val => m._we_tag_text(h, item, val, bytes.length)))
+		if (!ok) throw Error(readError(m, h))
+	}
+	if (meta.pictures) for (let p of meta.pictures) {
+		let name = TE.encode((p.description || 'cover') + '.' + (MIME_EXT[p.mime] || 'bin') + '\0')
+		let value = new Uint8Array(name.length + p.data.length)
+		value.set(name); value.set(p.data, name.length)
+		let ok = withCStr(m, 'Cover Art (Front)', item => withBytes(m, value, val => m._we_tag_binary(h, item, val, value.length)))
+		if (!ok) throw Error(readError(m, h))
+	}
+}
+
+// Copy `bytes` to a scratch WASM allocation, run `fn(ptr)`, free it, return fn's result.
+function withBytes(m, bytes, fn) {
+	let ptr = m._malloc(bytes.length || 1)
+	m.HEAPU8.set(bytes, ptr)
+	try { return fn(ptr) } finally { m._free(ptr) }
+}
+// Same, but NUL-terminated (for char* item-name arguments).
+function withCStr(m, str, fn) {
+	let bytes = TE.encode(str)
+	let ptr = m._malloc(bytes.length + 1)
+	m.HEAPU8.set(bytes, ptr)
+	m.HEAPU8[ptr + bytes.length] = 0
+	try { return fn(ptr) } finally { m._free(ptr) }
+}
+
+function readError(m, h) {
+	if (!h) return 'WavPack: encoder allocation failed'
+	let ptr = m._we_error(h)
+	let bytes = m.HEAPU8.subarray(ptr, ptr + 128)
+	let nul = bytes.indexOf(0)
+	return new TextDecoder().decode(bytes.subarray(0, nul < 0 ? 128 : nul)) || 'WavPack: encoder error'
+}