@derogab/stt-proxy 0.1.0 → 0.2.0

package/README.md

@@ -42,10 +42,10 @@ curl -L -o ggml-base.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/ma
 
 ### `transcribe(audio: string | Buffer, options?): Promise<TranscribeOutput>`
 
-Transcribes audio to text using the configured STT provider.
+Transcribes audio to text using the configured STT provider. The package automatically manages provider initialization and cleanup.
 
 **Parameters:**
-- `audio`: Path to audio file or audio Buffer
+- `audio`: Path to audio file (string) or audio Buffer
 - `options` (optional): Transcription options
 
 **Returns:**
@@ -66,25 +66,24 @@ type TranscribeOutput = {
 };
 ```
 
-### `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.
+**Example:**
+```typescript
+// Transcribe from file path
+const result1 = await transcribe('/path/to/audio.wav');
+console.log(result1.text);
+
+// Transcribe from Buffer
+const audioBuffer = fs.readFileSync('/path/to/audio.wav');
+const result2 = await transcribe(audioBuffer);
+console.log(result2.text);
+
+// With options
+const result3 = await transcribe('/path/to/audio.wav', {
+  language: 'en',
+  translate: false
+});
+console.log(result3.text);
+```
 
 ## Provider Priority
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@derogab/stt-proxy",
-  "version": "0.1.0",
+  "version": "0.2.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",

package/src/index.ts

@@ -21,7 +21,7 @@ function getWhisperModelPath(): string | undefined {
   return process.env['WHISPER_CPP_MODEL_PATH'];
 }
 
-export function isWhisperConfigured(): boolean {
+function isWhisperConfigured(): boolean {
   const modelPath = getWhisperModelPath();
   return modelPath !== undefined && fs.existsSync(modelPath);
 }
@@ -124,7 +124,7 @@ export async function transcribe(audio: string | Buffer, options: TranscribeOpti
   throw new Error('No STT provider configured. Set WHISPER_CPP_MODEL_PATH environment variable.');
 }
 
-export async function transcribeBuffer(audioBuffer: Buffer, options: TranscribeOptions = {}): Promise<TranscribeOutput> {
+async function transcribeBuffer(audioBuffer: Buffer, options: TranscribeOptions = {}): Promise<TranscribeOutput> {
   const modelPath = getWhisperModelPath();
 
   if (!modelPath) {
@@ -146,7 +146,7 @@ export async function transcribeBuffer(audioBuffer: Buffer, options: TranscribeO
   }
 }
 
-export async function freeWhisper(): Promise<void> {
+async function freeWhisper(): Promise<void> {
   if (whisperInstance) {
     await whisperInstance.free();
     whisperInstance = null;
@@ -154,23 +154,21 @@ export async function freeWhisper(): Promise<void> {
   }
 }
 
-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',
-  ];
-}
+// Automatically clean up Whisper instance on process exit
+process.on('exit', () => {
+  if (whisperInstance) {
+    // Note: Cannot use async operations in 'exit' handler
+    // The instance will be cleaned up by the process termination
+    whisperInstance = null;
+    currentModelPath = null;
+  }
+});
 
-export function getModelUrl(model: string): string {
-  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${model}.bin`;
-}
+// Handle graceful shutdown signals
+const shutdownHandler = async () => {
+  await freeWhisper();
+  process.exit(0);
+};
+
+process.on('SIGINT', shutdownHandler);
+process.on('SIGTERM', shutdownHandler);

package/test/index.test.ts

@@ -39,35 +39,23 @@ describe('stt-proxy', () => {
     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 () => {
+    it('should throw error when no provider is configured (string path)', 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 no provider is configured (Buffer)', async () => {
+      const { transcribe } = await import('../src/index.js');
+      const buffer = Buffer.from('test');
+      await expect(transcribe(buffer)).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) => {
@@ -91,82 +79,50 @@ describe('stt-proxy', () => {
         '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);
-    });
-  });
+    it('should successfully transcribe audio file', async () => {
+      process.env['WHISPER_CPP_MODEL_PATH'] = '/path/to/model.bin';
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      // Mock readFileSync to return a valid PCM buffer (Float32Array requires 4-byte aligned buffer)
+      const pcmData = new Float32Array([0.1, 0.2, 0.3]);
+      vi.mocked(fs.readFileSync).mockReturnValue(Buffer.from(pcmData.buffer));
+      const { transcribe } = await import('../src/index.js');
 
-  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');
-    });
+      const result = await transcribe('/path/to/audio.wav');
 
-    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');
+      expect(result).toBeDefined();
+      expect(result.text).toBe('Hello, world!');
     });
-  });
 
-  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();
-    });
-  });
+    it('should successfully transcribe audio from buffer', async () => {
+      process.env['WHISPER_CPP_MODEL_PATH'] = '/path/to/model.bin';
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      // Mock readFileSync to return a valid PCM buffer (Float32Array requires 4-byte aligned buffer)
+      const pcmData = new Float32Array([0.1, 0.2, 0.3]);
+      vi.mocked(fs.readFileSync).mockReturnValue(Buffer.from(pcmData.buffer));
+      const { transcribe } = await import('../src/index.js');
 
-  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'
-      );
+      const audioBuffer = Buffer.from('fake audio data');
+      const result = await transcribe(audioBuffer);
+
+      expect(result).toBeDefined();
+      expect(result.text).toBe('Hello, world!');
     });
   });
 
-  describe('type exports', () => {
+
+  describe('API 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 () => {
+    it('should only export transcribe function (no other functions)', 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');
+      const exportedFunctions = Object.keys(module).filter(
+        key => typeof module[key as keyof typeof module] === 'function'
+      );
+      expect(exportedFunctions).toEqual(['transcribe']);
     });
   });
 });

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

@@ -61,9 +61,6 @@ function normalizeTranscription(text: string): string {
 
 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
@@ -89,17 +86,8 @@ describe('whisper.cpp integration tests', () => {
     // 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);
 
@@ -114,7 +102,7 @@ describe('whisper.cpp integration tests', () => {
 
   it('should transcribe audio from buffer', async () => {
     const audioBuffer = fs.readFileSync(AUDIO_FILE);
-    const result = await transcribeBuffer(audioBuffer);
+    const result = await transcribe(audioBuffer);
 
     expect(result).toBeDefined();
     expect(result.text).toBeDefined();
@@ -125,10 +113,6 @@ describe('whisper.cpp integration tests', () => {
     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');
   });