@vellumai/assistant 0.6.3 → 0.6.4

package/src/stt/types.ts

@@ -0,0 +1,330 @@
+/**
+ * Provider-agnostic speech-to-text domain types for daemon transcription.
+ *
+ * These types define the boundary between callers that need audio transcription
+ * and the concrete STT provider implementations. The goal is to let daemon
+ * callsites program against a single typed interface so that provider swaps are
+ * localized to the adapter layer.
+ *
+ * Two execution modes are supported:
+ * - **Batch** — a single audio buffer is sent and a final transcript returned.
+ * - **Streaming** — audio chunks are sent over a persistent session, and the
+ *   provider emits partial/final transcript events in real time.
+ */
+
+// ---------------------------------------------------------------------------
+// Provider identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical provider identifiers for daemon-hosted STT backends.
+ * Extend this union as new providers are integrated.
+ */
+export type SttProviderId = "openai-whisper" | "deepgram" | "google-gemini";
+
+/**
+ * Telephony-specific STT capability class.
+ *
+ * Describes the provider's native audio-ingestion capability when used in
+ * a telephony context. This is a **capability classification**, not a direct
+ * Twilio strategy selector — the telephony routing resolver
+ * (`telephony-stt-routing.ts`) maps capability classes plus catalog routing
+ * metadata to concrete Twilio setup strategies (conversation-relay-native
+ * vs media-stream-custom).
+ *
+ * - `"realtime-ws"` — provider offers a WebSocket streaming endpoint suitable
+ *   for low-latency telephony audio (e.g. Deepgram live transcription).
+ * - `"batch-only"` — provider supports only REST batch transcription as its
+ *   native capability. A `batch-only` provider may still participate in
+ *   telephony via Twilio-native ConversationRelay (e.g. Google Gemini) or
+ *   via the media-stream custom path — the routing strategy is determined
+ *   by the catalog's telephony routing metadata, not this field alone.
+ * - `"none"` — provider has no telephony support.
+ */
+export type TelephonySttMode = "realtime-ws" | "batch-only" | "none";
+
+/**
+ * Conversation streaming STT support mode.
+ *
+ * Describes how a provider can participate in real-time conversation
+ * streaming when used for chat message capture (chat composer and iOS
+ * input bar).
+ *
+ * - `"realtime-ws"` — provider offers a native WebSocket streaming endpoint
+ *   that accepts audio chunks and emits partial/final transcript events
+ *   with low latency (e.g. Deepgram live transcription).
+ * - `"incremental-batch"` — provider does not offer true streaming but can
+ *   be polled with incremental audio batches to approximate streaming
+ *   behaviour (e.g. Google Gemini multimodal).
+ * - `"none"` — provider has no conversation streaming support; callers
+ *   should fall back to batch transcription.
+ */
+export type ConversationStreamingMode =
+  | "realtime-ws"
+  | "incremental-batch"
+  | "none";
+
+// ---------------------------------------------------------------------------
+// Boundary identifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime boundary through which STT is executed.
+ * - `daemon-batch` — transcription runs in the daemon process via a REST API
+ *   call to the provider (e.g. OpenAI Whisper).
+ * - `daemon-streaming` — transcription runs in the daemon process over a
+ *   persistent streaming session (e.g. WebSocket or incremental-batch loop).
+ */
+export type SttBoundaryId = "daemon-batch" | "daemon-streaming";
+
+// ---------------------------------------------------------------------------
+// Call-context hints
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional metadata hints that a caller can supply when the transcription
+ * originates from a phone-call context. These are advisory — providers may
+ * ignore hints they do not support.
+ *
+ * This type is intentionally separate from the batch request so that
+ * call-context awareness can be added incrementally without changing the
+ * shape for non-call callers.
+ */
+export interface SttCallContextHints {
+  /** BCP-47 language code for the expected speech (e.g. "en-US"). */
+  language?: string;
+  /** Static vocabulary hints (proper nouns, domain terms) the ASR should prioritize. */
+  vocabularyHints?: string[];
+  /** Short natural-language prompt to bias the transcription model. */
+  prompt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Request / result
+// ---------------------------------------------------------------------------
+
+/** Input to a batch transcription call. */
+export interface SttTranscribeRequest {
+  /** Raw audio data (WAV, OGG, MP3, etc.). */
+  audio: Buffer;
+  /** MIME type of the audio data (e.g. "audio/ogg", "audio/wav"). */
+  mimeType: string;
+  /** Optional abort signal for cancellation / timeout. */
+  signal?: AbortSignal;
+  /**
+   * Optional call-context hints. Present when the transcription request
+   * originates from a telephony call. Providers may use these to improve
+   * recognition accuracy.
+   */
+  callContext?: SttCallContextHints;
+}
+
+/** Successful transcription output. */
+export interface SttTranscribeResult {
+  /** The transcribed text, trimmed. Empty string for silence. */
+  text: string;
+}
+
+// ---------------------------------------------------------------------------
+// Normalized error categories
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalized error categories that callers can branch on without coupling to
+ * provider-specific error shapes or HTTP status codes.
+ */
+export type SttErrorCategory =
+  /** The provider rejected the request due to invalid or missing credentials. */
+  | "auth"
+  /** The provider rate-limited the request. */
+  | "rate-limit"
+  /** The request or response timed out. */
+  | "timeout"
+  /** The audio payload was rejected (unsupported format, too large, etc.). */
+  | "invalid-audio"
+  /** Any other provider-side or network failure. */
+  | "provider-error";
+
+/** A transcription error enriched with a normalized category. */
+export class SttError extends Error {
+  readonly category: SttErrorCategory;
+
+  constructor(category: SttErrorCategory, message: string) {
+    super(message);
+    this.name = "SttError";
+    this.category = category;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Batch transcriber interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Daemon-hosted batch transcriber contract.
+ *
+ * Implementations accept a buffer of audio data and return a transcription
+ * result. Errors propagate as raw provider errors (not wrapped in
+ * {@link SttError}) so that callers relying on specific error identities
+ * (e.g. `AbortError` for cancellation) continue to work. Callers that need
+ * normalized error categories should wrap calls with `normalizeSttError()`
+ * from `daemon-batch-transcriber.ts`.
+ */
+export interface BatchTranscriber {
+  /** Which provider backs this transcriber. */
+  readonly providerId: SttProviderId;
+  /** Which runtime boundary this transcriber operates in. */
+  readonly boundaryId: SttBoundaryId;
+
+  /**
+   * Transcribe a chunk of audio.
+   *
+   * Rejects with the raw provider error on failure. Use
+   * `normalizeSttError()` to convert to an {@link SttError} with a
+   * structured {@link SttErrorCategory}.
+   */
+  transcribe(request: SttTranscribeRequest): Promise<SttTranscribeResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Streaming client events (client -> daemon)
+// ---------------------------------------------------------------------------
+
+/**
+ * Events that a client sends to the daemon streaming session.
+ *
+ * The discriminated `type` field lets the runtime session handler
+ * dispatch to the correct streaming adapter method without coupling
+ * to transport-level framing (WebSocket opcodes, HTTP/2 frames, etc.).
+ */
+export type SttStreamClientEvent =
+  | SttStreamClientAudioEvent
+  | SttStreamClientStopEvent;
+
+/** A chunk of audio data to be transcribed. */
+export interface SttStreamClientAudioEvent {
+  readonly type: "audio";
+  /** Raw audio data for the current chunk. */
+  readonly audio: Buffer;
+  /** MIME type of the audio data (e.g. "audio/webm", "audio/pcm"). */
+  readonly mimeType: string;
+}
+
+/** Signals that the client has finished sending audio. */
+export interface SttStreamClientStopEvent {
+  readonly type: "stop";
+}
+
+// ---------------------------------------------------------------------------
+// Streaming server events (daemon -> client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Events that the daemon streaming session emits to the client.
+ *
+ * The discriminated `type` field allows clients to handle partial
+ * and final transcripts, errors, and session lifecycle signals in a
+ * type-safe manner.
+ */
+export type SttStreamServerEvent =
+  | SttStreamServerPartialEvent
+  | SttStreamServerFinalEvent
+  | SttStreamServerErrorEvent
+  | SttStreamServerClosedEvent;
+
+/**
+ * A partial (interim) transcript — may be revised by subsequent
+ * partial or final events.
+ */
+export interface SttStreamServerPartialEvent {
+  readonly type: "partial";
+  /** Interim transcript text. May change with subsequent events. */
+  readonly text: string;
+  // Provider-emitted speaker label; undefined when diarization is disabled or unsupported. Consumers cross-check with channel-specific signals (e.g., Meet DOM).
+  readonly speakerLabel?: string;
+  /**
+   * Provider-emitted confidence score in [0, 1]. Undefined when the
+   * provider does not surface confidence on interim chunks.
+   */
+  readonly confidence?: number;
+}
+
+/**
+ * A final (committed) transcript — this segment will not be revised.
+ */
+export interface SttStreamServerFinalEvent {
+  readonly type: "final";
+  /** Committed transcript text for a completed speech segment. */
+  readonly text: string;
+  // Provider-emitted speaker label; undefined when diarization is disabled or unsupported. Consumers cross-check with channel-specific signals (e.g., Meet DOM).
+  readonly speakerLabel?: string;
+  /**
+   * Provider-emitted confidence score in [0, 1]. Undefined when the
+   * provider does not surface confidence on this chunk.
+   */
+  readonly confidence?: number;
+}
+
+/** An error occurred during streaming transcription. */
+export interface SttStreamServerErrorEvent {
+  readonly type: "error";
+  /** Normalized error category for caller branching. */
+  readonly category: SttErrorCategory;
+  /** Human-readable error description. */
+  readonly message: string;
+}
+
+/** The streaming session has closed (no more events will be emitted). */
+export interface SttStreamServerClosedEvent {
+  readonly type: "closed";
+}
+
+// ---------------------------------------------------------------------------
+// Streaming transcriber interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Daemon-hosted streaming transcriber contract.
+ *
+ * Implementations manage a persistent session that accepts audio chunks
+ * and emits partial/final transcript events. The runtime session
+ * orchestrator (PR 5) drives this interface from the gateway WebSocket
+ * path.
+ *
+ * Lifecycle:
+ * 1. Call {@link start} to open the provider session.
+ * 2. Feed audio chunks via {@link sendAudio}.
+ * 3. Call {@link stop} when the client finishes recording.
+ * 4. The `onEvent` callback receives server events until `closed`.
+ */
+export interface StreamingTranscriber {
+  /** Which provider backs this transcriber. */
+  readonly providerId: SttProviderId;
+  /** Which runtime boundary this transcriber operates in. */
+  readonly boundaryId: "daemon-streaming";
+
+  /**
+   * Open the streaming session with the provider.
+   *
+   * Must be called once before {@link sendAudio}. Rejects if the
+   * provider session cannot be established.
+   */
+  start(onEvent: (event: SttStreamServerEvent) => void): Promise<void>;
+
+  /**
+   * Feed a chunk of audio into the streaming session.
+   *
+   * Callers must not call this before {@link start} resolves or after
+   * {@link stop} has been called.
+   */
+  sendAudio(audio: Buffer, mimeType: string): void;
+
+  /**
+   * Signal that the client has finished sending audio.
+   *
+   * The provider may emit additional final events after stop is called.
+   * The session is fully closed when the `onEvent` callback receives a
+   * `closed` event.
+   */
+  stop(): void;
+}

package/src/stt/wav-encoder.test.ts

@@ -0,0 +1,373 @@
+import { describe, expect, test } from "bun:test";
+
+import { encodePcm16LeToWav } from "./wav-encoder.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Default mono 16 kHz PCM16LE options used by most tests. */
+const MONO_16K = { sampleRate: 16000, channels: 1 } as const;
+
+/**
+ * Read a 4-byte ASCII string from a buffer at the given offset.
+ */
+function readTag(buf: Buffer, offset: number): string {
+  return buf.toString("ascii", offset, offset + 4);
+}
+
+// ---------------------------------------------------------------------------
+// RIFF / WAVE structure
+// ---------------------------------------------------------------------------
+
+describe("encodePcm16LeToWav", () => {
+  describe("RIFF/WAVE markers", () => {
+    test("starts with RIFF chunk ID", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(readTag(wav, 0)).toBe("RIFF");
+    });
+
+    test("contains WAVE format identifier at offset 8", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(readTag(wav, 8)).toBe("WAVE");
+    });
+
+    test("contains fmt sub-chunk ID at offset 12", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(readTag(wav, 12)).toBe("fmt ");
+    });
+
+    test("contains data sub-chunk ID at offset 36", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(readTag(wav, 36)).toBe("data");
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // RIFF chunk size
+  // -------------------------------------------------------------------------
+
+  describe("RIFF chunk size", () => {
+    test("ChunkSize equals fileSize - 8 for non-empty payload", () => {
+      const pcm = Buffer.alloc(1024);
+      const wav = encodePcm16LeToWav(pcm, MONO_16K);
+      const chunkSize = wav.readUInt32LE(4);
+      // Total file size = 44 (header) + 1024 (data) = 1068
+      // ChunkSize = 1068 - 8 = 1060
+      expect(chunkSize).toBe(1068 - 8);
+    });
+
+    test("ChunkSize equals 36 for empty payload (header-only)", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      const chunkSize = wav.readUInt32LE(4);
+      // Total file size = 44, ChunkSize = 44 - 8 = 36
+      expect(chunkSize).toBe(36);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // fmt sub-chunk fields
+  // -------------------------------------------------------------------------
+
+  describe("fmt sub-chunk", () => {
+    test("fmt sub-chunk size is 16 (PCM)", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(wav.readUInt32LE(16)).toBe(16);
+    });
+
+    test("AudioFormat is 1 (PCM)", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(wav.readUInt16LE(20)).toBe(1);
+    });
+
+    test("NumChannels matches mono input", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 16000,
+        channels: 1,
+      });
+      expect(wav.readUInt16LE(22)).toBe(1);
+    });
+
+    test("NumChannels matches stereo input", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 44100,
+        channels: 2,
+      });
+      expect(wav.readUInt16LE(22)).toBe(2);
+    });
+
+    test("SampleRate is written correctly for 16 kHz", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(wav.readUInt32LE(24)).toBe(16000);
+    });
+
+    test("SampleRate is written correctly for 44.1 kHz", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 44100,
+        channels: 1,
+      });
+      expect(wav.readUInt32LE(24)).toBe(44100);
+    });
+
+    test("SampleRate is written correctly for 48 kHz", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 48000,
+        channels: 2,
+      });
+      expect(wav.readUInt32LE(24)).toBe(48000);
+    });
+
+    test("ByteRate = sampleRate * channels * bitsPerSample / 8 for mono 16-bit", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      // 16000 * 1 * 16 / 8 = 32000
+      expect(wav.readUInt32LE(28)).toBe(32000);
+    });
+
+    test("ByteRate = sampleRate * channels * bitsPerSample / 8 for stereo 16-bit", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 48000,
+        channels: 2,
+      });
+      // 48000 * 2 * 16 / 8 = 192000
+      expect(wav.readUInt32LE(28)).toBe(192000);
+    });
+
+    test("BlockAlign = channels * bitsPerSample / 8 for mono 16-bit", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      // 1 * 16 / 8 = 2
+      expect(wav.readUInt16LE(32)).toBe(2);
+    });
+
+    test("BlockAlign = channels * bitsPerSample / 8 for stereo 16-bit", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 44100,
+        channels: 2,
+      });
+      // 2 * 16 / 8 = 4
+      expect(wav.readUInt16LE(32)).toBe(4);
+    });
+
+    test("BitsPerSample defaults to 16", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(wav.readUInt16LE(34)).toBe(16);
+    });
+
+    test("BitsPerSample respects explicit override", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 16000,
+        channels: 1,
+        bitsPerSample: 24,
+      });
+      expect(wav.readUInt16LE(34)).toBe(24);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // data sub-chunk
+  // -------------------------------------------------------------------------
+
+  describe("data sub-chunk", () => {
+    test("data sub-chunk size matches PCM payload length", () => {
+      const pcm = Buffer.alloc(512);
+      const wav = encodePcm16LeToWav(pcm, MONO_16K);
+      expect(wav.readUInt32LE(40)).toBe(512);
+    });
+
+    test("data sub-chunk size is 0 for empty payload", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(wav.readUInt32LE(40)).toBe(0);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Payload passthrough
+  // -------------------------------------------------------------------------
+
+  describe("payload passthrough", () => {
+    test("PCM data is copied verbatim after the 44-byte header", () => {
+      const pcm = Buffer.from([0x01, 0x02, 0x03, 0x04, 0xff, 0xfe]);
+      const wav = encodePcm16LeToWav(pcm, MONO_16K);
+
+      const payload = wav.subarray(44);
+      expect(payload).toEqual(pcm);
+    });
+
+    test("large payload is preserved byte-for-byte", () => {
+      // 1 second of mono 16 kHz 16-bit audio = 32000 bytes
+      const pcm = Buffer.alloc(32000);
+      for (let i = 0; i < pcm.length; i++) {
+        pcm[i] = i % 256;
+      }
+
+      const wav = encodePcm16LeToWav(pcm, MONO_16K);
+      const payload = wav.subarray(44);
+      expect(payload).toEqual(pcm);
+    });
+
+    test("total file length is header + payload", () => {
+      const pcm = Buffer.alloc(256);
+      const wav = encodePcm16LeToWav(pcm, MONO_16K);
+      expect(wav.length).toBe(44 + 256);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Empty audio (silence / final flush edge case)
+  // -------------------------------------------------------------------------
+
+  describe("empty audio", () => {
+    test("produces a deterministic 44-byte header-only output", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(wav.length).toBe(44);
+    });
+
+    test("header-only output has valid RIFF structure", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(readTag(wav, 0)).toBe("RIFF");
+      expect(readTag(wav, 8)).toBe("WAVE");
+      expect(readTag(wav, 12)).toBe("fmt ");
+      expect(readTag(wav, 36)).toBe("data");
+      expect(wav.readUInt32LE(40)).toBe(0);
+    });
+
+    test("two calls with empty audio produce identical output", () => {
+      const a = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      const b = encodePcm16LeToWav(Buffer.alloc(0), MONO_16K);
+      expect(a).toEqual(b);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Custom bit depths
+  // -------------------------------------------------------------------------
+
+  describe("custom bit depths", () => {
+    test("accepts 8-bit depth and computes correct byte rate", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 8000,
+        channels: 1,
+        bitsPerSample: 8,
+      });
+      // ByteRate = 8000 * 1 * 8 / 8 = 8000
+      expect(wav.readUInt32LE(28)).toBe(8000);
+      // BlockAlign = 1 * 8 / 8 = 1
+      expect(wav.readUInt16LE(32)).toBe(1);
+      expect(wav.readUInt16LE(34)).toBe(8);
+    });
+
+    test("accepts 24-bit depth and computes correct byte rate", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 48000,
+        channels: 2,
+        bitsPerSample: 24,
+      });
+      // ByteRate = 48000 * 2 * 24 / 8 = 288000
+      expect(wav.readUInt32LE(28)).toBe(288000);
+      // BlockAlign = 2 * 24 / 8 = 6
+      expect(wav.readUInt16LE(32)).toBe(6);
+      expect(wav.readUInt16LE(34)).toBe(24);
+    });
+
+    test("accepts 32-bit depth and computes correct byte rate", () => {
+      const wav = encodePcm16LeToWav(Buffer.alloc(0), {
+        sampleRate: 44100,
+        channels: 1,
+        bitsPerSample: 32,
+      });
+      // ByteRate = 44100 * 1 * 32 / 8 = 176400
+      expect(wav.readUInt32LE(28)).toBe(176400);
+      // BlockAlign = 1 * 32 / 8 = 4
+      expect(wav.readUInt16LE(32)).toBe(4);
+      expect(wav.readUInt16LE(34)).toBe(32);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Input validation
+  // -------------------------------------------------------------------------
+
+  describe("input validation", () => {
+    test("throws for zero sample rate", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: 0,
+          channels: 1,
+        }),
+      ).toThrow("Invalid sampleRate");
+    });
+
+    test("throws for negative sample rate", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: -16000,
+          channels: 1,
+        }),
+      ).toThrow("Invalid sampleRate");
+    });
+
+    test("throws for NaN sample rate", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: NaN,
+          channels: 1,
+        }),
+      ).toThrow("Invalid sampleRate");
+    });
+
+    test("throws for Infinity sample rate", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: Infinity,
+          channels: 1,
+        }),
+      ).toThrow("Invalid sampleRate");
+    });
+
+    test("throws for zero channels", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: 16000,
+          channels: 0,
+        }),
+      ).toThrow("Invalid channels");
+    });
+
+    test("throws for negative channels", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: 16000,
+          channels: -1,
+        }),
+      ).toThrow("Invalid channels");
+    });
+
+    test("throws for fractional channels", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: 16000,
+          channels: 1.5,
+        }),
+      ).toThrow("Invalid channels");
+    });
+
+    test("throws for unsupported bit depth", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: 16000,
+          channels: 1,
+          bitsPerSample: 12,
+        }),
+      ).toThrow("Unsupported bitsPerSample");
+    });
+
+    test("throws for zero bit depth", () => {
+      expect(() =>
+        encodePcm16LeToWav(Buffer.alloc(0), {
+          sampleRate: 16000,
+          channels: 1,
+          bitsPerSample: 0,
+        }),
+      ).toThrow("Unsupported bitsPerSample");
+    });
+  });
+});