Transcription reference¶

@dataclass(frozen=True)
class TranscriptionOptions:
    language: Language = "auto"
    vad_filter: bool = True
    beam_size: int = 5
    best_of: int = 5
    temperature: Temperature = (0.0, 0.2, 0.4, 0.6, 0.8, 1.0)
    initial_prompt: str | None = None
    without_timestamps: bool = False
    condition_on_previous_text: bool = True
    word_timestamps: bool = False
    max_new_tokens: int | None = None
    chunk_length: int | None = None
    language_detection_segments: int = 1
    language_detection_threshold: float = 0.5
    no_speech_threshold: float = 0.6
    vad_min_silence_duration_ms: int = 2000
    vad_speech_pad_ms: int = 400
    repetition_penalty: float = 1.0
    no_repeat_ngram_size: int = 0
    hotwords: str | None = None

class Transcriber(Protocol):
    model_name: str
    device: str

    def transcribe(
        self,
        audio_path: str | PathLike[str],
        options: TranscriptionOptions | None = None,
    ) -> TranscriptionResult:
        ...

class FasterWhisperTranscriber:
    """Thin wrapper around faster-whisper with project-safe defaults."""

    def __init__(
        self,
        model: str,
        *,
        device: str = "cpu",
        compute_type: str = "int8",
        cpu_threads: int = 0,
        num_workers: int = 1,
    ) -> None:
        try:
            from faster_whisper import WhisperModel
        except ImportError as exc:
            raise RuntimeError(
                "faster-whisper is not installed. Install with: "
                'uv pip install -e ".[faster-whisper]"'
            ) from exc

        self.model_name = model
        self.device = device
        self.compute_type = compute_type
        self._model = WhisperModel(
            model,
            device=device,
            compute_type=compute_type,
            cpu_threads=cpu_threads,
            num_workers=num_workers,
        )

    @classmethod
    def from_preset(cls, preset_name: str = "cpu-lite", **overrides: object) -> "FasterWhisperTranscriber":
        preset = get_preset(preset_name)
        return cls.from_model_preset(preset, **overrides)

    @classmethod
    def from_model_preset(cls, preset: ModelPreset, **overrides: object) -> "FasterWhisperTranscriber":
        config = {
            "model": preset.model,
            "device": preset.device,
            "compute_type": preset.compute_type,
        }
        config.update(overrides)
        return cls(**config)

    def transcribe(
        self,
        audio_path: str | PathLike[str],
        options: TranscriptionOptions | None = None,
    ) -> TranscriptionResult:
        options = options or TranscriptionOptions()
        if options.beam_size < 1:
            raise ValueError("beam_size must be >= 1")

        language = None if options.language == "auto" else options.language
        vad_parameters = None
        if options.vad_filter:
            vad_parameters = {
                "min_silence_duration_ms": options.vad_min_silence_duration_ms,
                "speech_pad_ms": options.vad_speech_pad_ms,
            }
        segments_iter, info = self._model.transcribe(
            str(audio_path),
            language=language,
            vad_filter=options.vad_filter,
            vad_parameters=vad_parameters,
            beam_size=options.beam_size,
            best_of=options.best_of,
            temperature=options.temperature,
            initial_prompt=options.initial_prompt,
            without_timestamps=options.without_timestamps,
            condition_on_previous_text=options.condition_on_previous_text,
            word_timestamps=options.word_timestamps and not options.without_timestamps,
            max_new_tokens=options.max_new_tokens,
            chunk_length=options.chunk_length,
            language_detection_segments=options.language_detection_segments,
            language_detection_threshold=options.language_detection_threshold,
            no_speech_threshold=options.no_speech_threshold,
            repetition_penalty=options.repetition_penalty,
            no_repeat_ngram_size=options.no_repeat_ngram_size,
            hotwords=options.hotwords,
        )
        segments = tuple(
            Segment(start=segment.start, end=segment.end, text=segment.text)
            for segment in segments_iter
        )
        text = "".join(segment.text for segment in segments).strip()
        return TranscriptionResult(
            text=text,
            language=info.language,
            language_probability=info.language_probability,
            duration=getattr(info, "duration", None),
            segments=segments,
        )