@derogab/stt-proxy 0.1.0

package/.github/workflows/release.yml

@@ -0,0 +1,131 @@
+name: Release and publish package to NPM
+
+on:
+  push:
+    # Publish `v1.2.3` tags as releases.
+    tags:
+      - v*
+
+jobs:
+  # Release the TAG to GitHub.
+  release:
+    name: Release pushed tag
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+        run: |
+          gh release create "$tag" \
+              --repo="$GITHUB_REPOSITORY" \
+              --title="v${tag#v}" \
+              --generate-notes
+  # Publish the package.
+  publish-npm:
+    name: Publish Package on NPM
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install FFmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - name: Cache Whisper model
+        uses: actions/cache@v4
+        with:
+          path: test/models
+          key: whisper-model-tiny-v1
+      - name: Cache test audio
+        uses: actions/cache@v4
+        with:
+          path: test/audio
+          key: test-audio-jfk-v1
+      - name: Install dependencies (clean)
+        run: npm ci
+      - name: Type check
+        run: npm run typecheck
+      - name: Run tests
+        run: npm test --if-present
+      - name: Build
+        run: npm run build
+      - name: Verify tag matches package.json version
+        run: |
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+          TAG_VERSION="${GITHUB_REF_NAME#v}"   # supports tags like v1.2.3
+          echo "package.json: $PKG_VERSION"
+          echo "release tag:   $TAG_VERSION"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Release tag ($TAG_VERSION) does not match package.json version ($PKG_VERSION)."
+            exit 1
+          fi
+      - name: Show publish contents (dry run)
+        run: npm pack --dry-run
+      - name: Publish to npm (with provenance)
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public
+  publish-github:
+    name: Publish Package on GitHub
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+          registry-url: 'https://npm.pkg.github.com'
+      - name: Install FFmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - name: Cache Whisper model
+        uses: actions/cache@v4
+        with:
+          path: test/models
+          key: whisper-model-tiny-v1
+      - name: Cache test audio
+        uses: actions/cache@v4
+        with:
+          path: test/audio
+          key: test-audio-jfk-v1
+      - name: Install dependencies (clean)
+        run: npm ci
+      - name: Type check
+        run: npm run typecheck
+      - name: Run tests
+        run: npm test --if-present
+      - name: Build
+        run: npm run build
+      - name: Verify tag matches package.json version
+        run: |
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+          TAG_VERSION="${GITHUB_REF_NAME#v}"   # supports tags like v1.2.3
+          echo "package.json: $PKG_VERSION"
+          echo "release tag:   $TAG_VERSION"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Release tag ($TAG_VERSION) does not match package.json version ($PKG_VERSION)."
+            exit 1
+          fi
+      - name: Show publish contents (dry run)
+        run: npm pack --dry-run
+      - name: Publish to GitHub Packages (with provenance)
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_GITHUB_TOKEN }}
+        run: npm publish --provenance --access public

package/.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  tests:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+      - name: Install FFmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - name: Cache Whisper model
+        uses: actions/cache@v4
+        with:
+          path: test/models
+          key: whisper-model-tiny-v1
+      - name: Cache test audio
+        uses: actions/cache@v4
+        with:
+          path: test/audio
+          key: test-audio-jfk-v1
+      - name: Install dependencies
+        run: npm ci
+      - name: Type check
+        run: npm run typecheck
+      - name: Build project
+        run: npm run build
+      - name: Run all tests
+        run: npm test

package/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Build all outputs (CJS, ESM, and types)
+npm run build:cjs    # Build CommonJS output only
+npm run build:esm    # Build ESM output only
+npm run build:types  # Build type declarations only
+```
+
+## Test Commands
+
+```bash
+npm test              # Run all tests (unit + integration)
+npm run test:unit     # Run unit tests only
+npm run test:whisper  # Run Whisper.cpp integration tests only
+npm run test:watch    # Run tests in watch mode
+npm run test:coverage # Run tests with coverage report
+```
+
+**Important**: Always run `npm test` after making changes to verify nothing is broken. Tests are located in the `test/` folder.
+
+Tests are written using Vitest and cover:
+- Provider selection logic (Whisper.cpp priority)
+- Error handling for all providers
+- Audio transcription functionality
+- API request formatting
+
+## Architecture
+
+This is a TypeScript npm package (`@derogab/stt-proxy`) that provides a unified interface for multiple STT providers. The entire implementation is in a single file: `src/index.ts`.
+
+### Provider Selection
+
+The `transcribe()` function automatically selects a provider based on environment variables in this priority order:
+1. **Whisper.cpp** - if `WHISPER_CPP_MODEL_PATH` is set
+
+### Build Output
+
+The package builds to three output formats:
+- `dist/cjs/` - CommonJS (for `require()`)
+- `dist/esm/` - ES Modules (for `import`)
+- `dist/types/` - TypeScript declarations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriele De Rosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# stt-proxy
+A simple and lightweight proxy for seamless integration with multiple STT providers including Whisper.cpp.
+
+## Features
+
+- **Multi-provider support**: Switch between STT providers with environment variables.
+- **TypeScript support**: Full TypeScript definitions included.
+- **Simple API**: Single function interface for all providers.
+- **Automatic provider detection**: Automatically selects the best available provider based on environment variables.
+
+## Installation
+
+```bash
+npm install @derogab/stt-proxy
+```
+
+## Quick Start
+
+```typescript
+import { transcribe } from '@derogab/stt-proxy';
+
+const result = await transcribe('/path/to/audio.wav');
+console.log(result.text);
+```
+
+## Configuration
+
+The package automatically detects which STT provider to use based on your environment variables.
+Configure one or more providers:
+
+### Whisper.cpp (Local)
+```bash
+WHISPER_CPP_MODEL_PATH=/path/to/ggml-base.bin # Required, path to your GGML model file
+```
+
+Download models from [HuggingFace](https://huggingface.co/ggerganov/whisper.cpp/tree/main):
+```bash
+curl -L -o ggml-base.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin
+```
+
+## API Reference
+
+### `transcribe(audio: string | Buffer, options?): Promise<TranscribeOutput>`
+
+Transcribes audio to text using the configured STT provider.
+
+**Parameters:**
+- `audio`: Path to audio file or audio Buffer
+- `options` (optional): Transcription options
+
+**Returns:**
+- Promise that resolves to an object with `text` property
+
+**Options Format:**
+```typescript
+type TranscribeOptions = {
+  language?: string;   // Language code (e.g., 'en', 'es', 'fr')
+  translate?: boolean; // Translate to English
+};
+```
+
+**Output Format:**
+```typescript
+type TranscribeOutput = {
+  text: string;
+};
+```
+
+### `transcribeBuffer(buffer: Buffer, options?): Promise<TranscribeOutput>`
+
+Transcribes audio from a Buffer.
+
+### `isWhisperConfigured(): boolean`
+
+Check if Whisper.cpp is configured and ready.
+
+### `freeWhisper(): Promise<void>`
+
+Release Whisper instance and free memory.
+
+### `getAvailableModels(): string[]`
+
+Get list of available Whisper model names.
+
+### `getModelUrl(model: string): string`
+
+Get HuggingFace download URL for a model.
+
+## Provider Priority
+
+The package selects providers in the following order:
+1. **Whisper.cpp** (if `WHISPER_CPP_MODEL_PATH` is set)
+
+If no providers are configured, the function throws an error.
+
+## Requirements
+
+- **FFmpeg**: Required for audio conversion.
+  ```bash
+  # macOS
+  brew install ffmpeg
+
+  # Ubuntu/Debian
+  sudo apt install ffmpeg
+
+  # Windows (with Chocolatey)
+  choco install ffmpeg
+  ```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+```
+
+## Credits
+_STT Proxy_ is made with ♥ by [derogab](https://github.com/derogab) and it's released under the [MIT license](./LICENSE).
+
+## Contributors
+
+<a href="https://github.com/derogab/stt-proxy/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=derogab/stt-proxy" />
+</a>
+
+## Tip
+If you like this project or directly benefit from it, please consider buying me a coffee:  
+🔗 `bc1qd0qatgz8h62uvnr74utwncc6j5ckfz2v2g4lef`  
+⚡️ `derogab@sats.mobi`  
+💶 [Sponsor on GitHub](https://github.com/sponsors/derogab)
+
+## Stargazers over time
+[![Stargazers over time](https://starchart.cc/derogab/stt-proxy.svg?variant=adaptive)](https://starchart.cc/derogab/stt-proxy)

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@derogab/stt-proxy",
+  "version": "0.1.0",
+  "description": "A simple and lightweight proxy for seamless integration with multiple STT (Speech-to-Text) providers including Whisper.cpp",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "vitest run",
+    "test:unit": "vitest run --exclude='**/*.integration.test.*'",
+    "test:whisper": "vitest run --testTimeout=300000 --hookTimeout=600000 test/whisper-cpp.integration.test.ts",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit -p tsconfig.esm.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/derogab/stt-proxy.git"
+  },
+  "keywords": [
+    "STT",
+    "speech-to-text",
+    "transcription",
+    "whisper",
+    "whisper.cpp",
+    "proxy",
+    "gateway"
+  ],
+  "author": "derogab",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/derogab/stt-proxy/issues"
+  },
+  "homepage": "https://github.com/derogab/stt-proxy#readme",
+  "dependencies": {
+    "dotenv": "16.5.0",
+    "smart-whisper": "0.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "@vitest/coverage-v8": "^3.1.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+import 'dotenv/config';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execSync } from 'child_process';
+import type { Whisper, TranscribeResult } from 'smart-whisper';
+
+export interface TranscribeOptions {
+  language?: string;
+  translate?: boolean;
+}
+
+export interface TranscribeOutput {
+  text: string;
+}
+
+let whisperInstance: Whisper | null = null;
+let currentModelPath: string | null = null;
+
+function getWhisperModelPath(): string | undefined {
+  return process.env['WHISPER_CPP_MODEL_PATH'];
+}
+
+export function isWhisperConfigured(): boolean {
+  const modelPath = getWhisperModelPath();
+  return modelPath !== undefined && fs.existsSync(modelPath);
+}
+
+async function getWhisperInstance(): Promise<Whisper> {
+  const modelPath = getWhisperModelPath();
+
+  if (!modelPath) {
+    throw new Error('WHISPER_CPP_MODEL_PATH environment variable is not set');
+  }
+
+  if (!fs.existsSync(modelPath)) {
+    throw new Error(`Whisper model not found at path: ${modelPath}`);
+  }
+
+  if (whisperInstance && currentModelPath === modelPath) {
+    return whisperInstance;
+  }
+
+  if (whisperInstance) {
+    await whisperInstance.free();
+    whisperInstance = null;
+  }
+
+  const { Whisper } = await import('smart-whisper');
+  whisperInstance = new Whisper(modelPath, { gpu: true });
+  currentModelPath = modelPath;
+
+  return whisperInstance;
+}
+
+function audioToPcm(audioPath: string): Float32Array {
+  const tempDir = os.tmpdir();
+  const tempPcmPath = path.join(tempDir, `whisper_${Date.now()}_${Math.random().toString(36).substring(7)}.pcm`);
+
+  try {
+    execSync(
+      `ffmpeg -y -i "${audioPath}" -ar 16000 -ac 1 -f f32le "${tempPcmPath}"`,
+      { stdio: 'pipe' }
+    );
+
+    const pcmBuffer = fs.readFileSync(tempPcmPath);
+    return new Float32Array(pcmBuffer.buffer, pcmBuffer.byteOffset, pcmBuffer.length / 4);
+  } finally {
+    if (fs.existsSync(tempPcmPath)) {
+      fs.unlinkSync(tempPcmPath);
+    }
+  }
+}
+
+function cleanTranscription(text: string): string {
+  return text
+    .replace(/[\x00-\x1F\x7F]/g, '')
+    .trim();
+}
+
+function resultsToText(results: TranscribeResult<'simple'>[]): string {
+  return results.map((r) => r.text).join(' ');
+}
+
+async function transcribe_whispercpp(audioPath: string, options: TranscribeOptions = {}): Promise<TranscribeOutput> {
+  if (!fs.existsSync(audioPath)) {
+    throw new Error(`Audio file not found: ${audioPath}`);
+  }
+
+  const whisper = await getWhisperInstance();
+  const pcmData = audioToPcm(audioPath);
+
+  const transcribeParams: { language?: string; translate?: boolean; format: 'simple' } = {
+    format: 'simple',
+  };
+
+  if (options.language !== undefined) {
+    transcribeParams.language = options.language;
+  }
+
+  if (options.translate !== undefined) {
+    transcribeParams.translate = options.translate;
+  }
+
+  const task = await whisper.transcribe(pcmData, transcribeParams);
+  const results = await task.result;
+  const text = resultsToText(results);
+
+  return {
+    text: cleanTranscription(text),
+  };
+}
+
+export async function transcribe(audio: string | Buffer, options: TranscribeOptions = {}): Promise<TranscribeOutput> {
+  const modelPath = getWhisperModelPath();
+
+  if (modelPath) {
+    if (Buffer.isBuffer(audio)) {
+      return transcribeBuffer(audio, options);
+    }
+    return transcribe_whispercpp(audio, options);
+  }
+
+  throw new Error('No STT provider configured. Set WHISPER_CPP_MODEL_PATH environment variable.');
+}
+
+export async function transcribeBuffer(audioBuffer: Buffer, options: TranscribeOptions = {}): Promise<TranscribeOutput> {
+  const modelPath = getWhisperModelPath();
+
+  if (!modelPath) {
+    throw new Error('No STT provider configured. Set WHISPER_CPP_MODEL_PATH environment variable.');
+  }
+
+  const tempDir = os.tmpdir();
+  const tempPath = path.join(tempDir, `whisper_input_${Date.now()}_${Math.random().toString(36).substring(7)}.audio`);
+
+  fs.writeFileSync(tempPath, audioBuffer);
+
+  try {
+    const result = await transcribe_whispercpp(tempPath, options);
+    return result;
+  } finally {
+    if (fs.existsSync(tempPath)) {
+      fs.unlinkSync(tempPath);
+    }
+  }
+}
+
+export async function freeWhisper(): Promise<void> {
+  if (whisperInstance) {
+    await whisperInstance.free();
+    whisperInstance = null;
+    currentModelPath = null;
+  }
+}
+
+export function getAvailableModels(): string[] {
+  return [
+    'tiny',
+    'tiny.en',
+    'base',
+    'base.en',
+    'small',
+    'small.en',
+    'medium',
+    'medium.en',
+    'large',
+    'large-v2',
+    'large-v3',
+    'large-v3-turbo',
+  ];
+}
+
+export function getModelUrl(model: string): string {
+  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${model}.bin`;
+}

package/test/index.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+
+vi.mock('fs', async () => {
+  const actual = await vi.importActual<typeof import('fs')>('fs');
+  return {
+    ...actual,
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    unlinkSync: vi.fn(),
+  };
+});
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+vi.mock('smart-whisper', () => ({
+  Whisper: vi.fn().mockImplementation(() => ({
+    transcribe: vi.fn().mockResolvedValue({
+      result: Promise.resolve([{ text: 'Hello, world!', from: 0, to: 1000 }]),
+    }),
+    free: vi.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+describe('stt-proxy', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+    delete process.env['WHISPER_CPP_MODEL_PATH'];
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    vi.resetModules();
+  });
+
+  describe('isWhisperConfigured', () => {
+    it('should return false when WHISPER_CPP_MODEL_PATH is not set', async () => {
+      const { isWhisperConfigured } = await import('../src/index.js');
+      expect(isWhisperConfigured()).toBe(false);
+    });
+
+    it('should return false when WHISPER_CPP_MODEL_PATH is set but file does not exist', async () => {
+      process.env['WHISPER_CPP_MODEL_PATH'] = '/path/to/model.bin';
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+      const { isWhisperConfigured } = await import('../src/index.js');
+      expect(isWhisperConfigured()).toBe(false);
+    });
+
+    it('should return true when WHISPER_CPP_MODEL_PATH is set and file exists', async () => {
+      process.env['WHISPER_CPP_MODEL_PATH'] = '/path/to/model.bin';
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      const { isWhisperConfigured } = await import('../src/index.js');
+      expect(isWhisperConfigured()).toBe(true);
+    });
+  });
+
+  describe('transcribe', () => {
+    it('should throw error when no provider is configured', async () => {
+      const { transcribe } = await import('../src/index.js');
+      await expect(transcribe('/path/to/audio.wav')).rejects.toThrow(
+        'No STT provider configured'
+      );
+    });
+
+    it('should throw error when audio file does not exist', async () => {
+      process.env['WHISPER_CPP_MODEL_PATH'] = '/path/to/model.bin';
+      vi.mocked(fs.existsSync).mockImplementation((path) => {
+        if (path === '/path/to/model.bin') return true;
+        return false;
+      });
+      const { transcribe } = await import('../src/index.js');
+      await expect(transcribe('/path/to/audio.wav')).rejects.toThrow(
+        'Audio file not found'
+      );
+    });
+
+    it('should throw error when model file does not exist', async () => {
+      process.env['WHISPER_CPP_MODEL_PATH'] = '/path/to/model.bin';
+      vi.mocked(fs.existsSync).mockImplementation((path) => {
+        if (path === '/path/to/audio.wav') return true;
+        return false;
+      });
+      const { transcribe } = await import('../src/index.js');
+      await expect(transcribe('/path/to/audio.wav')).rejects.toThrow(
+        'Whisper model not found at path'
+      );
+    });
+  });
+
+  describe('getAvailableModels', () => {
+    it('should return list of available models', async () => {
+      const { getAvailableModels } = await import('../src/index.js');
+      const models = getAvailableModels();
+      expect(models).toContain('tiny');
+      expect(models).toContain('base');
+      expect(models).toContain('small');
+      expect(models).toContain('medium');
+      expect(models).toContain('large');
+      expect(models).toContain('large-v3-turbo');
+      expect(models.length).toBe(12);
+    });
+  });
+
+  describe('getModelUrl', () => {
+    it('should return correct HuggingFace URL for model', async () => {
+      const { getModelUrl } = await import('../src/index.js');
+      const url = getModelUrl('base');
+      expect(url).toBe('https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin');
+    });
+
+    it('should return correct URL for large-v3-turbo model', async () => {
+      const { getModelUrl } = await import('../src/index.js');
+      const url = getModelUrl('large-v3-turbo');
+      expect(url).toBe('https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin');
+    });
+  });
+
+  describe('freeWhisper', () => {
+    it('should not throw when called without active instance', async () => {
+      const { freeWhisper } = await import('../src/index.js');
+      await expect(freeWhisper()).resolves.not.toThrow();
+    });
+  });
+
+  describe('transcribeBuffer', () => {
+    it('should throw error when no provider is configured', async () => {
+      const { transcribeBuffer } = await import('../src/index.js');
+      const buffer = Buffer.from('test');
+      await expect(transcribeBuffer(buffer)).rejects.toThrow(
+        'No STT provider configured'
+      );
+    });
+  });
+
+  describe('type exports', () => {
+    it('should export transcribe function', async () => {
+      const module = await import('../src/index.js');
+      expect(typeof module.transcribe).toBe('function');
+    });
+
+    it('should export transcribeBuffer function', async () => {
+      const module = await import('../src/index.js');
+      expect(typeof module.transcribeBuffer).toBe('function');
+    });
+
+    it('should export isWhisperConfigured function', async () => {
+      const module = await import('../src/index.js');
+      expect(typeof module.isWhisperConfigured).toBe('function');
+    });
+
+    it('should export freeWhisper function', async () => {
+      const module = await import('../src/index.js');
+      expect(typeof module.freeWhisper).toBe('function');
+    });
+
+    it('should export getAvailableModels function', async () => {
+      const module = await import('../src/index.js');
+      expect(typeof module.getAvailableModels).toBe('function');
+    });
+
+    it('should export getModelUrl function', async () => {
+      const module = await import('../src/index.js');
+      expect(typeof module.getModelUrl).toBe('function');
+    });
+  });
+});

package/test/whisper-cpp.integration.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as https from 'https';
+import * as http from 'http';
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+const TEST_MODEL_DIR = path.join(__dirname, 'models');
+const TEST_AUDIO_DIR = path.join(__dirname, 'audio');
+const MODEL_NAME = 'ggml-tiny.bin';
+const MODEL_PATH = path.join(TEST_MODEL_DIR, MODEL_NAME);
+const AUDIO_FILE = path.join(TEST_AUDIO_DIR, 'jfk.wav');
+
+const MODEL_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin';
+const JFK_AUDIO_URL = 'https://github.com/ggerganov/whisper.cpp/raw/master/samples/jfk.wav';
+
+async function downloadFile(url: string, destPath: string, maxRedirects = 10): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) {
+      return reject(new Error('Too many redirects'));
+    }
+
+    const dir = path.dirname(destPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const protocol = url.startsWith('https') ? https : http;
+
+    protocol.get(url, (response) => {
+      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        let redirectUrl = response.headers.location;
+        if (redirectUrl.startsWith('/')) {
+          const urlObj = new URL(url);
+          redirectUrl = `${urlObj.protocol}//${urlObj.host}${redirectUrl}`;
+        }
+        downloadFile(redirectUrl, destPath, maxRedirects - 1).then(resolve).catch(reject);
+        return;
+      } else if (response.statusCode === 200) {
+        const file = fs.createWriteStream(destPath);
+        response.pipe(file);
+        file.on('finish', () => {
+          file.close();
+          resolve();
+        });
+        file.on('error', (err) => {
+          fs.unlinkSync(destPath);
+          reject(err);
+        });
+      } else {
+        reject(new Error(`HTTP ${response.statusCode}`));
+      }
+    }).on('error', reject);
+  });
+}
+
+function normalizeTranscription(text: string): string {
+  return text.toLowerCase().replace(/[.,!?]/g, '').trim();
+}
+
+describe('whisper.cpp integration tests', () => {
+  let transcribe: typeof import('../src/index.js').transcribe;
+  let transcribeBuffer: typeof import('../src/index.js').transcribeBuffer;
+  let isWhisperConfigured: typeof import('../src/index.js').isWhisperConfigured;
+  let freeWhisper: typeof import('../src/index.js').freeWhisper;
+
+  beforeAll(async () => {
+    // Download model if needed
+    if (!fs.existsSync(MODEL_PATH) || fs.statSync(MODEL_PATH).size === 0) {
+      if (fs.existsSync(MODEL_PATH)) fs.unlinkSync(MODEL_PATH);
+      console.log(`Downloading Whisper tiny model to ${MODEL_PATH}...`);
+      console.log('This may take a few minutes on first run.');
+      await downloadFile(MODEL_URL, MODEL_PATH);
+      console.log('Model downloaded successfully.');
+    }
+
+    // Download audio if needed
+    if (!fs.existsSync(AUDIO_FILE) || fs.statSync(AUDIO_FILE).size === 0) {
+      if (fs.existsSync(AUDIO_FILE)) fs.unlinkSync(AUDIO_FILE);
+      console.log(`Downloading JFK test audio to ${AUDIO_FILE}...`);
+      await downloadFile(JFK_AUDIO_URL, AUDIO_FILE);
+      console.log('Audio downloaded successfully.');
+    }
+
+    // Set model path
+    process.env['WHISPER_CPP_MODEL_PATH'] = MODEL_PATH;
+
+    // Import module
+    const stt = await import('../src/index.js');
+    transcribe = stt.transcribe;
+    transcribeBuffer = stt.transcribeBuffer;
+    isWhisperConfigured = stt.isWhisperConfigured;
+    freeWhisper = stt.freeWhisper;
+  }, 600000); // 10 minute timeout for model download
+
+  afterAll(async () => {
+    if (freeWhisper) {
+      await freeWhisper();
+    }
+  });
+
+  it('should transcribe JFK speech audio file', async () => {
+    const result = await transcribe(AUDIO_FILE);
+
+    expect(result).toBeDefined();
+    expect(result.text).toBeDefined();
+    expect(typeof result.text).toBe('string');
+    expect(result.text.length).toBeGreaterThan(0);
+
+    const normalizedResult = normalizeTranscription(result.text);
+    expect(normalizedResult).toContain('ask not what your country can do for you');
+  }, 300000); // 5 minute timeout
+
+  it('should transcribe audio from buffer', async () => {
+    const audioBuffer = fs.readFileSync(AUDIO_FILE);
+    const result = await transcribeBuffer(audioBuffer);
+
+    expect(result).toBeDefined();
+    expect(result.text).toBeDefined();
+    expect(typeof result.text).toBe('string');
+    expect(result.text.length).toBeGreaterThan(0);
+
+    const normalizedResult = normalizeTranscription(result.text);
+    expect(normalizedResult).toContain('ask not what your country can do for you');
+  }, 300000); // 5 minute timeout
+
+  it('should return true for isWhisperConfigured', () => {
+    expect(isWhisperConfigured()).toBe(true);
+  });
+
+  it('should throw error for non-existent audio file', async () => {
+    await expect(transcribe('/non/existent/audio.wav')).rejects.toThrow('Audio file not found');
+  });
+});

package/tsconfig.cjs.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "outDir": "./dist/cjs",
+    "declaration": false,
+    "declarationMap": false,
+    "verbatimModuleSyntax": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.test.ts", "vitest.config.ts"]
+}

package/tsconfig.esm.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "outDir": "./dist/esm",
+    "declaration": false,
+    "declarationMap": false,
+    "verbatimModuleSyntax": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.test.ts", "vitest.config.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "esnext",
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  }
+}

package/tsconfig.types.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "outDir": "./dist/types",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "verbatimModuleSyntax": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.test.ts", "vitest.config.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      include: ['src/**/*.ts'],
+    },
+  },
+});