@wovin/tranz 0.1.36 → 0.2.0

package/src/utils/transcription/format.ts

@@ -0,0 +1,208 @@
+/**
+ * Format transcript with line breaks based on pauses between words
+ * @param transcript The punctuated transcript text from the API
+ * @param words Array of word objects with timing data
+ * @param shortPauseThreshold Threshold for single line break (default: 1.0s)
+ * @param longPauseThreshold Threshold for paragraph break/double newline (default: 5.0s)
+ */
+export function formatTranscriptWithPauses(
+	transcript: string,
+	words: Array<{ word: string; start: number; end: number; confidence: number }>,
+	shortPauseThreshold = 1.0,
+	longPauseThreshold = 5.0,
+): string {
+	if (!words || words.length === 0) {
+		return transcript
+	}
+
+	// Find pause positions (word indices where we should insert line breaks)
+	const pausePositions: Map<number, 'short' | 'long'> = new Map()
+
+	for (let i = 0; i < words.length - 1; i++) {
+		const word = words[i]
+		const nextWord = words[i + 1]
+		const gap = nextWord.start - word.end
+
+		if (gap >= longPauseThreshold) {
+			pausePositions.set(i, 'long')
+		} else if (gap >= shortPauseThreshold) {
+			pausePositions.set(i, 'short')
+		}
+	}
+
+	// If no pauses found, return original transcript
+	if (pausePositions.size === 0) {
+		return transcript
+	}
+
+	// Split transcript into words, preserving punctuation
+	// This regex splits on spaces but keeps punctuation attached to words
+	const transcriptWords = transcript.split(/\s+/)
+
+	// Build output with line breaks at pause positions
+	const result: string[] = []
+
+	for (let i = 0; i < transcriptWords.length; i++) {
+		result.push(transcriptWords[i])
+
+		// Check if there's a pause after this word
+		const pauseType = pausePositions.get(i)
+		if (pauseType === 'long') {
+			result.push('\n\n')
+		} else if (pauseType === 'short') {
+			result.push('\n')
+		} else if (i < transcriptWords.length - 1) {
+			// No pause, add regular space
+			result.push(' ')
+		}
+	}
+
+	return result.join('')
+}
+
+import type { TranscriptionResult, TranscriptSegment } from './providers.ts'
+import type { MergedTranscriptionResult } from '../audio/merge-results.ts'
+
+export interface FormatMarkdownOptions {
+	/** Silence gap (seconds) that ends a paragraph. Default 1.5. */
+	gapSec?: number
+	/** Include `· Speaker N` in each paragraph header when diarization labels are present. Default true. */
+	speakerLabel?: boolean
+	/** Prepend an `# <source>` title + bulleted metadata block. Default false. */
+	includeHeader?: boolean
+	/** Source filename to use in the `# ` title and `Source:` line (when includeHeader=true). */
+	source?: string
+	/** Total audio duration in seconds — used for `Duration:` line and for picking mm:ss vs h:mm:ss formatting. */
+	durationSec?: number
+}
+
+function formatTime(seconds: number, useHours: boolean): string {
+	const total = Math.max(0, Math.floor(seconds))
+	const h = Math.floor(total / 3600)
+	const m = Math.floor((total % 3600) / 60)
+	const s = total % 60
+	if (useHours) {
+		return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+	}
+	return `${m}:${String(s).padStart(2, '0')}`
+}
+
+function formatDurationHuman(seconds: number): string {
+	const total = Math.max(0, Math.floor(seconds))
+	const h = Math.floor(total / 3600)
+	const m = Math.floor((total % 3600) / 60)
+	const s = total % 60
+	if (h > 0) return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+	return `${m}:${String(s).padStart(2, '0')}`
+}
+
+/**
+ * Format a transcription result as readable Markdown with timestamped paragraphs.
+ *
+ * Groups adjacent segments into paragraphs, starting a new paragraph on either
+ * a silence gap ≥ `gapSec` OR a change in diarization label. Each paragraph is
+ * preceded by `**[mm:ss · Speaker N]**` (or `**[h:mm:ss · Speaker N]**` for
+ * audio ≥ 1h). The speaker suffix is dropped when no diarization labels are
+ * present or all segments share the same label.
+ *
+ * If `segments` is missing/empty, falls back to emitting `result.text` as a
+ * single (un-timestamped) paragraph.
+ */
+export function formatTranscriptAsMarkdown(
+	result: TranscriptionResult | MergedTranscriptionResult,
+	opts: FormatMarkdownOptions = {},
+): string {
+	const gapSec = opts.gapSec ?? 1.5
+	const wantSpeakerLabel = opts.speakerLabel ?? true
+	const includeHeader = opts.includeHeader ?? false
+	const gapMs = gapSec * 1000
+
+	const segments = result.segments ?? []
+	const totalDurationSec =
+		opts.durationSec ??
+		result.duration ??
+		(segments.length > 0 ? segments[segments.length - 1].endMs / 1000 : 0)
+	const useHours = totalDurationSec >= 3600
+
+	const speakerSet = new Set<string | number>()
+	for (const seg of segments) {
+		if (seg.diarization !== undefined && seg.diarization !== null) {
+			speakerSet.add(seg.diarization)
+		}
+	}
+	const hasMultipleSpeakers = speakerSet.size > 1
+	const showSpeakers = wantSpeakerLabel && hasMultipleSpeakers
+
+	let headerBlock = ''
+	if (includeHeader) {
+		const bullets: string[] = []
+		if (opts.source) bullets.push(`- Source: \`${opts.source}\``)
+		if (totalDurationSec > 0) bullets.push(`- Duration: ${formatDurationHuman(totalDurationSec)}`)
+		if (result.model) bullets.push(`- Model: ${result.model}`)
+		if (segments.length > 0) bullets.push(`- Segments: ${segments.length}`)
+		if (speakerSet.size > 0) bullets.push(`- Speakers (diarized): ${speakerSet.size}`)
+
+		const parts: string[] = []
+		if (opts.source) parts.push(`# ${opts.source}`)
+		if (bullets.length > 0) parts.push(bullets.join('\n'))
+		parts.push('## Transcript')
+		headerBlock = parts.join('\n\n')
+	}
+
+	const body: string[] = []
+
+	if (segments.length === 0) {
+		const text = (result.text ?? '').trim()
+		if (text) body.push(text)
+	} else {
+		interface Paragraph {
+			startMs: number
+			lastEndMs: number
+			speaker?: string | number
+			texts: string[]
+		}
+		const paragraphs: Paragraph[] = []
+		let current: Paragraph | undefined
+
+		for (const seg of segments) {
+			const text = (seg.text ?? '').trim()
+			if (!text) continue
+
+			const gap = current ? seg.startMs - current.lastEndMs : Infinity
+			const speakerChanged = current ? current.speaker !== seg.diarization : false
+
+			if (!current || gap >= gapMs || speakerChanged) {
+				current = {
+					startMs: seg.startMs,
+					lastEndMs: seg.endMs,
+					speaker: seg.diarization,
+					texts: [text],
+				}
+				paragraphs.push(current)
+			} else {
+				current.texts.push(text)
+				current.lastEndMs = seg.endMs
+			}
+		}
+
+		for (const p of paragraphs) {
+			const time = formatTime(p.startMs / 1000, useHours)
+			const speakerSuffix =
+				showSpeakers && p.speaker !== undefined && p.speaker !== null
+					? ` · Speaker ${formatSpeakerLabel(p.speaker)}`
+					: ''
+			body.push(`**[${time}${speakerSuffix}]** ${p.texts.join(' ')}`)
+		}
+	}
+
+	const bodyBlock = body.join('\n\n')
+	const out = [headerBlock, bodyBlock].filter((s) => s.length > 0).join('\n\n')
+	return out.trimEnd() + (out.length > 0 ? '\n' : '')
+}
+
+function formatSpeakerLabel(value: string | number): string {
+	const s = String(value)
+	// Mistral emits `speaker_1`, `speaker_2`, … — strip the redundant prefix
+	// so the rendered label reads "Speaker 1" not "Speaker speaker_1".
+	return s.replace(/^speaker[_-]/, '')
+}

package/src/utils/transcription/mime-detection.ts

@@ -0,0 +1,80 @@
+import { Buffer } from 'node:buffer'
+
+/**
+ * Detect audio format from buffer magic bytes
+ *
+ * @param buffer - The audio buffer to analyze
+ * @returns The detected MIME type string ('audio/mpeg', 'audio/ogg', 'audio/wav', 'audio/flac')
+ *
+ * @description
+ * This function analyzes the magic bytes at the beginning of an audio buffer to determine
+ * its format. It handles MP3 files with ID3 tags by skipping over them before checking
+ * for the actual audio frame header.
+ *
+ * Supported formats:
+ * - MP3 (MPEG Audio): FF FB, FF FA, FF F3, FF F2 with optional ID3 tag
+ * - OGG: "OggS" (4F 67 67 53)
+ * - WAV (RIFF): "RIFF" (52 49 46 46)
+ * - FLAC: "fLaC" (66 4C 61 43)
+ *
+ * @example
+ * const buffer = readFileSync('audio.mp3')
+ * const mimeType = detectAudioMimeType(buffer)
+ * console.log(mimeType) // 'audio/mpeg'
+ */
+export function detectAudioMimeType(buffer: Buffer): string {
+	if (buffer.length < 4) return 'audio/ogg'
+
+	let offset = 0
+
+	// Skip ID3 tags (used in MP3 files)
+	if (buffer[0] === 0x49 && buffer[1] === 0x44 && buffer[2] === 0x33) {
+		// ID3v2 header: "ID3" + version (2 bytes) + flags (1 byte) + size (4 bytes synchsafe)
+		if (buffer.length >= 10) {
+			const size = ((buffer[6] & 0x7f) << 21) | ((buffer[7] & 0x7f) << 14) | ((buffer[8] & 0x7f) << 7) |
+				(buffer[9] & 0x7f)
+			offset = 10 + size
+			// Make sure we don't skip past the buffer
+			if (offset >= buffer.length) offset = 0
+		}
+	}
+
+	// Now check the actual audio format at the correct offset
+	if (buffer.length - offset >= 4) {
+		// MP3: FF FB or FF FA (MPEG Audio)
+		if (
+			(buffer[offset] === 0xff && (buffer[offset + 1] === 0xfb || buffer[offset + 1] === 0xfa)) ||
+			(buffer[offset] === 0xff && buffer[offset + 1] === 0xf3) ||
+			(buffer[offset] === 0xff && buffer[offset + 1] === 0xf2)
+		) {
+			return 'audio/mpeg'
+		}
+
+		// OGG: OggS
+		if (
+			buffer[offset] === 0x4f && buffer[offset + 1] === 0x67 && buffer[offset + 2] === 0x67 &&
+			buffer[offset + 3] === 0x53
+		) {
+			return 'audio/ogg'
+		}
+
+		// WAV: RIFF
+		if (
+			buffer[offset] === 0x52 && buffer[offset + 1] === 0x49 && buffer[offset + 2] === 0x46 &&
+			buffer[offset + 3] === 0x46
+		) {
+			return 'audio/wav'
+		}
+
+		// FLAC: fLaC
+		if (
+			buffer[offset] === 0x66 && buffer[offset + 1] === 0x4c && buffer[offset + 2] === 0x61 &&
+			buffer[offset + 3] === 0x43
+		) {
+			return 'audio/flac'
+		}
+	}
+
+	// Default to OGG
+	return 'audio/ogg'
+}