@wovin/tranz 0.1.36 → 0.2.0

package/src/utils/audio/merge-results.ts

@@ -0,0 +1,198 @@
+/**
+ * Utilities for merging transcription results from split audio segments
+ */
+
+import type { TranscriptionResult, TranscriptSegment } from '../transcription/providers.ts'
+import type { AudioSegment } from './split.ts'
+
+/**
+ * Word-level data with timing information
+ */
+export interface WordData {
+  word: string
+  start: number
+  end: number
+  confidence?: number
+  speaker?: string | number
+}
+
+/**
+ * Metadata describing one audio chunk in an auto-split + merge run.
+ */
+export interface AudioChunk {
+  index: number
+  startSec: number
+  endSec: number
+  text: string
+}
+
+/**
+ * Merged transcription result with chunk-level metadata.
+ */
+export interface MergedTranscriptionResult extends TranscriptionResult {
+  /** Audio chunks that were transcribed independently and merged. Absent when no split happened. */
+  audioChunks?: AudioChunk[]
+}
+
+/**
+ * Prefix a per-chunk diarization label so values from different chunks don't collide.
+ * Chunk-scoped labels (Mistral's `speaker_1`, Deepgram's `0`) are NOT comparable across
+ * chunks — `chunk0/speaker_1` and `chunk1/speaker_1` are almost always different humans.
+ */
+function prefixChunkLabel(chunkIndex: number, value: string | number | undefined): string | number | undefined {
+  if (value === undefined) return undefined
+  return `chunk${chunkIndex}/${String(value)}`
+}
+
+/**
+ * Merge multiple transcription results from audio segments into one
+ * Adjusts word timestamps to be relative to the original audio
+ *
+ * @param results - Array of transcription results from each segment
+ * @param segments - Array of audio segment metadata
+ * @returns Merged transcription result
+ */
+export function mergeTranscriptionResults(
+  results: TranscriptionResult[],
+  segments: AudioSegment[]
+): MergedTranscriptionResult {
+  if (results.length === 0) {
+    return {
+      text: '',
+      error: 'No results to merge',
+    }
+  }
+
+  if (results.length === 1) {
+    // Single result, no merging needed — preserve native diarization types verbatim.
+    return results[0]
+  }
+
+  // Check for errors in any segment
+  const errors = results
+    .map((r, i) => (r.error ? `Segment ${i}: ${r.error}` : null))
+    .filter(Boolean)
+
+  if (errors.length > 0) {
+    return {
+      text: '',
+      error: `Errors in segments: ${errors.join('; ')}`,
+    }
+  }
+
+  // Merge text with segment markers (double newline between segments)
+  const mergedText = results.map((r) => r.text.trim()).join('\n\n')
+
+  // Merge and adjust word timestamps. Words use seconds (legacy WordData shape).
+  const mergedWords: WordData[] = []
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i]
+    const segment = segments[i]
+    const words = result.words || result.rawResponse?.words || []
+
+    for (const word of words) {
+      mergedWords.push({
+        word: word.word || word.text,
+        start: (word.start || 0) + segment.startSec,
+        end: (word.end || 0) + segment.startSec,
+        confidence: word.confidence,
+        speaker: prefixChunkLabel(i, word.speaker) as string | number | undefined,
+      })
+    }
+  }
+
+  // Merge transcription segments. These use integer ms (TranscriptSegment shape).
+  const mergedSegments: TranscriptSegment[] = []
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i]
+    const chunkOffsetMs = Math.round(segments[i].startSec * 1000)
+    if (!result.segments) continue
+    for (const seg of result.segments) {
+      mergedSegments.push({
+        startMs: seg.startMs + chunkOffsetMs,
+        endMs: seg.endMs + chunkOffsetMs,
+        text: seg.text,
+        ...(seg.diarization !== undefined
+          ? { diarization: prefixChunkLabel(i, seg.diarization) as string | number }
+          : {}),
+      })
+    }
+  }
+
+  // Calculate total duration
+  const totalDuration = segments.reduce((sum, seg) => sum + seg.durationSec, 0)
+
+  // Per-chunk metadata
+  const audioChunks: AudioChunk[] = results.map((r, i) => ({
+    index: i,
+    startSec: segments[i].startSec,
+    endSec: segments[i].endSec,
+    text: r.text.trim(),
+  }))
+
+  // Merge raw responses
+  const mergedRawResponse = {
+    merged: true,
+    chunkCount: results.length,
+    chunks: results.map((r, i) => ({
+      index: i,
+      startSec: segments[i].startSec,
+      rawResponse: r.rawResponse,
+    })),
+  }
+
+  // Take language and model from first result
+  const firstResult = results[0]
+
+  return {
+    text: mergedText,
+    duration: totalDuration,
+    language: firstResult.language,
+    model: firstResult.model,
+    rawResponse: mergedRawResponse,
+    audioChunks,
+    ...(mergedWords.length > 0 ? { words: mergedWords } : {}),
+    ...(mergedSegments.length > 0 ? { segments: mergedSegments } : {}),
+  }
+}
+
+/**
+ * Format merged results with optional segment markers in the text
+ *
+ * @param result - Merged transcription result
+ * @param includeMarkers - Whether to include [Chunk N] markers
+ * @returns Formatted text
+ */
+export function formatMergedText(
+  result: MergedTranscriptionResult,
+  includeMarkers: boolean = false
+): string {
+  if (!result.audioChunks || result.audioChunks.length <= 1) {
+    return result.text
+  }
+
+  if (!includeMarkers) {
+    return result.text
+  }
+
+  return result.audioChunks
+    .map((chunk, i) => {
+      const timeStr = formatTimestamp(chunk.startSec)
+      return `[Chunk ${i + 1} @ ${timeStr}]\n${chunk.text}`
+    })
+    .join('\n\n')
+}
+
+/**
+ * Format seconds as HH:MM:SS or MM:SS
+ */
+function formatTimestamp(seconds: number): string {
+  const hours = Math.floor(seconds / 3600)
+  const minutes = Math.floor((seconds % 3600) / 60)
+  const secs = Math.floor(seconds % 60)
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`
+  }
+  return `${minutes}:${secs.toString().padStart(2, '0')}`
+}

package/src/utils/audio/split.ts

@@ -0,0 +1,504 @@
+/**
+ * Audio splitting utilities for tranz-cli
+ * Provides silence detection and optimal split point calculation
+ */
+
+import { execa } from 'execa'
+import * as fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+/**
+ * Configuration for audio splitting
+ */
+export interface SplitConfig {
+  /** Maximum segment duration in seconds (default: 600 = 10min) */
+  maxDurationSec: number
+  /** Minimum silence duration to consider for split (default: 1.0s) */
+  minSilenceDurSec: number
+  /** FFmpeg silence threshold (default: '-35dB') */
+  silenceThreshold: string
+  /** Prefer longer silences for splits (default: true) */
+  preferLongerSilence: boolean
+  /** Buffer to leave at silence edges (default: 0.2s) */
+  silenceBuffer: number
+}
+
+/**
+ * A detected silence region in the audio
+ */
+export interface SilenceRegion {
+  startSec: number
+  endSec: number
+  durationSec: number
+}
+
+/**
+ * A calculated split point
+ */
+export interface SplitPoint {
+  /** Time in seconds where to split (middle of silence) */
+  timeSec: number
+  /** Duration of the silence at this split point */
+  silenceDuration: number
+}
+
+/**
+ * An audio segment after splitting
+ */
+export interface AudioSegment {
+  index: number
+  startSec: number
+  endSec: number
+  durationSec: number
+  outputPath: string
+}
+
+/**
+ * Default split configuration
+ */
+export const DEFAULT_SPLIT_CONFIG: SplitConfig = {
+  maxDurationSec: 600, // 10 minutes
+  minSilenceDurSec: 1.0,
+  silenceThreshold: '-35dB',
+  preferLongerSilence: true,
+  silenceBuffer: 0.2,
+}
+
+/**
+ * Execute ffprobe and return metadata
+ * Uses -show_format and -show_streams to get duration from either source
+ */
+async function execFFprobe(audioPath: string): Promise<{
+  format?: { duration?: string | number }
+  streams?: Array<{ duration?: string | number }>
+}> {
+  try {
+    const { stdout } = await execa('ffprobe', [
+      '-v', 'error',
+      '-print_format', 'json',
+      '-show_format',
+      '-show_streams',
+      audioPath
+    ])
+    return JSON.parse(stdout)
+  } catch (err) {
+    throw new Error(`Failed to probe audio: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+/**
+ * Extract audio segment using ffmpeg
+ */
+async function extractAudioSegment(
+  inputPath: string,
+  outputPath: string,
+  startSec: number,
+  durationSec: number
+): Promise<void> {
+  try {
+    await execa('ffmpeg', [
+      '-ss', startSec.toString(),
+      '-t', durationSec.toString(),
+      '-i', inputPath,
+      '-ar', '16000',        // 16kHz sample rate (Whisper-compatible)
+      '-ac', '1',            // mono
+      '-c:a', 'pcm_s16le',   // 16-bit PCM codec
+      '-y',                  // overwrite output
+      outputPath
+    ])
+  } catch (err) {
+    throw new Error(`Failed to extract segment: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+/**
+ * Get duration using ffmpeg decode (slower but more reliable)
+ * Used as fallback when ffprobe can't determine duration
+ */
+async function getDurationViaFfmpeg(audioPath: string): Promise<number | undefined> {
+  try {
+    // Use ffmpeg to decode to null and capture the duration from stderr
+    const { stderr } = await execa('ffmpeg', [
+      '-i', audioPath,
+      '-f', 'null',
+      '-'
+    ], { reject: false })
+
+    // Parse duration from ffmpeg output: "Duration: HH:MM:SS.ss" or "time=HH:MM:SS.ss"
+    const durationMatch = stderr.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/)
+    if (durationMatch) {
+      const hours = parseFloat(durationMatch[1])
+      const minutes = parseFloat(durationMatch[2])
+      const seconds = parseFloat(durationMatch[3])
+      return hours * 3600 + minutes * 60 + seconds
+    }
+
+    // Try parsing from final time= output
+    const timeMatches = [...stderr.matchAll(/time=(\d+):(\d+):(\d+(?:\.\d+)?)/g)]
+    if (timeMatches.length > 0) {
+      const lastMatch = timeMatches[timeMatches.length - 1]
+      const hours = parseFloat(lastMatch[1])
+      const minutes = parseFloat(lastMatch[2])
+      const seconds = parseFloat(lastMatch[3])
+      return hours * 3600 + minutes * 60 + seconds
+    }
+  } catch {
+    // Ignore errors, return undefined
+  }
+  return undefined
+}
+
+/**
+ * Get the duration of an audio file in seconds
+ * Tries format.duration first, then falls back to stream duration,
+ * and finally uses ffmpeg decode as last resort
+ */
+export async function getAudioDuration(audioPath: string): Promise<number> {
+  const metadata = await execFFprobe(audioPath)
+
+  // Try format duration first (most reliable for container formats)
+  if (metadata.format?.duration) {
+    const duration = parseFloat(String(metadata.format.duration))
+    if (!isNaN(duration) && duration > 0) {
+      return duration
+    }
+  }
+
+  // Fall back to stream duration (works for raw audio formats)
+  if (metadata.streams?.length) {
+    for (const stream of metadata.streams) {
+      if (stream.duration) {
+        const duration = parseFloat(String(stream.duration))
+        if (!isNaN(duration) && duration > 0) {
+          return duration
+        }
+      }
+    }
+  }
+
+  // Last resort: decode with ffmpeg to get duration
+  const ffmpegDuration = await getDurationViaFfmpeg(audioPath)
+  if (ffmpegDuration !== undefined && ffmpegDuration > 0) {
+    return ffmpegDuration
+  }
+
+  // Provide helpful debug info
+  const hasFormat = !!metadata.format
+  const hasStreams = !!metadata.streams?.length
+  throw new Error(
+    `Could not determine audio duration (format: ${hasFormat}, streams: ${hasStreams}). ` +
+    `File may be corrupted or in an unsupported format.`
+  )
+}
+
+/**
+ * Detect silence regions in an audio file using FFmpeg
+ * Uses spawn directly for better compatibility
+ */
+export async function detectSilenceRegions(
+  audioPath: string,
+  config: Partial<SplitConfig> = {}
+): Promise<SilenceRegion[]> {
+  const { minSilenceDurSec, silenceThreshold } = { ...DEFAULT_SPLIT_CONFIG, ...config }
+
+  return new Promise((resolve, reject) => {
+    const silenceRegions: SilenceRegion[] = []
+
+    // Use spawn directly for better ffmpeg compatibility
+    const args = [
+      '-i', audioPath,
+      '-af', `silencedetect=n=${silenceThreshold}:d=${minSilenceDurSec}`,
+      '-f', 'wav',
+      '-ac', '1',
+      '-ar', '8000',
+      'pipe:1'
+    ]
+
+    const proc = spawn('ffmpeg', args)
+
+    // Discard stdout (audio data)
+    proc.stdout.on('data', () => {})
+
+    // Parse stderr for silence info
+    proc.stderr.on('data', (data: Buffer) => {
+      const lines = data.toString().split('\n')
+      for (const line of lines) {
+        if (line.includes('silence_end:')) {
+          const match = line.match(/silence_end:\s*([\d.]+)\s*\|\s*silence_duration:\s*([\d.]+)/)
+          if (match) {
+            const endSec = parseFloat(match[1])
+            const durationSec = parseFloat(match[2])
+            if (!isNaN(endSec) && !isNaN(durationSec)) {
+              silenceRegions.push({
+                startSec: endSec - durationSec,
+                endSec,
+                durationSec,
+              })
+            }
+          }
+        }
+      }
+    })
+
+    proc.on('close', (code: number) => {
+      if (code === 0 || silenceRegions.length > 0) {
+        resolve(silenceRegions)
+      } else {
+        reject(new Error(`FFmpeg exited with code ${code}`))
+      }
+    })
+
+    proc.on('error', (err: Error) => {
+      reject(new Error(`Silence detection failed: ${err.message}`))
+    })
+  })
+}
+
+/**
+ * Find optimal split points in audio based on silence regions
+ * Prefers splitting at longer silences when possible
+ *
+ * @param silenceRegions - Detected silence regions
+ * @param totalDuration - Total audio duration in seconds
+ * @param config - Split configuration
+ * @returns Array of optimal split points
+ */
+export function findOptimalSplitPoints(
+  silenceRegions: SilenceRegion[],
+  totalDuration: number,
+  config: Partial<SplitConfig> = {}
+): SplitPoint[] {
+  const { maxDurationSec, preferLongerSilence, silenceBuffer } = {
+    ...DEFAULT_SPLIT_CONFIG,
+    ...config,
+  }
+
+  // No splits needed if audio is short enough
+  if (totalDuration <= maxDurationSec) {
+    return []
+  }
+
+  // Calculate how many segments we need
+  const numSegments = Math.ceil(totalDuration / maxDurationSec)
+  const idealSegmentDuration = totalDuration / numSegments
+
+  const splitPoints: SplitPoint[] = []
+
+  // Find split points for each required split (numSegments - 1 splits)
+  for (let i = 1; i < numSegments; i++) {
+    const idealSplitTime = idealSegmentDuration * i
+
+    // Define search window: ±30% of segment duration around ideal point
+    const windowSize = idealSegmentDuration * 0.3
+    const windowStart = idealSplitTime - windowSize
+    const windowEnd = idealSplitTime + windowSize
+
+    // Find all silences within the window
+    const candidateSilences = silenceRegions.filter((silence) => {
+      const silenceMid = (silence.startSec + silence.endSec) / 2
+      return silenceMid >= windowStart && silenceMid <= windowEnd
+    })
+
+    let bestSplitPoint: SplitPoint
+
+    if (candidateSilences.length > 0) {
+      // Score each silence and pick the best
+      let bestScore = -Infinity
+      let bestSilence = candidateSilences[0]
+
+      for (const silence of candidateSilences) {
+        const silenceMid = (silence.startSec + silence.endSec) / 2
+        const proximityScore = 1 - Math.abs(silenceMid - idealSplitTime) / windowSize
+
+        // Score formula: prefer longer silences and closer to ideal point
+        const score = preferLongerSilence
+          ? silence.durationSec * proximityScore
+          : proximityScore
+
+        if (score > bestScore) {
+          bestScore = score
+          bestSilence = silence
+        }
+      }
+
+      // Split at the middle of the best silence
+      bestSplitPoint = {
+        timeSec: (bestSilence.startSec + bestSilence.endSec) / 2,
+        silenceDuration: bestSilence.durationSec,
+      }
+    } else {
+      // No silence found in window - split at ideal point
+      // This is a fallback; may split mid-speech
+      bestSplitPoint = {
+        timeSec: idealSplitTime,
+        silenceDuration: 0,
+      }
+    }
+
+    splitPoints.push(bestSplitPoint)
+  }
+
+  return splitPoints.sort((a, b) => a.timeSec - b.timeSec)
+}
+
+/**
+ * Split audio file at specified points using FFmpeg
+ *
+ * @param audioPath - Path to source audio file
+ * @param splitPoints - Where to split the audio
+ * @param totalDuration - Total duration of source audio
+ * @param outputDir - Directory to write segments
+ * @param baseName - Base name for output files
+ * @returns Array of created audio segments
+ */
+export async function splitAudioAtPoints(
+  audioPath: string,
+  splitPoints: SplitPoint[],
+  totalDuration: number,
+  outputDir: string,
+  baseName: string
+): Promise<AudioSegment[]> {
+  // Ensure output directory exists
+  fs.mkdirSync(outputDir, { recursive: true })
+
+  const segments: AudioSegment[] = []
+
+  // Build segment boundaries
+  const boundaries = [0, ...splitPoints.map((sp) => sp.timeSec), totalDuration]
+
+  const splitPromises: Promise<void>[] = []
+
+  for (let i = 0; i < boundaries.length - 1; i++) {
+    const startSec = boundaries[i]
+    const endSec = boundaries[i + 1]
+    const durationSec = endSec - startSec
+    const outputPath = path.join(outputDir, `${baseName}-segment-${i.toString().padStart(3, '0')}.wav`)
+
+    const segment: AudioSegment = {
+      index: i,
+      startSec,
+      endSec,
+      durationSec,
+      outputPath,
+    }
+    segments.push(segment)
+
+    // Create promise for this segment's extraction
+    const extractPromise = extractAudioSegment(
+      audioPath,
+      outputPath,
+      startSec,
+      durationSec
+    ).catch(err => {
+      throw new Error(`Failed to extract segment ${i}: ${err instanceof Error ? err.message : String(err)}`)
+    })
+
+    splitPromises.push(extractPromise)
+  }
+
+  // Wait for all segments to be extracted
+  await Promise.all(splitPromises)
+
+  return segments
+}
+
+/**
+ * Auto-split an audio file if it exceeds the maximum duration
+ * Returns the original file path if no split is needed
+ *
+ * @param audioPath - Path to source audio file
+ * @param outputDir - Directory for split segments
+ * @param config - Split configuration
+ * @returns Array of audio segment paths (single element if no split needed)
+ */
+export async function autoSplitAudio(
+  audioPath: string,
+  outputDir: string,
+  config: Partial<SplitConfig> = {}
+): Promise<AudioSegment[]> {
+  const mergedConfig = { ...DEFAULT_SPLIT_CONFIG, ...config }
+
+  // Get audio duration
+  const totalDuration = await getAudioDuration(audioPath)
+
+  // Check if splitting is needed
+  if (totalDuration <= mergedConfig.maxDurationSec) {
+    // No split needed - return original as single segment
+    return [
+      {
+        index: 0,
+        startSec: 0,
+        endSec: totalDuration,
+        durationSec: totalDuration,
+        outputPath: audioPath,
+      },
+    ]
+  }
+
+  // Detect silence regions for optimal split points
+  const silenceRegions = await detectSilenceRegions(audioPath, mergedConfig)
+
+  // Find optimal split points
+  const splitPoints = findOptimalSplitPoints(silenceRegions, totalDuration, mergedConfig)
+
+  // Extract base name from audio path
+  const baseName = path.basename(audioPath, path.extname(audioPath))
+
+  // Split the audio
+  const segments = await splitAudioAtPoints(
+    audioPath,
+    splitPoints,
+    totalDuration,
+    outputDir,
+    baseName
+  )
+
+  return segments
+}
+
+/**
+ * Information about split points for logging/debugging
+ */
+export interface SplitAnalysis {
+  totalDuration: number
+  numSegments: number
+  splitPoints: SplitPoint[]
+  silenceRegions: SilenceRegion[]
+  needsSplit: boolean
+}
+
+/**
+ * Analyze audio file and return split information without actually splitting
+ * Useful for preview/dry-run functionality
+ */
+export async function analyzeSplitPoints(
+  audioPath: string,
+  config: Partial<SplitConfig> = {}
+): Promise<SplitAnalysis> {
+  const mergedConfig = { ...DEFAULT_SPLIT_CONFIG, ...config }
+
+  const totalDuration = await getAudioDuration(audioPath)
+  const needsSplit = totalDuration > mergedConfig.maxDurationSec
+
+  if (!needsSplit) {
+    return {
+      totalDuration,
+      numSegments: 1,
+      splitPoints: [],
+      silenceRegions: [],
+      needsSplit: false,
+    }
+  }
+
+  const silenceRegions = await detectSilenceRegions(audioPath, mergedConfig)
+  const splitPoints = findOptimalSplitPoints(silenceRegions, totalDuration, mergedConfig)
+
+  return {
+    totalDuration,
+    numSegments: splitPoints.length + 1,
+    splitPoints,
+    silenceRegions,
+    needsSplit: true,
+  }
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,16 @@
+import path from 'node:path'
+
+export const getExt = (filePath: string) => {
+  return getFileInfo(filePath).ext
+}
+export const getName = (filePath: string) => {
+  return getFileInfo(filePath).name
+}
+export const getNameWithExt = (filePath: string) => {
+  const { name, ext } = getFileInfo(filePath)
+  return `${name}.${ext}`
+}
+export const getFileInfo = (filePath: string) => {
+  const normed = path.normalize(filePath)
+  return path.parse(normed)
+}