voicecc 1.1.36 → 1.2.0

package/server/voice/stt-elevenlabs.ts

@@ -1,210 +0,0 @@
-/**
- * ElevenLabs STT provider via batch transcription API (Scribe v2).
- *
- * Accumulates audio samples locally during speech, then sends the full buffer
- * to the ElevenLabs speech-to-text API on transcribe(). Audio is encoded as a
- * WAV file (16kHz mono 16-bit PCM) before upload.
- *
- * Responsibilities:
- * - Accumulate Float32Array audio chunks during speech
- * - Encode accumulated audio as a WAV file for upload
- * - POST the WAV to the ElevenLabs batch STT API via multipart/form-data
- * - Parse the JSON response and return a TranscriptionResult
- * - Clear the buffer after transcription or on demand
- */
-
-import type { SttProcessor, TranscriptionResult } from "./types.js";
-
-// ============================================================================
-// CONSTANTS
-// ============================================================================
-
-/** ElevenLabs STT API endpoint */
-const ELEVENLABS_STT_URL = "https://api.elevenlabs.io/v1/speech-to-text";
-
-/** Sample rate for the WAV file (must match input audio from microphone) */
-const WAV_SAMPLE_RATE = 16000;
-
-/** Number of audio channels */
-const WAV_CHANNELS = 1;
-
-/** Bits per sample in the WAV file */
-const WAV_BIT_DEPTH = 16;
-
-/** Size of the WAV file header in bytes */
-const WAV_HEADER_SIZE = 44;
-
-// ============================================================================
-// INTERFACES
-// ============================================================================
-
-/**
- * Configuration for the ElevenLabs STT provider.
- */
-export interface ElevenlabsSttConfig {
-  /** ElevenLabs API key for authentication */
-  apiKey: string;
-  /** ElevenLabs STT model ID (e.g. "scribe_v1") */
-  modelId: string;
-}
-
-// ============================================================================
-// MAIN HANDLERS
-// ============================================================================
-
-/**
- * Create an SttProcessor that uses the ElevenLabs batch transcription API.
- *
- * Audio is accumulated locally via accumulate(), then the full buffer is
- * encoded as WAV and sent to ElevenLabs on transcribe(). This fits the
- * existing SttProcessor interface without changes.
- *
- * @param config - ElevenLabs STT configuration (API key and model ID)
- * @returns An SttProcessor instance ready for transcription
- */
-export async function createElevenlabsStt(config: ElevenlabsSttConfig): Promise<SttProcessor> {
-  const { apiKey, modelId } = config;
-
-  let audioChunks: Float32Array[] = [];
-
-  /**
-   * Append audio samples to the internal buffer.
-   * @param samples - Float32Array of audio samples (16kHz, normalized -1.0 to 1.0)
-   */
-  function accumulate(samples: Float32Array): void {
-    audioChunks.push(samples);
-  }
-
-  /**
-   * Transcribe the accumulated audio buffer by sending it to the ElevenLabs API.
-   * Encodes the audio as WAV, uploads via multipart/form-data, and parses the result.
-   *
-   * @returns Transcription result with text, isFinal flag, and timestamp
-   * @throws Error on empty buffer, non-2xx response, or network failure
-   */
-  async function transcribe(): Promise<TranscriptionResult> {
-    const combinedSamples = concatenateChunks(audioChunks);
-    audioChunks = [];
-
-    if (combinedSamples.length === 0) {
-      return { text: "", isFinal: true, timestamp: Date.now() };
-    }
-
-    // Encode audio as WAV and upload to ElevenLabs
-    const wavBuffer = encodeWav(combinedSamples);
-    const wavBlob = new Blob([new Uint8Array(wavBuffer)], { type: "audio/wav" });
-
-    const formData = new FormData();
-    formData.append("file", wavBlob, "audio.wav");
-    formData.append("model_id", modelId);
-
-    const response = await fetch(ELEVENLABS_STT_URL, {
-      method: "POST",
-      headers: {
-        "xi-api-key": apiKey,
-      },
-      body: formData,
-    });
-
-    if (!response.ok) {
-      const errorText = await response.text().catch(() => "unknown error");
-      throw new Error(`ElevenLabs STT API error ${response.status}: ${errorText}`);
-    }
-
-    const result = await response.json() as { text: string };
-
-    return { text: result.text.trim(), isFinal: true, timestamp: Date.now() };
-  }
-
-  /**
-   * Clear the accumulated audio buffer without transcribing.
-   */
-  function clearBuffer(): void {
-    audioChunks = [];
-  }
-
-  /**
-   * Free resources. Clears the buffer (no external resources to release).
-   */
-  function destroy(): void {
-    audioChunks = [];
-  }
-
-  return {
-    accumulate,
-    transcribe,
-    clearBuffer,
-    destroy,
-  };
-}
-
-// ============================================================================
-// HELPER FUNCTIONS
-// ============================================================================
-
-/**
- * Encode Float32Array audio samples as a WAV file buffer.
- * Writes a 44-byte WAV header followed by 16-bit signed PCM data.
- *
- * @param samples - Float32Array of audio samples (normalized -1.0 to 1.0)
- * @returns Buffer containing a valid WAV file
- */
-function encodeWav(samples: Float32Array): Buffer {
-  const bytesPerSample = WAV_BIT_DEPTH / 8;
-  const dataSize = samples.length * bytesPerSample;
-  const fileSize = WAV_HEADER_SIZE + dataSize;
-
-  const buffer = Buffer.alloc(fileSize);
-  let offset = 0;
-
-  // RIFF header
-  buffer.write("RIFF", offset); offset += 4;
-  buffer.writeUInt32LE(fileSize - 8, offset); offset += 4;
-  buffer.write("WAVE", offset); offset += 4;
-
-  // fmt sub-chunk
-  buffer.write("fmt ", offset); offset += 4;
-  buffer.writeUInt32LE(16, offset); offset += 4;             // Sub-chunk size (16 for PCM)
-  buffer.writeUInt16LE(1, offset); offset += 2;              // Audio format (1 = PCM)
-  buffer.writeUInt16LE(WAV_CHANNELS, offset); offset += 2;   // Number of channels
-  buffer.writeUInt32LE(WAV_SAMPLE_RATE, offset); offset += 4; // Sample rate
-  buffer.writeUInt32LE(WAV_SAMPLE_RATE * WAV_CHANNELS * bytesPerSample, offset); offset += 4; // Byte rate
-  buffer.writeUInt16LE(WAV_CHANNELS * bytesPerSample, offset); offset += 2; // Block align
-  buffer.writeUInt16LE(WAV_BIT_DEPTH, offset); offset += 2;  // Bits per sample
-
-  // data sub-chunk
-  buffer.write("data", offset); offset += 4;
-  buffer.writeUInt32LE(dataSize, offset); offset += 4;
-
-  // Convert float samples to 16-bit signed PCM
-  for (let i = 0; i < samples.length; i++) {
-    const clamped = Math.max(-1, Math.min(1, samples[i]));
-    const int16 = clamped < 0 ? clamped * 0x8000 : clamped * 0x7FFF;
-    buffer.writeInt16LE(Math.round(int16), offset);
-    offset += 2;
-  }
-
-  return buffer;
-}
-
-/**
- * Concatenate an array of Float32Array chunks into a single Float32Array.
- *
- * @param chunks - Array of Float32Array audio chunks
- * @returns Single concatenated Float32Array
- */
-function concatenateChunks(chunks: Float32Array[]): Float32Array {
-  if (chunks.length === 0) return new Float32Array(0);
-  if (chunks.length === 1) return chunks[0];
-
-  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  const result = new Float32Array(totalLength);
-
-  let offset = 0;
-  for (const chunk of chunks) {
-    result.set(chunk, offset);
-    offset += chunk.length;
-  }
-
-  return result;
-}

package/server/voice/stt-provider.ts

@@ -1,106 +0,0 @@
-/**
- * STT provider factory and readiness checks.
- *
- * Routes STT creation to the ElevenLabs provider implementation.
- * Checks provider readiness (API keys) for dashboard status.
- *
- * Responsibilities:
- * - Create an SttProcessor for the configured provider
- * - Check provider readiness (API keys set)
- * - Provide static metadata about available STT providers
- */
-
-import { createElevenlabsStt } from "./stt-elevenlabs.js";
-import { readEnv } from "../services/env.js";
-
-import type { SttProcessor, SttProviderType, SttProviderConfig, ProviderStatus } from "./types.js";
-
-// ============================================================================
-// INTERFACES
-// ============================================================================
-
-/**
- * Metadata about an STT provider for display in the dashboard.
- */
-export interface SttProviderInfo {
-  /** Provider type identifier */
-  type: SttProviderType;
-  /** Human-readable provider name */
-  name: string;
-  /** Short description of the provider */
-  description: string;
-  /** Environment variable name for the API key (undefined = no key needed) */
-  requiresApiKey?: string;
-}
-
-/**
- * Options for creating an STT processor via the provider factory.
- */
-export interface CreateSttOptions {
-  /** Provider configuration (which provider + per-provider settings) */
-  providerConfig: SttProviderConfig;
-}
-
-// ============================================================================
-// MAIN HANDLERS
-// ============================================================================
-
-/**
- * Create an SttProcessor for the configured provider.
- *
- * @param options - Provider config with per-provider settings
- * @returns An SttProcessor instance ready for transcription
- * @throws Error if the provider is not implemented
- */
-export async function createSttForProvider(options: CreateSttOptions): Promise<SttProcessor> {
-  const { providerConfig } = options;
-
-  switch (providerConfig.provider) {
-    case "elevenlabs":
-      return createElevenlabsStt({
-        apiKey: providerConfig.elevenlabs.apiKey,
-        modelId: providerConfig.elevenlabs.modelId,
-      });
-
-    default:
-      throw new Error(`Unknown STT provider: ${providerConfig.provider}`);
-  }
-}
-
-/**
- * Check whether an STT provider is ready to use.
- * Checks ELEVENLABS_API_KEY is set in .env.
- *
- * @param providerType - The provider to check
- * @returns Readiness status with reason if not ready
- */
-export async function getSttProviderStatus(providerType: SttProviderType): Promise<ProviderStatus> {
-  switch (providerType) {
-    case "elevenlabs": {
-      const env = await readEnv();
-      if (!env.ELEVENLABS_API_KEY) {
-        return { ready: false, reason: "missing_api_key", detail: "ELEVENLABS_API_KEY is not set in .env" };
-      }
-      return { ready: true };
-    }
-
-    default:
-      throw new Error(`Unknown STT provider: ${providerType}`);
-  }
-}
-
-/**
- * Get the list of all known STT providers with metadata.
- *
- * @returns Static array of STT provider info
- */
-export function getAvailableSttProviders(): SttProviderInfo[] {
-  return [
-    {
-      type: "elevenlabs",
-      name: "ElevenLabs Scribe",
-      description: "Cloud STT via ElevenLabs batch transcription API",
-      requiresApiKey: "ELEVENLABS_API_KEY",
-    },
-  ];
-}

package/server/voice/tts-elevenlabs-hiss.test.ts

@@ -1,183 +0,0 @@
-/**
- * Tests that ElevenLabs TTS writes sample-aligned PCM to the speaker stream.
- *
- * ElevenLabs streams raw PCM (16-bit, 24kHz mono) over HTTP. The fetch
- * response body yields chunks at arbitrary byte boundaries (TCP packets).
- * Each chunk is written to the speaker stream, which for the browser path
- * becomes a separate WebSocket message. The browser interprets each message
- * as Int16Array -- if a chunk has an odd byte count, a sample is split and
- * all subsequent audio is corrupted (hiss/static).
- *
- * Run: npx tsx --test server/voice/tts-elevenlabs-hiss.test.ts
- */
-
-import { test } from "node:test";
-import { strict as assert } from "node:assert";
-import { PassThrough } from "stream";
-
-import { createElevenlabsTts } from "./tts-elevenlabs.js";
-
-// ============================================================================
-// CONSTANTS
-// ============================================================================
-
-/** Sample rate of ElevenLabs PCM output */
-const SAMPLE_RATE = 24000;
-
-/** Bytes per sample (16-bit) */
-const BYTES_PER_SAMPLE = 2;
-
-// ============================================================================
-// HELPERS
-// ============================================================================
-
-/**
- * Generate a buffer of raw 16-bit signed LE PCM (440Hz sine wave).
- *
- * @param sampleCount - Number of samples to generate
- * @returns Buffer of int16 LE PCM
- */
-function generateSineWavePcm(sampleCount: number): Buffer {
-  const buf = Buffer.alloc(sampleCount * BYTES_PER_SAMPLE);
-
-  for (let i = 0; i < sampleCount; i++) {
-    const t = i / SAMPLE_RATE;
-    const int16 = Math.round(Math.sin(2 * Math.PI * 440 * t) * 32767);
-    buf.writeInt16LE(int16, i * BYTES_PER_SAMPLE);
-  }
-
-  return buf;
-}
-
-/**
- * Create a mock fetch Response whose body streams the given PCM buffer
- * split into chunks at the specified byte offsets (simulating arbitrary
- * HTTP chunked transfer boundaries).
- *
- * @param pcm - Full PCM buffer to stream
- * @param splitOffsets - Byte offsets at which to split (e.g. [1001, 2000])
- * @returns A Response object with a streaming body
- */
-function createMockResponse(pcm: Buffer, splitOffsets: number[]): Response {
-  const chunks: Uint8Array[] = [];
-  let offset = 0;
-
-  for (const splitAt of splitOffsets) {
-    if (offset >= pcm.byteLength) break;
-    chunks.push(new Uint8Array(pcm.subarray(offset, Math.min(splitAt, pcm.byteLength))));
-    offset = splitAt;
-  }
-
-  if (offset < pcm.byteLength) {
-    chunks.push(new Uint8Array(pcm.subarray(offset)));
-  }
-
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      for (const chunk of chunks) {
-        controller.enqueue(chunk);
-      }
-      controller.close();
-    },
-  });
-
-  return new Response(stream, { status: 200 });
-}
-
-/**
- * Stub global fetch to return a mock response, run the callback, then restore.
- *
- * @param mockResponse - The Response to return from fetch
- * @param fn - Async function to run while fetch is stubbed
- */
-async function withMockFetch(mockResponse: Response, fn: () => Promise<void>): Promise<void> {
-  const originalFetch = globalThis.fetch;
-  globalThis.fetch = async () => mockResponse;
-
-  try {
-    await fn();
-  } finally {
-    globalThis.fetch = originalFetch;
-  }
-}
-
-// ============================================================================
-// TESTS
-// ============================================================================
-
-/**
- * Every write to the speaker stream must have an even byte count so the
- * browser can interpret it as Int16Array without truncating or misaligning.
- */
-test("ElevenLabs chunks written to speaker must be sample-aligned (even byte count)", async () => {
-  const pcm = generateSineWavePcm(2400); // 0.1s of audio = 4800 bytes
-  const speakerOutput = new PassThrough();
-
-  // Split at odd byte offsets to simulate arbitrary HTTP chunk boundaries
-  const mockResponse = createMockResponse(pcm, [1001, 2000, 3333, 4001]);
-
-  const player = await createElevenlabsTts({
-    apiKey: "test-key",
-    voiceId: "test-voice",
-    modelId: "test-model",
-    speakerInput: speakerOutput,
-    interruptPlayback: () => {},
-    resumePlayback: () => {},
-  });
-
-  // Collect all chunks written to the speaker stream
-  const writtenChunks: Buffer[] = [];
-  speakerOutput.on("data", (chunk: Buffer) => {
-    writtenChunks.push(Buffer.from(chunk));
-  });
-
-  await withMockFetch(mockResponse, () => player.speak("Hello world"));
-
-  // Every chunk written to the speaker must be sample-aligned
-  const oddChunks = writtenChunks.filter((c) => c.byteLength % BYTES_PER_SAMPLE !== 0);
-
-  assert.equal(
-    oddChunks.length,
-    0,
-    `${oddChunks.length} of ${writtenChunks.length} chunks written to speaker had odd byte length ` +
-    `(${oddChunks.map((c) => c.byteLength).join(", ")} bytes). ` +
-    `Odd-length chunks split 16-bit PCM samples, causing hiss in browser playback.`
-  );
-});
-
-/**
- * Sample alignment must not lose audio data. The total bytes written to the
- * speaker must equal the original PCM size.
- */
-test("total bytes written to speaker must equal source PCM size", async () => {
-  const pcm = generateSineWavePcm(2400); // 0.1s = 4800 bytes
-  const speakerOutput = new PassThrough();
-
-  // Odd splits that would cause byte loss if alignment just truncates
-  const mockResponse = createMockResponse(pcm, [1001, 2000, 3333, 4001]);
-
-  const player = await createElevenlabsTts({
-    apiKey: "test-key",
-    voiceId: "test-voice",
-    modelId: "test-model",
-    speakerInput: speakerOutput,
-    interruptPlayback: () => {},
-    resumePlayback: () => {},
-  });
-
-  const writtenChunks: Buffer[] = [];
-  speakerOutput.on("data", (chunk: Buffer) => {
-    writtenChunks.push(Buffer.from(chunk));
-  });
-
-  await withMockFetch(mockResponse, () => player.speak("Hello world"));
-
-  const totalWritten = writtenChunks.reduce((sum, c) => sum + c.byteLength, 0);
-
-  assert.equal(
-    totalWritten,
-    pcm.byteLength,
-    `Expected ${pcm.byteLength} bytes written to speaker, got ${totalWritten}. ` +
-    `Sample alignment must carry over leftover bytes, not drop them.`
-  );
-});