@wovin/tranz 0.1.36 → 0.2.0

package/src/utils/transcription/runtime.ts

@@ -0,0 +1,40 @@
+/**
+ * Runtime environment detection for WebSocket implementations
+ *
+ * Provides environment-aware WebSocket constructor selection:
+ * - Browser/Deno: Uses global WebSocket API
+ * - Node.js: Dynamically imports 'ws' package
+ */
+
+/**
+ * Get the appropriate WebSocket implementation for the current runtime
+ *
+ * @returns WebSocket constructor (browser WebSocket or ws package)
+ * @throws Error if WebSocket is not available in any form
+ */
+export async function getWebSocketImpl(): Promise<any> {
+  // Check if we're in a browser/Deno environment (has DOM or navigator)
+  const isBrowser = typeof globalThis !== "undefined" &&
+    (typeof globalThis.document !== "undefined" || typeof globalThis.navigator !== "undefined");
+
+  // Browser/Deno - use global WebSocket
+  if (isBrowser && typeof globalThis.WebSocket !== "undefined") {
+    return globalThis.WebSocket;
+  }
+
+  // Node.js - dynamically import ws
+  if (!isBrowser) {
+    try {
+      const WS = await import("ws");
+      return WS.default || WS;
+    } catch (err) {
+      throw new Error(
+        "WebSocket not available. In Node.js, install 'ws' package: npm install ws"
+      );
+    }
+  }
+
+  throw new Error(
+    "WebSocket not available in this environment"
+  );
+}

package/src/utils/transcription/transcribe.ts

@@ -0,0 +1,366 @@
+/**
+ * Simple high-level transcription API with good defaults
+ */
+
+import * as fs from 'node:fs'
+import * as https from 'node:https'
+import * as http from 'node:http'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { MistralProvider, VOXTRAL_LIMITS, type TranscriptionResult } from './providers.ts'
+import { autoSplitAudio, getAudioDuration, type AudioSegment } from '../audio/split.ts'
+import { mergeTranscriptionResults, type MergedTranscriptionResult } from '../audio/merge-results.ts'
+
+/** Logger interface for transcription progress */
+export interface TranscribeLogger {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  debug: (msg: string) => void
+}
+
+const defaultLogger: TranscribeLogger = {
+  info: (msg) => console.log(`[tranz] ${msg}`),
+  warn: (msg) => console.warn(`[tranz] ${msg}`),
+  debug: () => {}, // silent by default
+}
+
+export interface TranscribeOptions {
+  /** Path to audio file */
+  audioPath?: string
+  /** Audio buffer to transcribe */
+  audioBuffer?: Buffer
+  /** MIME type for audioBuffer (auto-detected if not provided) */
+  mimeType?: string
+  /** URL to audio file (e.g., IPFS gateway URL) */
+  audioUrl?: string
+  /** Known duration in seconds (skips duration detection for URL input) */
+  duration?: number
+  /** Language code (e.g. 'en', 'fr') - note: disables word timestamps for Mistral */
+  language?: string
+  /** Model to use (default: voxtral-mini-latest) */
+  model?: string
+  /** Enable speaker diarization (default: true) */
+  diarize?: boolean
+  /** Timestamp granularity: 'word' | 'segment' (default: 'segment' when diarize=true, disabled if language set) */
+  timestamps?: 'word' | 'segment'
+  /**
+   * Context biasing terms — up to `VOXTRAL_LIMITS.maxContextBiasingTerms` (100)
+   * custom-vocabulary entries passed to Voxtral as `context_bias[]`. Mistral only.
+   */
+  contextBias?: string[]
+  /** Auto-split long audio (default: true). For URLs, detects duration first. */
+  autoSplit?: boolean
+  /** Output directory for split segments (default: system temp) */
+  splitOutputDir?: string
+  /** Custom logger (default: console) */
+  logger?: TranscribeLogger
+  /** Enable verbose/debug logging */
+  verbose?: boolean
+}
+
+export interface MistralTranscriberConfig {
+  /** Mistral API key */
+  apiKey: string
+  /** Default model (default: voxtral-mini-latest) */
+  model?: string
+}
+
+/** Map of MIME types to file extensions */
+const MIME_TO_EXT: Record<string, string> = {
+  'audio/mpeg': '.mp3',
+  'audio/mp3': '.mp3',
+  'audio/wav': '.wav',
+  'audio/x-wav': '.wav',
+  'audio/ogg': '.ogg',
+  'audio/flac': '.flac',
+  'audio/x-flac': '.flac',
+  'audio/mp4': '.m4a',
+  'audio/m4a': '.m4a',
+  'audio/aac': '.aac',
+  'audio/webm': '.webm',
+  'audio/opus': '.opus',
+}
+
+/**
+ * Get file extension from Content-Type header or URL
+ */
+function getExtFromContentType(contentType: string | undefined, url: string): string {
+  // Try Content-Type first
+  if (contentType) {
+    const mimeType = contentType.split(';')[0].trim().toLowerCase()
+    if (MIME_TO_EXT[mimeType]) {
+      return MIME_TO_EXT[mimeType]
+    }
+  }
+  // Fall back to URL path extension
+  try {
+    const urlPath = new URL(url).pathname
+    const ext = path.extname(urlPath).toLowerCase()
+    if (ext && ['.mp3', '.wav', '.ogg', '.flac', '.m4a', '.aac', '.webm', '.opus'].includes(ext)) {
+      return ext
+    }
+  } catch {}
+  // Default to .audio (ffprobe will probe the format)
+  return '.audio'
+}
+
+/**
+ * Download a URL to a temporary file
+ */
+async function downloadToTempFile(url: string, outputDir: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith('https') ? https : http
+    protocol.get(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302) {
+        // Handle redirect
+        const redirectUrl = response.headers.location
+        if (redirectUrl) {
+          downloadToTempFile(redirectUrl, outputDir).then(resolve).catch(reject)
+          return
+        }
+      }
+      if (response.statusCode !== 200) {
+        reject(new Error(`Failed to download: HTTP ${response.statusCode}`))
+        return
+      }
+
+      // Determine file extension from Content-Type or URL
+      const ext = getExtFromContentType(response.headers['content-type'], url)
+      const tempPath = path.join(outputDir, `download-${Date.now()}${ext}`)
+      const file = fs.createWriteStream(tempPath)
+
+      response.pipe(file)
+      file.on('finish', () => {
+        file.close()
+        resolve(tempPath)
+      })
+      file.on('error', (err) => {
+        fs.unlink(tempPath, () => {})
+        reject(err)
+      })
+    }).on('error', (err) => {
+      reject(err)
+    })
+  })
+}
+
+/**
+ * Try to get duration from URL using ffprobe (uses HTTP range requests)
+ * Returns undefined if detection fails
+ */
+async function tryGetUrlDuration(url: string): Promise<number | undefined> {
+  try {
+    return await getAudioDuration(url)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Simple Mistral transcriber with auto-splitting and good defaults
+ *
+ * @example
+ * ```ts
+ * const transcriber = createMistralTranscriber({ apiKey: process.env.MISTRAL_API_KEY })
+ *
+ * // From file (supports auto-split for long audio)
+ * const result = await transcriber.transcribe({ audioPath: './interview.mp3' })
+ *
+ * // From URL (auto-detects if splitting needed, downloads only if necessary)
+ * const result = await transcriber.transcribe({ audioUrl: 'https://gateway.ipfs.io/ipfs/Qm...' })
+ *
+ * // From URL with known duration (skips detection)
+ * const result = await transcriber.transcribe({ audioUrl: '...', duration: 120 })
+ *
+ * // From buffer
+ * const result = await transcriber.transcribe({ audioBuffer: buffer, mimeType: 'audio/mpeg' })
+ * ```
+ */
+/** Transcriber interface returned by createMistralTranscriber */
+export interface MistralTranscriber {
+  transcribe(options: TranscribeOptions): Promise<MergedTranscriptionResult>
+}
+
+export function createMistralTranscriber(config: MistralTranscriberConfig): MistralTranscriber {
+  const provider = new MistralProvider()
+  const defaultModel = config.model || 'voxtral-mini-latest'
+
+  return {
+    /**
+     * Transcribe audio with smart auto-splitting
+     * - For files: checks duration and splits if needed
+     * - For URLs: probes duration via HTTP range request, downloads only if splitting needed
+     * - For buffers: transcribes directly (no splitting)
+     */
+    async transcribe(options: TranscribeOptions): Promise<MergedTranscriptionResult> {
+      const {
+        audioPath,
+        audioBuffer,
+        mimeType,
+        audioUrl,
+        duration: knownDuration,
+        language,
+        model = defaultModel,
+        contextBias,
+        diarize = true,
+        timestamps = language ? undefined : 'segment',
+        autoSplit,
+        splitOutputDir,
+        logger: customLogger,
+        verbose,
+      } = options
+
+      const log = customLogger || defaultLogger
+      if (verbose) log.debug = log.info // promote debug to info when verbose
+
+      const maxDuration = VOXTRAL_LIMITS.maxAudioDurationSec
+
+      // Buffer input - no auto-split support, transcribe directly
+      if (audioBuffer) {
+        log.info(`Transcribing from buffer (${(audioBuffer.length / 1024 / 1024).toFixed(2)} MB)`)
+        const result = await provider.transcribe({
+          audioBuffer,
+          mimeType,
+          apiKey: config.apiKey,
+          model,
+          language,
+          diarize,
+          timestampGranularity: timestamps,
+          contextBias,
+        })
+        return result
+      }
+
+      // URL input - smart handling
+      if (audioUrl) {
+        // If autoSplit explicitly disabled, use URL directly
+        if (autoSplit === false) {
+          log.info(`Transcribing URL directly (autoSplit disabled)`)
+          const result = await provider.transcribe({
+            audioUrl,
+            apiKey: config.apiKey,
+            model,
+            language,
+            diarize,
+            timestampGranularity: timestamps,
+            contextBias,
+          })
+          return result
+        }
+
+        // Check duration (use known or detect)
+        let duration = knownDuration
+        if (duration === undefined) {
+          log.info(`Probing URL duration via ffprobe...`)
+          duration = await tryGetUrlDuration(audioUrl)
+          if (duration !== undefined) {
+            log.info(`Duration detected: ${duration.toFixed(1)}s`)
+          } else {
+            log.warn(`Duration detection failed, will download to check`)
+          }
+        } else {
+          log.debug(`Using provided duration: ${duration.toFixed(1)}s`)
+        }
+
+        // If duration known and short enough, use URL directly
+        if (duration !== undefined && duration <= maxDuration) {
+          log.info(`Duration ${duration.toFixed(1)}s <= ${maxDuration}s, using URL directly`)
+          const result = await provider.transcribe({
+            audioUrl,
+            apiKey: config.apiKey,
+            model,
+            language,
+            diarize,
+            timestampGranularity: timestamps,
+            contextBias,
+          })
+          return result
+        }
+
+        // Duration unknown or too long - download and process as file
+        log.info(`Downloading URL to temp file for processing...`)
+        const outDir = splitOutputDir || path.join(os.tmpdir(), `tranz-${Date.now()}`)
+        fs.mkdirSync(outDir, { recursive: true })
+
+        const tempFile = await downloadToTempFile(audioUrl, outDir)
+        log.info(`Downloaded to ${tempFile}`)
+
+        // Recurse with file path
+        const result = await this.transcribe({
+          audioPath: tempFile,
+          language,
+          model,
+          diarize,
+          timestamps,
+          contextBias,
+          autoSplit: true,
+          splitOutputDir: outDir,
+          logger: customLogger,
+          verbose,
+        })
+
+        // Cleanup temp file (segments are in outDir)
+        try { fs.unlinkSync(tempFile) } catch {}
+
+        return result
+      }
+
+      // File path input
+      if (!audioPath) {
+        return { text: '', error: 'No audio input provided (audioPath, audioBuffer, or audioUrl required)' }
+      }
+
+      log.debug(`Processing file: ${audioPath}`)
+      const duration = knownDuration ?? await getAudioDuration(audioPath)
+      log.info(`Audio duration: ${duration.toFixed(1)}s`)
+      const needsSplit = autoSplit !== false && duration > maxDuration
+
+      if (!needsSplit) {
+        log.info(`Transcribing file directly (no split needed)`)
+        const result = await provider.transcribe({
+          audioPath,
+          apiKey: config.apiKey,
+          model,
+          language,
+          diarize,
+          timestampGranularity: timestamps,
+          contextBias,
+        })
+        return result
+      }
+
+      // Auto-split and transcribe segments
+      log.info(`Duration ${duration.toFixed(1)}s > ${maxDuration}s, splitting audio...`)
+      const outDir = splitOutputDir || path.join(os.tmpdir(), `tranz-split-${Date.now()}`)
+      fs.mkdirSync(outDir, { recursive: true })
+
+      const segments = await autoSplitAudio(audioPath, outDir, {
+        maxDurationSec: maxDuration,
+      })
+      log.info(`Split into ${segments.length} segments`)
+
+      // Transcribe each segment
+      const results: TranscriptionResult[] = []
+      for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i]
+        log.info(`Transcribing segment ${i + 1}/${segments.length} (${segment.durationSec.toFixed(1)}s)`)
+        const result = await provider.transcribe({
+          audioPath: segment.outputPath,
+          apiKey: config.apiKey,
+          model,
+          language,
+          diarize,
+          timestampGranularity: timestamps,
+          contextBias,
+        })
+        results.push(result)
+      }
+
+      log.info(`Merging ${segments.length} segments`)
+      return mergeTranscriptionResults(results, segments)
+    },
+  }
+}
+
+/** Alias for simpler import */
+export const transcribe = createMistralTranscriber