@wovin/tranz 0.1.4 → 0.1.6

package/README.md

@@ -8,6 +8,7 @@ Audio transcription library with provider support and auto-splitting for long au
 ## Features
 
 - **Multiple Transcription Providers**: Mistral Voxtral, Whisper, GreenPT
+- **Realtime Transcription**: Stream audio from microphone or other sources for live transcription
 - **Automatic Audio Splitting**: Handles long audio files by intelligently splitting at silence points
 - **Smart Input Support**: Files, URLs (with HTTP range probing), or buffers
 - **Speaker Diarization**: Identify different speakers in audio
@@ -147,6 +148,72 @@ const result = await whisper.transcribe({
 })
 ```
 
+## Realtime Transcription
+
+Stream audio for real-time transcription using Mistral's WebSocket API:
+
+```typescript
+import {
+  createRealtimeTranscriber,
+  captureAudioFromMicrophone,
+} from '@wovin/tranz/realtime'
+
+// Create realtime transcriber
+const transcriber = createRealtimeTranscriber({
+  apiKey: process.env.MISTRAL_API_KEY,
+})
+
+// Capture audio from microphone (requires SoX)
+const { stream, stop } = captureAudioFromMicrophone(16000)
+
+try {
+  for await (const event of transcriber.transcribe(stream)) {
+    if (event.type === 'transcription.text.delta') {
+      process.stdout.write(event.text)
+    } else if (event.type === 'transcription.done') {
+      console.log('\nComplete:', event.text)
+      break
+    }
+  }
+} finally {
+  stop()
+}
+```
+
+### Custom Audio Source
+
+You can provide any `AsyncIterable<Uint8Array>` as an audio source:
+
+```typescript
+async function* myAudioSource() {
+  // Read from file, socket, etc.
+  const buffer = await readSomeAudio()
+  yield new Uint8Array(buffer)
+}
+
+for await (const event of transcriber.transcribe(myAudioSource())) {
+  // Handle events
+}
+```
+
+### Realtime Event Types
+
+- `session.created` - WebSocket connection established
+- `session.updated` - Audio format confirmed
+- `transcription.text.delta` - Transcription text chunks (use for live display)
+- `transcription.language` - Detected audio language
+- `transcription.done` - Complete transcript available
+- `error` - Error occurred
+
+### Limitations
+
+The WebSocket realtime API has some limitations compared to batch transcription:
+- No timestamp information (no word or segment timing)
+- No speaker diarization
+- Designed for streaming/live use cases, not long audio files
+
+For timestamped transcriptions or speaker identification, use the batch API instead.
+
 ## Advanced: Audio Utilities
 
 ```typescript

package/dist/index.min.js

@@ -215,6 +215,9 @@ var MistralProvider = class {
     return VOXTRAL_LIMITS.recommendedMaxDurationSec;
   }
   async transcribe(params) {
+    if (params.language && params.timestampGranularity) {
+      return { text: "", error: "Cannot use both language and timestampGranularity (Mistral API limitation)" };
+    }
     const formData = new FormData();
     if (params.audioUrl) {
       formData.append("file_url", params.audioUrl);
@@ -239,14 +242,14 @@ var MistralProvider = class {
     if (params.language) {
       formData.append("language", params.language);
     }
-    const timestampGranularity = params.timestampGranularity ?? (params.language ? void 0 : "word");
-    if (timestampGranularity) {
-      formData.append("timestamp_granularities", timestampGranularity);
-    }
     const diarize = params.diarize ?? true;
     if (diarize) {
       formData.append("diarize", "true");
     }
+    const timestampGranularity = params.language ? void 0 : params.timestampGranularity ?? "segment";
+    if (timestampGranularity) {
+      formData.append("timestamp_granularities", timestampGranularity);
+    }
     const response = await fetch("https://api.mistral.ai/v1/audio/transcriptions", {
       method: "POST",
       headers: {

package/dist/providers.min.js

@@ -215,6 +215,9 @@ var MistralProvider = class {
     return VOXTRAL_LIMITS.recommendedMaxDurationSec;
   }
   async transcribe(params) {
+    if (params.language && params.timestampGranularity) {
+      return { text: "", error: "Cannot use both language and timestampGranularity (Mistral API limitation)" };
+    }
     const formData = new FormData();
     if (params.audioUrl) {
       formData.append("file_url", params.audioUrl);
@@ -239,14 +242,14 @@ var MistralProvider = class {
     if (params.language) {
       formData.append("language", params.language);
     }
-    const timestampGranularity = params.timestampGranularity ?? (params.language ? void 0 : "word");
-    if (timestampGranularity) {
-      formData.append("timestamp_granularities", timestampGranularity);
-    }
     const diarize = params.diarize ?? true;
     if (diarize) {
       formData.append("diarize", "true");
     }
+    const timestampGranularity = params.language ? void 0 : params.timestampGranularity ?? "segment";
+    if (timestampGranularity) {
+      formData.append("timestamp_granularities", timestampGranularity);
+    }
     const response = await fetch("https://api.mistral.ai/v1/audio/transcriptions", {
       method: "POST",
       headers: {

package/dist/realtime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Realtime transcription API
+ *
+ * This module provides a simple, event-driven interface for streaming audio
+ * transcription using Mistral's realtime WebSocket API.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createRealtimeTranscriber,
+ *   captureAudioFromMicrophone,
+ * } from '@wovin/tranz/realtime'
+ *
+ * const transcriber = createRealtimeTranscriber({
+ *   apiKey: process.env.MISTRAL_API_KEY,
+ * })
+ *
+ * const { stream, stop } = captureAudioFromMicrophone(16000)
+ *
+ * try {
+ *   for await (const event of transcriber.transcribe(stream)) {
+ *     if (event.type === 'transcription.text.delta') {
+ *       process.stdout.write(event.text)
+ *     } else if (event.type === 'transcription.done') {
+ *       console.log('\nComplete!')
+ *       break
+ *     }
+ *   }
+ * } finally {
+ *   stop()
+ * }
+ * ```
+ *
+ * @module @wovin/tranz/realtime
+ */
+export { createRealtimeTranscriber, captureAudioFromMicrophone, type RealtimeEvent, type RealtimeConfig, type RealtimeTranscriber, type TranscribeOptions, type AudioFormat, type AudioCaptureResult, type SessionCreatedEvent, type SessionUpdatedEvent, type TranscriptionTextDeltaEvent, type TranscriptionLanguageEvent, type TranscriptionSegmentEvent, type TranscriptionDoneEvent, type ErrorEvent, } from "./utils/transcription/realtime.js";
+export { AudioEncoding } from "@mistralai/mistralai/extra/realtime";
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,UAAU,GAChB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/realtime.min.js

@@ -0,0 +1,95 @@
+// src/utils/transcription/realtime.ts
+import { spawn } from "child_process";
+import {
+  AudioEncoding,
+  RealtimeTranscription
+} from "@mistralai/mistralai/extra/realtime";
+function createRealtimeTranscriber(config) {
+  const model = config.model ?? "voxtral-mini-transcribe-realtime-2602";
+  const baseUrl = config.baseUrl ?? "wss://api.mistral.ai";
+  const client = new RealtimeTranscription({
+    apiKey: config.apiKey,
+    serverURL: baseUrl
+  });
+  return {
+    async *transcribe(audioStream, options) {
+      const audioFormat = {
+        encoding: options?.audioFormat?.encoding ?? AudioEncoding.PcmS16le,
+        sampleRate: options?.audioFormat?.sampleRate ?? 16e3
+      };
+      const eventStream = client.transcribeStream(audioStream, model, {
+        audioFormat
+      });
+      for await (const event of eventStream) {
+        yield event;
+      }
+    }
+  };
+}
+function captureAudioFromMicrophone(sampleRate = 16e3) {
+  const recorder = spawn(
+    "rec",
+    [
+      "-q",
+      // Quiet mode
+      "-t",
+      "raw",
+      // Raw PCM output
+      "-b",
+      "16",
+      // 16-bit samples
+      "-e",
+      "signed-integer",
+      // Signed PCM
+      "-r",
+      String(sampleRate),
+      // Sample rate
+      "-c",
+      "1",
+      // Mono (1 channel)
+      "-"
+      // Output to stdout
+    ],
+    { stdio: ["ignore", "pipe", "ignore"] }
+  );
+  recorder.on("error", (err) => {
+    const error = err;
+    if (error.code === "ENOENT") {
+      console.error(
+        "\nError: 'rec' command not found. Please install SoX:",
+        "\n  macOS: brew install sox",
+        "\n  Linux: sudo apt install sox"
+      );
+      process.exit(1);
+    }
+    throw err;
+  });
+  const stream = (async function* () {
+    try {
+      if (!recorder.stdout) {
+        throw new Error("Failed to create audio capture stream");
+      }
+      for await (const chunk of recorder.stdout) {
+        yield new Uint8Array(chunk);
+      }
+    } finally {
+      if (!recorder.killed) {
+        recorder.kill("SIGTERM");
+      }
+    }
+  })();
+  const stop = () => {
+    if (!recorder.killed) {
+      recorder.kill("SIGTERM");
+    }
+  };
+  return { stream, stop };
+}
+
+// src/realtime.ts
+import { AudioEncoding as AudioEncoding2 } from "@mistralai/mistralai/extra/realtime";
+export {
+  AudioEncoding2 as AudioEncoding,
+  captureAudioFromMicrophone,
+  createRealtimeTranscriber
+};

package/dist/utils/transcription/providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/utils/transcription/providers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/utils/transcription/providers.ts"],"names":[],"mappings":"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"}

package/dist/utils/transcription/realtime.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Realtime transcription API for Mistral's WebSocket-based transcription service
+ *
+ * Provides a simple, event-driven interface for streaming audio transcription.
+ * Users provide audio as AsyncIterable<Uint8Array> and receive typed events.
+ *
+ * @example
+ * ```typescript
+ * import { createRealtimeTranscriber } from '@wovin/tranz/realtime'
+ *
+ * const transcriber = createRealtimeTranscriber({
+ *   apiKey: process.env.MISTRAL_API_KEY,
+ * })
+ *
+ * for await (const event of transcriber.transcribe(audioStream)) {
+ *   if (event.type === 'transcription.text.delta') {
+ *     process.stdout.write(event.text)
+ *   }
+ * }
+ * ```
+ */
+import { AudioEncoding } from "@mistralai/mistralai/extra/realtime";
+/**
+ * Audio format configuration for realtime transcription
+ */
+export interface AudioFormat {
+    /** Audio encoding format (default: pcm_s16le) */
+    encoding: AudioEncoding;
+    /** Sample rate in Hz (default: 16000) */
+    sampleRate: number;
+}
+/**
+ * Configuration for creating a realtime transcriber
+ */
+export interface RealtimeConfig {
+    /** Mistral API key */
+    apiKey: string;
+    /** Model ID (default: voxtral-mini-transcribe-realtime-2602) */
+    model?: string;
+    /** WebSocket base URL (default: wss://api.mistral.ai) */
+    baseUrl?: string;
+}
+/**
+ * Options for transcription
+ */
+export interface TranscribeOptions {
+    /** Audio format configuration (optional, uses defaults if not provided) */
+    audioFormat?: Partial<AudioFormat>;
+}
+/**
+ * Union type for all realtime transcription events
+ * These events are yielded as the transcription progresses
+ */
+export type RealtimeEvent = SessionCreatedEvent | SessionUpdatedEvent | TranscriptionTextDeltaEvent | TranscriptionLanguageEvent | TranscriptionSegmentEvent | TranscriptionDoneEvent | ErrorEvent;
+/**
+ * Session created event - emitted when WebSocket connection is established
+ */
+export interface SessionCreatedEvent {
+    type: "session.created";
+    session: {
+        id: string;
+    };
+}
+/**
+ * Session updated event - emitted when audio format is confirmed
+ */
+export interface SessionUpdatedEvent {
+    type: "session.updated";
+    session: {
+        audioFormat: AudioFormat;
+    };
+}
+/**
+ * Text delta event - emitted as transcription text arrives in chunks
+ * This is the primary event for displaying real-time transcription
+ */
+export interface TranscriptionTextDeltaEvent {
+    type: "transcription.text.delta";
+    text: string;
+}
+/**
+ * Language detection event - emitted when audio language is detected
+ */
+export interface TranscriptionLanguageEvent {
+    type: "transcription.language";
+    audioLanguage: string;
+}
+/**
+ * Segment event - emitted for timestamped segments
+ * NOTE: WebSocket realtime API does NOT support this - included for completeness
+ */
+export interface TranscriptionSegmentEvent {
+    type: "transcription.segment";
+    start?: number;
+    end?: number;
+    text: string;
+    speakerId?: string;
+}
+/**
+ * Transcription done event - emitted when transcription completes
+ * Contains the complete transcript
+ */
+export interface TranscriptionDoneEvent {
+    type: "transcription.done";
+    text: string;
+    language?: string;
+}
+/**
+ * Error event - emitted when an error occurs
+ */
+export interface ErrorEvent {
+    type: "error";
+    error: {
+        message: string | unknown;
+    };
+}
+/**
+ * Realtime transcriber interface
+ */
+export interface RealtimeTranscriber {
+    /**
+     * Transcribe audio stream and yield events as they arrive
+     *
+     * @param audioStream - AsyncIterable of audio chunks (Uint8Array)
+     * @param options - Optional transcription options
+     * @returns AsyncIterable of transcription events
+     *
+     * @example
+     * ```typescript
+     * const transcriber = createRealtimeTranscriber({ apiKey: 'xxx' })
+     *
+     * for await (const event of transcriber.transcribe(audioStream)) {
+     *   if (event.type === 'transcription.text.delta') {
+     *     console.log(event.text)
+     *   } else if (event.type === 'transcription.done') {
+     *     console.log('Complete:', event.text)
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    transcribe(audioStream: AsyncIterable<Uint8Array>, options?: TranscribeOptions): AsyncIterable<RealtimeEvent>;
+}
+/**
+ * Create a realtime transcriber instance
+ *
+ * @param config - Configuration including API key and optional model/baseUrl
+ * @returns RealtimeTranscriber instance
+ *
+ * @example
+ * ```typescript
+ * const transcriber = createRealtimeTranscriber({
+ *   apiKey: process.env.MISTRAL_API_KEY,
+ *   model: 'voxtral-mini-transcribe-realtime-2602', // optional
+ *   baseUrl: 'wss://api.mistral.ai', // optional
+ * })
+ * ```
+ */
+export declare function createRealtimeTranscriber(config: RealtimeConfig): RealtimeTranscriber;
+/**
+ * Result from audio capture - includes stream and stop function
+ */
+export interface AudioCaptureResult {
+    /** AsyncGenerator yielding audio chunks */
+    stream: AsyncGenerator<Uint8Array, void, unknown>;
+    /** Function to stop audio capture */
+    stop: () => void;
+}
+/**
+ * Capture audio from microphone using SoX `rec` command
+ *
+ * Yields PCM 16-bit signed little-endian mono audio chunks suitable for
+ * realtime transcription.
+ *
+ * **Requirements:**
+ * - SoX audio tools must be installed
+ *   - macOS: `brew install sox`
+ *   - Linux: `sudo apt install sox`
+ *
+ * @param sampleRate - Sample rate in Hz (default: 16000)
+ * @returns Object with audio stream and stop function
+ *
+ * @example
+ * ```typescript
+ * const { stream, stop } = captureAudioFromMicrophone(16000)
+ *
+ * try {
+ *   for await (const event of transcriber.transcribe(stream)) {
+ *     // ... handle events
+ *   }
+ * } finally {
+ *   stop() // Clean up audio capture
+ * }
+ * ```
+ */
+export declare function captureAudioFromMicrophone(sampleRate?: number): AudioCaptureResult;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/utils/transcription/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../../src/utils/transcription/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EACL,aAAa,EAEd,MAAM,qCAAqC,CAAC;AAM7C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,EAAE,aAAa,CAAC;IACxB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,mBAAmB,GACnB,mBAAmB,GACnB,2BAA2B,GAC3B,0BAA0B,GAC1B,yBAAyB,GACzB,sBAAsB,GACtB,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE;QACP,WAAW,EAAE,WAAW,CAAC;KAC1B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,0BAA0B,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;KAC3B,CAAC;CACH;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CACR,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,EACtC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,aAAa,CAAC,aAAa,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,cAAc,GACrB,mBAAmB,CA+BrB;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,MAAM,EAAE,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAClD,qCAAqC;IACrC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,GAAE,MAAc,GACzB,kBAAkB,CAuDpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wovin/tranz",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Audio transcription library with provider support and auto-splitting",
   "author": "gotjoshua @gotjoshua",
@@ -27,6 +27,10 @@
     "./audio": {
       "import": "./dist/audio.min.js",
       "types": "./dist/audio.d.ts"
+    },
+    "./realtime": {
+      "import": "./dist/realtime.min.js",
+      "types": "./dist/realtime.d.ts"
     }
   },
   "files": [
@@ -36,14 +40,20 @@
     "access": "public"
   },
   "dependencies": {
+    "@mistralai/mistralai": "^1.14.0",
     "fluent-ffmpeg": "^2.1.2"
   },
   "devDependencies": {
     "@types/fluent-ffmpeg": "^2.1.21",
     "@types/node": "^24.10.1",
+    "@types/ws": "^8.5.13",
+    "@types/yargs": "^17.0.33",
     "concurrently": "^8.2.2",
     "tsup": "^8.5.0",
+    "tsx": "^4.19.2",
     "typescript": "^5.9.3",
+    "ws": "^8.18.0",
+    "yargs": "^17.7.2",
     "tsupconfig": "^0.0.0"
   },
   "keywords": [
@@ -60,6 +70,8 @@
     "dev": "concurrently \"pnpm dev:code\" \"pnpm dev:types\"",
     "dev:code": "tsup --watch",
     "dev:types": "tsc --emitDeclarationOnly --declaration --watch",
-    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist"
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "test:realtime": "tsx test/realtime-transcription.ts",
+    "test:realtime-api": "tsx test/realtime-api-test.ts"
   }
 }