@kuralle-syrinx/recorder 2.1.1 → 3.0.0

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@kuralle-syrinx/recorder",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./wav": "./src/wav.ts"
+  },
   "dependencies": {
-    "@kuralle-syrinx/core": "2.1.1"
+    "@kuralle-syrinx/core": "3.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/index.ts

@@ -14,6 +14,11 @@ import {
   type VoicePacket,
   type VoicePlugin,
 } from "@kuralle-syrinx/core";
+import { interleaveStereoPcm16, pcm16ToWav } from "./wav.js";
+
+// Re-export the runtime-agnostic builders so Workers hosts can `@kuralle-syrinx/recorder/wav`
+// (no node:fs) without reaching through this Node-only entry point.
+export { interleaveStereoPcm16, pcm16ToWav } from "./wav.js";
 
 export interface VoiceSessionRecorderConfig {
   readonly outputDir: string;
@@ -352,9 +357,9 @@ export class VoiceSessionRecorder implements VoicePlugin {
     const resampled = assistantRate !== userRate
       ? resampleLinear(assistantPcm, assistantRate, userRate)
       : assistantPcm;
-    const stereo = interleaveInt16(userPcm, resampled);
+    const stereo = interleaveStereoPcm16(userPcm, resampled);
     this.conversationAudioBytes = stereo.byteLength;
-    await writeFile(this.conversationAudioPath, buildWav(stereo, 2, userRate));
+    await writeFile(this.conversationAudioPath, pcm16ToWav(stereo, userRate, 2));
   }
 
   private async writeManifest(): Promise<void> {
@@ -791,38 +796,3 @@ function resampleLinear(src: Buffer, srcRate: number, dstRate: number): Buffer {
   return dst;
 }
 
-function interleaveInt16(left: Buffer, right: Buffer): Buffer {
-  const leftSamples = left.byteLength >> 1;
-  const rightSamples = right.byteLength >> 1;
-  const maxSamples = Math.max(leftSamples, rightSamples);
-  if (maxSamples === 0) return Buffer.alloc(0);
-  const out = Buffer.alloc(maxSamples * 4);
-  for (let i = 0; i < maxSamples; i++) {
-    const l = i < leftSamples ? left.readInt16LE(i * 2) : 0;
-    const r = i < rightSamples ? right.readInt16LE(i * 2) : 0;
-    out.writeInt16LE(l, i * 4);
-    out.writeInt16LE(r, i * 4 + 2);
-  }
-  return out;
-}
-
-function buildWav(pcm: Buffer, channels: number, sampleRateHz: number): Buffer {
-  const bitsPerSample = 16;
-  const blockAlign = channels * (bitsPerSample >> 3);
-  const byteRate = sampleRateHz * blockAlign;
-  const header = Buffer.allocUnsafe(44);
-  header.write("RIFF", 0, "ascii");
-  header.writeUInt32LE(36 + pcm.byteLength, 4);
-  header.write("WAVE", 8, "ascii");
-  header.write("fmt ", 12, "ascii");
-  header.writeUInt32LE(16, 16);
-  header.writeUInt16LE(1, 20);
-  header.writeUInt16LE(channels, 22);
-  header.writeUInt32LE(sampleRateHz, 24);
-  header.writeUInt32LE(byteRate, 28);
-  header.writeUInt16LE(blockAlign, 32);
-  header.writeUInt16LE(bitsPerSample, 34);
-  header.write("data", 36, "ascii");
-  header.writeUInt32LE(pcm.byteLength, 40);
-  return Buffer.concat([header, pcm]);
-}

package/src/wav.test.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { interleaveStereoPcm16, pcm16ToWav } from "./wav.js";
+
+describe("pcm16ToWav", () => {
+  it("writes a canonical 44-byte RIFF/PCM header for the given rate and channels", () => {
+    const pcm = new Uint8Array([1, 2, 3, 4]); // 2 mono samples
+    const wav = pcm16ToWav(pcm, 16000, 1);
+    expect(wav.byteLength).toBe(44 + 4);
+    const view = new DataView(wav.buffer);
+    expect(String.fromCharCode(wav[0]!, wav[1]!, wav[2]!, wav[3]!)).toBe("RIFF");
+    expect(view.getUint32(4, true)).toBe(36 + 4); // chunk size
+    expect(String.fromCharCode(wav[8]!, wav[9]!, wav[10]!, wav[11]!)).toBe("WAVE");
+    expect(view.getUint16(20, true)).toBe(1); // PCM
+    expect(view.getUint16(22, true)).toBe(1); // channels
+    expect(view.getUint32(24, true)).toBe(16000); // sample rate
+    expect(view.getUint16(32, true)).toBe(2); // blockAlign = channels * 2
+    expect(view.getUint32(40, true)).toBe(4); // data size
+    expect([...wav.subarray(44)]).toEqual([1, 2, 3, 4]);
+  });
+
+  it("sets stereo blockAlign and byteRate", () => {
+    const view = new DataView(pcm16ToWav(new Uint8Array(8), 24000, 2).buffer);
+    expect(view.getUint16(32, true)).toBe(4); // 2ch * 2 bytes
+    expect(view.getUint32(28, true)).toBe(24000 * 4); // byteRate
+  });
+});
+
+describe("interleaveStereoPcm16", () => {
+  it("interleaves L/R frames and pads the shorter stream with silence", () => {
+    const left = new Uint8Array([0x10, 0x00, 0x20, 0x00]); // samples 16, 32
+    const right = new Uint8Array([0x01, 0x00]); // sample 1, then padded
+    const out = interleaveStereoPcm16(left, right);
+    const view = new DataView(out.buffer);
+    expect(out.byteLength).toBe(2 * 4); // 2 frames × (2ch × 2 bytes)
+    expect(view.getInt16(0, true)).toBe(16); // L0
+    expect(view.getInt16(2, true)).toBe(1); // R0
+    expect(view.getInt16(4, true)).toBe(32); // L1
+    expect(view.getInt16(6, true)).toBe(0); // R1 padded
+  });
+});

package/src/wav.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+//
+// Pure, runtime-agnostic PCM16 → WAV and stereo-mix builders. No `node:fs`, no `Buffer` —
+// just `Uint8Array` — so the same builders run on Node AND Cloudflare Workers (where a
+// host writes the bytes to R2 instead of disk). The Node `VoiceSessionRecorder` and a
+// Workers R2 recorder share these so the WAV/stereo logic can't drift between runtimes.
+
+/** Wrap mono/stereo PCM16LE bytes in a 44-byte canonical WAV (RIFF/PCM) container. */
+export function pcm16ToWav(pcm: Uint8Array, sampleRateHz: number, channels: number): Uint8Array {
+  const blockAlign = channels * 2; // 16-bit samples
+  const byteRate = sampleRateHz * blockAlign;
+  const out = new Uint8Array(44 + pcm.byteLength);
+  const view = new DataView(out.buffer);
+  writeAscii(view, 0, "RIFF");
+  view.setUint32(4, 36 + pcm.byteLength, true);
+  writeAscii(view, 8, "WAVE");
+  writeAscii(view, 12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true); // PCM
+  view.setUint16(22, channels, true);
+  view.setUint32(24, sampleRateHz, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, blockAlign, true);
+  view.setUint16(34, 16, true);
+  writeAscii(view, 36, "data");
+  view.setUint32(40, pcm.byteLength, true);
+  out.set(pcm, 44);
+  return out;
+}
+
+/**
+ * Interleave two mono PCM16LE streams into stereo (left, right). The shorter stream is
+ * padded with silence to the longer one's frame count.
+ */
+export function interleaveStereoPcm16(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const leftSamples = left.byteLength >> 1;
+  const rightSamples = right.byteLength >> 1;
+  const frames = Math.max(leftSamples, rightSamples);
+  const out = new Uint8Array(frames * 4);
+  const lv = new DataView(left.buffer, left.byteOffset, left.byteLength);
+  const rv = new DataView(right.buffer, right.byteOffset, right.byteLength);
+  const ov = new DataView(out.buffer);
+  for (let i = 0; i < frames; i += 1) {
+    ov.setInt16(i * 4, i < leftSamples ? lv.getInt16(i * 2, true) : 0, true);
+    ov.setInt16(i * 4 + 2, i < rightSamples ? rv.getInt16(i * 2, true) : 0, true);
+  }
+  return out;
+}
+
+function writeAscii(view: DataView, offset: number, text: string): void {
+  for (let i = 0; i < text.length; i += 1) view.setUint8(offset + i, text.charCodeAt(i));
+}