---

name: transcription description: "Use faster-whisper transcription APIs for ASR, batched inference, timestamps, VAD, language detection, audio decoding, and CPU or CUDA runtime choices." disable-model-invocation: true metadata: disco-role: operating license: MIT

faster-whisper Transcription

Use this sub-skill when the task is to transcribe, translate, segment, timestamp, or inspect audio with the faster-whisper Python package. It covers the public WhisperModel, BatchedInferencePipeline, decode_audio, and VAD/timestamp surfaces. Use the root skill for installation, backend setup, and model management decisions that are not specific to one transcription call.

Read first when

• The user mentions WhisperModel, BatchedInferencePipeline, decode_audio, VAD, word-level timestamps, hotwords, clip timestamps, language detection, translation, compute_type, or CPU/CUDA transcription.
• The user has an audio path, file-like object, or NumPy waveform and wants text segments, word timestamps, language probabilities, or batched throughput.
• The user reports confusing behavior such as an empty result because the segment generator was not consumed, CUDA compute-type errors, audio decode failures, VAD needing onnxruntime, or mismatched batched defaults.

Route map

• Read references/api-reference.md for verified signatures, return objects, option defaults, model aliases, and utility APIs.
• Read references/workflows.md for copyable recipes: standard transcription, batched transcription, VAD, word timestamps, hotwords, multilingual/translation, clip timestamps, stereo decoding, logging, and local model paths.
• Read references/troubleshooting.md for symptoms, likely causes, and recovery steps for model downloads, generator consumption, audio/PyAV, VAD/ONNX, CUDA/cuDNN/compute types, language/task choices, batching defaults, and long-audio handling.
• Run or adapt scripts/transcribe_audio.py when a future task needs a bundled command-line transcription helper instead of a prose-only recipe. The helper is safe to inspect with --help; real transcription may download or load a model.
• For install and backend setup, read ../../references/installation-and-backends.md.
• For model aliases, download/cache behavior, local CTranslate2 model paths, and conversion recipes, read ../../references/model-management.md.

Quick workflow

1. Choose a model source:
   • A public alias such as tiny, base, small, medium, large-v3, turbo, or distil-large-v3.
   • A Hugging Face repository id for a CTranslate2-converted Whisper model.
   • A local CTranslate2 model directory.
2. Choose runtime:
   • CPU: device="cpu", usually compute_type="int8" or "float32".
   • CUDA: device="cuda", usually compute_type="float16", "int8_float16", or another CTranslate2-supported type when NVIDIA CUDA/cuDNN libraries are available.
   • device="auto" is convenient for exploratory code, but use an explicit device in reproducible instructions or when troubleshooting.
3. Instantiate WhisperModel for ordinary transcription or wrap it in BatchedInferencePipeline for chunked batched inference.
4. Call transcribe(...) and always consume the returned segment generator with list(segments) or a for loop. The actual transcription starts when the generator is iterated.
5. Validate TranscriptionInfo (language, language_probability, duration, duration_after_vad) and the segment fields (start, end, text, optional words).

Minimal API pattern:

from faster_whisper import WhisperModel

model = WhisperModel("tiny", device="cpu", compute_type="int8")
segments, info = model.transcribe("audio.mp3", beam_size=5, language="en")
segments = list(segments)  # transcription runs here
print(info.language, info.language_probability)
for segment in segments:
    print(f"[{segment.start:.2f} -> {segment.end:.2f}] {segment.text}")

Important decisions

• Use word_timestamps=True when word-level timing is required; then inspect segment.words and validate monotonic times.
• Use vad_filter=True on WhisperModel.transcribe only when silence removal is desired; BatchedInferencePipeline.transcribe defaults to vad_filter=True.
• Use without_timestamps=False for timestamped output. WhisperModel defaults to timestamped behavior; BatchedInferencePipeline defaults to without_timestamps=True.
• Set language when known to avoid language-detection uncertainty; use task="translate" only when English translation is desired.
• Prefer clip_timestamps for explicit audio windows: WhisperModel accepts a comma-separated string such as "0,30,45,60"; batched transcription accepts a list of dictionaries like [{"start": 0.0, "end": 30.0}].
• For stereo diarization-like workflows, call decode_audio(path, split_stereo=True), transcribe left and right arrays separately, and keep the channel labels outside faster-whisper.

Boundaries and omissions

This sub-skill does not cover heavy speed, memory, or WER benchmarking as a runtime workflow. Those scripts require large model downloads, benchmark data, GPU telemetry, or external datasets. Treat benchmark numbers as context, not as required behavior for normal transcription tasks.