Example: "{stem}_{lang}.{ext}" → "interview_en.srt"

Inference Tuning: --beam-size N Beam search size; higher = more accurate but slower (default: 5) --temperature T Sampling temperature or comma-separated fallback list, e.g. '0.0' or '0.0,0.2,0.4' (default: faster-whisper's schedule) --no-speech-threshold PROB Probability threshold to mark segments as silence (default: 0.6) --batch-size N Batched inference batch size (default: 8; reduce if OOM) --no-vad Disable voice activity detection (on by default) --vad-threshold T VAD speech probability threshold (default: 0.5) --vad-neg-threshold T VAD negative threshold for ending speech (default: auto) --vad-onset T Alias for --vad-threshold (legacy) --vad-offset T Alias for --vad-neg-threshold (legacy) --min-speech-duration MS Minimum speech segment duration in ms (default: 0) --max-speech-duration SEC Maximum speech segment duration in seconds (default: unlimited) --min-silence-duration MS Minimum silence before splitting a segment in ms (default: 2000) --speech-pad MS Padding around speech segments in ms (default: 400) --no-batch Disable batched inference (use standard WhisperModel) --hallucination-silence-threshold SEC Skip silent sections where model hallucinates (e.g. 1.0) --no-condition-on-previous-text Don't condition on previous text (reduces repetition/hallucination loops; auto-enabled for distil models per HuggingFace recommendation) --condition-on-previous-text Force-enable conditioning on previous text (overrides auto-disable for distil models) --compression-ratio-threshold RATIO Filter segments above this compression ratio (default: 2.4) --log-prob-threshold PROB Filter segments below this avg log probability (default: -1.0) --max-new-tokens N Maximum tokens per segment (prevents runaway generation) --clip-timestamps RANGE Transcribe specific time ranges: '30,60' or '0,30;60,90' (seconds) --progress Show transcription progress bar --best-of N Candidates when sampling with non-zero temperature (default: 5) --patience F Beam search patience factor (default: 1.0) --repetition-penalty F Penalty for repeated tokens (default: 1.0) --no-repeat-ngram-size N Prevent n-gram repetitions of this size (default: 0 = off) Advanced Inference: --no-timestamps Output text without timing info (faster; incompatible with --word-timestamps, --format srt/vtt/tsv, --diarize) --chunk-length N Audio chunk length in seconds for batched inference (default: auto) --language-detection-threshold T Confidence threshold for language auto-detection (default: 0.5) --language-detection-segments N Audio segments to sample for language detection (default: 1) --length-penalty F Beam search length penalty; >1 favors longer, <1 favors shorter (default: 1.0) --prompt-reset-on-temperature T Reset initial prompt when temperature fallback hits threshold (default: 0.5) --no-suppress-blank Disable blank token suppression (may help soft/quiet speech) --suppress-tokens IDS Comma-separated token IDs to suppress in addition to default -1 --max-initial-timestamp T Maximum timestamp for the first segment in seconds (default: 1.0) --prepend-punctuations CHARS Punctuation characters merged into preceding word (default: "'¿([{-) --append-punctuations CHARS Punctuation characters merged into following word (default: "'.。,，!！?？:：")]}、")

Preprocessing:

--normalize Normalize audio volume (EBU R128 loudnorm) before transcription --denoise Apply noise reduction (high-pass + FFT denoise) before transcription

Advanced:

--diarize Speaker diarization (requires pyannote.audio) --min-speakers N Minimum number of speakers hint for diarization --max-speakers N Maximum number of speakers hint for diarization --speaker-names NAMES Comma-separated names to replace SPEAKER_1, SPEAKER_2 (e.g. 'Alice,Bob') Requires --diarize --min-confidence PROB Filter segments below this avg word confidence (0.0–1.0) --skip-existing Skip files whose output already exists (batch mode) --detect-language-only Detect language and exit (no transcription). Output: "Language: en (probability: 0.984)" With --format json: {"language": "en", "language_probability": 0.984} --stats-file PATH Write JSON stats sidecar after transcription (processing time, RTF, word count, etc.) Directory path → writes {stem}.stats.json inside; file path → exact path --burn-in OUTPUT Burn subtitles into the original video (single-file mode only; requires ffmpeg) --filter-hallucinations Filter common Whisper hallucinations: music/applause markers, duplicate segments, 'Thank you for watching', lone punctuation, etc. --keep-temp Keep temp files from URL downloads (useful for re-processing without re-downloading) --parallel N Number of parallel workers for batch processing (default: sequential) --retries N Retry failed files up to N times with exponential backoff (default: 0; incompatible with --parallel) Batch ETA: Automatically shown for sequential batch jobs (no flag needed). After each file completes, the next file's progress line includes: [current/total] filename | ETA: Xm Ys ETA is calculated from average time per file × remaining files. Shown to stderr (surfaced to users via OpenClaw/Clawdbot output). Language Map (per-file language override): --language-map MAP Per-file language override for batch mode. Two forms:

Inline: "interview*.mp3=en,lecture.wav=fr,keynote.wav=de"

JSON file: "@/path/to/map.json" (must be {pattern: lang} dict) Patterns support fnmatch globs on filename or stem.

Priority: exact filename > exact stem > glob on filename > glob on stem > fallback.

Files not matched fall back to --language (or auto-detect if not set). Transcript Search: --search TERM Search the transcript for TERM and print matching segments with timestamps. Replaces normal transcript output (use -o to save results to a file). Case-insensitive exact substring match by default. --search-fuzzy Enable fuzzy/approximate matching with --search (useful for typos, phonetic near-misses, or partial words; uses SequenceMatcher ratio ≥ 0.6) Chapter Detection: --detect-chapters Auto-detect chapter/section breaks from silence gaps and print chapter markers. Output is printed after the transcript (or to --chapters-file). --chapter-gap SEC Minimum silence gap in seconds between consecutive segments to start a new chapter (default: 8.0). Tune down for dense speech, up for sparse content. --chapters-file PATH Write chapter markers to this file (default: stdout after transcript) --chapter-format FMT youtube | text | json — chapter output format:

youtube: "0:00 Chapter 1" (YouTube description ready)
text:    "Chapter 1: 00:00:00"
json:    JSON array with chapter, start, title fields

(default: youtube) Speaker Audio Export: --export-speakers DIR After diarization, export each speaker's audio turns concatenated into separate WAV files saved in DIR. Requires --diarize and ffmpeg.

Output: SPEAKER_1.wav, SPEAKER_2.wav, … (or real names if --speaker-names set)

RSS / Podcast: --rss URL Podcast RSS feed URL — extracts audio enclosures and transcribes them. AUDIO positional is optional when --rss is used. --rss-latest N Number of most-recent episodes to process (default: 5; 0 = all episodes)

Device:

--device DEV auto | cpu | cuda (default: auto) --compute-type TYPE auto | int8 | int8_float16 | float16 | float32 (default: auto) int8_float16 = hybrid mode for GPU (saves VRAM, minimal quality loss) --threads N CPU thread count for CTranslate2 (default: auto) -q, --quiet Suppress progress and status messages --log-level LEVEL Set faster_whisper library logging level: debug | info | warning | error (default: warning; use debug to see CTranslate2/VAD internals)

Utility:

--version Print installed faster-whisper version and exit --update Upgrade faster-whisper in the skill venv and exit Output Formats Text (default) Plain transcript text. With --diarize, speaker labels are inserted: [SPEAKER_1] Hello, welcome to the meeting. [SPEAKER_2] Thanks for having me. JSON (--format json) Full metadata including segments, timestamps, language detection, and performance stats: { "file": "audio.mp3", "text": "Hello, welcome...", "language": "en", "language_probability": 0.98, "duration": 600.5, "segments": [...], "speakers": ["SPEAKER_1", "SPEAKER_2"], "stats": { "processing_time": 28.3, "realtime_factor": 21.2 } } SRT (--format srt) Standard subtitle format for video players: 1

00:00:00,000 --> 00:00:02,500

[SPEAKER_1] Hello, welcome to the meeting. 2

00:00:02,800 --> 00:00:04,200

[SPEAKER_2] Thanks for having me. VTT (--format vtt) WebVTT format for web video players: WEBVTT 1

00:00:00.000 --> 00:00:02.500

[SPEAKER_1] Hello, welcome to the meeting. 2

00:00:02.800 --> 00:00:04.200

[SPEAKER_2] Thanks for having me. TSV (--format tsv) Tab-separated values, OpenAI Whisper–compatible. Columns: start_ms, end_ms, text: 0 2500 Hello, welcome to the meeting. 2800 4200 Thanks for having me. Useful for piping into other tools or spreadsheets. No header row. ASS/SSA (--format ass) Advanced SubStation Alpha format — supported by Aegisub, VLC, mpv, MPC-HC, and most video editors. Offers richer styling than SRT (font, size, color, position) via the [V4+ Styles] section: [Script Info]

ScriptType: v4.00+

... [V4+ Styles]

Style: Default,Arial,20,&H00FFFFFF,...

[Events]

Format: Layer, Start, End, Style, Name, ..., Text
Dialogue: 0,0:00:00.00,0:00:02.50,Default,,[SPEAKER_1] Hello, welcome.
Dialogue: 0,0:00:02.80,0:00:04.20,Default,,[SPEAKER_2] Thanks for having me.

Timestamps use H:MM:SS.cc (centiseconds). Edit the [V4+ Styles] block in Aegisub to customise font, color, and position without re-transcribing. LRC (--format lrc) Timed lyrics format used by music players (e.g., Foobar2000, VLC, AIMP). Timestamps use [mm:ss.xx] where xx = centiseconds: [00:00.50]Hello, welcome to the meeting. [00:02.80]Thanks for having me. With diarization, speaker labels are included: [00:00.50][SPEAKER_1] Hello, welcome to the meeting. [00:02.80][SPEAKER_2] Thanks for having me. Default file extension: .lrc. Useful for music transcription, karaoke, and any workflow requiring timed text with music-player compatibility. Speaker Diarization Identifies who spoke when using pyannote.audio.

Setup:

./setup.sh --diarize

Requirements:

HuggingFace token at ~/.cache/huggingface/token (huggingface-cli login) Accepted model agreements:

https://hf.co/pyannote/speaker-diarization-3.1
https://hf.co/pyannote/segmentation-3.0
Usage:
# Basic diarization (text output)
./scripts/transcribe meeting.wav --diarize
# Diarized subtitles
./scripts/transcribe meeting.wav --diarize --format srt -o meeting.srt
# Diarized JSON (includes speakers list)
./scripts/transcribe meeting.wav --diarize --format json

Speakers are labeled SPEAKER_1, SPEAKER_2, etc. in order of first appearance. Diarization runs on GPU automatically if CUDA is available. Precise Word Timestamps Whenever word-level timestamps are computed (--word-timestamps, --diarize, or --min-confidence), a wav2vec2 forced alignment pass automatically refines them from Whisper's ~100-200ms accuracy to ~10ms. No extra flag needed.

# Word timestamps with automatic wav2vec2 alignment
./scripts/transcribe audio.mp3 --word-timestamps --format json
# Diarization also gets precise alignment automatically
./scripts/transcribe meeting.wav --diarize
# Precise subtitles
./scripts/transcribe audio.mp3 --word-timestamps --format srt -o subtitles.srt

Uses the MMS (Massively Multilingual Speech) model from torchaudio — supports 1000+ languages. The model is cached after first load, so batch processing stays fast. URL & YouTube Input Pass any URL as input — audio is downloaded automatically via yt-dlp:

# YouTube video
./scripts/transcribe https://youtube.com/watch?v=dQw4w9WgXcQ
# Direct audio URL
./scripts/transcribe https://example.com/podcast.mp3
# With options
./scripts/transcribe https://youtube.com/watch?v=... --language en --format srt -o subs.srt

Requires yt-dlp (checks PATH and ~/.local/share/pipx/venvs/yt-dlp/bin/yt-dlp). Batch Processing Process multiple files at once with glob patterns, directories, or multiple paths:

# All MP3s in current directory
./scripts/transcribe *.mp3
# Entire directory (auto-filters audio files)
./scripts/transcribe ./recordings/
# Output to directory (one file per input)
./scripts/transcribe *.mp3 -o ./transcripts/
# Skip already-transcribed files (resume interrupted batch)
./scripts/transcribe *.mp3 --skip-existing -o ./transcripts/
# Mixed inputs
./scripts/transcribe file1.mp3 file2.wav ./more-recordings/
# Batch SRT subtitles
./scripts/transcribe *.mp3 --format srt -o ./subtitles/

When outputting to a directory, files are named {input-stem}.{ext} (e.g., audio.mp3 → audio.srt). Batch mode prints a summary after all files complete: 📊 Done: 12 files, 3h24m audio in 10m15s (19.9× realtime) Workflows End-to-end pipelines for common use cases. Podcast Transcription Pipeline Fetch and transcribe the latest 5 episodes from any podcast RSS feed:

# Transcribe latest 5 episodes → one .txt per episode
./scripts/transcribe --rss https://feeds.megaphone.fm/mypodcast -o ./transcripts/
# All episodes, as SRT subtitles
./scripts/transcribe --rss https://... --rss-latest 0 --format srt -o ./subtitles/
# Skip already-done episodes (safe to re-run)
./scripts/transcribe --rss https://... --skip-existing -o ./transcripts/
# With diarization (who said what) + retry on flaky network
./scripts/transcribe --rss https://... --diarize --retries 2 -o ./transcripts/

Meeting Notes Pipeline Transcribe a meeting recording with speaker labels, then output clean text:

# Diarize + name speakers (replace SPEAKER_1/2 with real names)
./scripts/transcribe meeting.wav --diarize --speaker-names "Alice,Bob" -o meeting.txt
# Diarized JSON for post-processing (summaries, action items)
./scripts/transcribe meeting.wav --diarize --format json -o meeting.json
# Stream live while it transcribes (long meetings)
./scripts/transcribe meeting.wav --stream

Video Subtitle Pipeline Generate ready-to-use subtitles for a video file:

# SRT subtitles with sentence merging (better readability)
./scripts/transcribe video.mp4 --format srt --merge-sentences -o subtitles.srt
# Burn subtitles directly into the video
./scripts/transcribe video.mp4 --format srt --burn-in video_subtitled.mp4
# Word-level SRT (karaoke-style), capped at 8 words per cue
./scripts/transcribe video.mp4 --format srt --word-timestamps --max-words-per-line 8 -o subs.srt

YouTube Batch Pipeline Transcribe multiple YouTube videos at once:

# One-liner: transcribe a playlist video + output SRT
./scripts/transcribe "https://youtube.com/watch?v=abc123" --format srt -o subs.srt
# Batch from a text file of URLs (one per line)
cat urls.txt | xargs ./scripts/transcribe -o ./transcripts/
# Download audio first, then transcribe (for re-use without re-downloading)
./scripts/transcribe https://youtube.com/watch?v=abc123 --keep-temp

Noisy Audio Pipeline Clean up poor-quality recordings before transcribing:

# Denoise + normalize, then transcribe
./scripts/transcribe interview.mp3 --denoise --normalize -o interview.txt
# Noisy batch with aggressive hallucination filtering
./scripts/transcribe *.mp3 --denoise --filter-hallucinations -o ./out/

Batch Recovery Pipeline Process a large folder with retries — safe to re-run after failures:

# Retry each failed file up to 3 times, skip already-done
./scripts/transcribe ./recordings/ --skip-existing --retries 3 -o ./transcripts/
# Check what failed (printed in batch summary at the end)
# Re-run the same command — skips successes, retries failures

Cloud STT via SkillBoss API Hub 如果你无法在本地运行 faster-whisper（云端环境、无 GPU），可以通过 SkillBoss API Hub 的 /v1/pilot 统一入口调用云端语音识别能力，自动路由最优 STT 模型，无需指定具体模型名称。 快速调用（curl）

# 通过 SkillBoss API Hub 发送音频进行转录（自动路由最优 STT 模型）

AUDIO_B64=$(base64 -w0 audio.mp3)

curl -X POST https://api.heybossai.com/v1/pilot \

-H "Authorization: Bearer $SKILLBOSS_API_KEY"
-H "Content-Type: application/json"
-d "{"type": "stt", "inputs": {"audio_data": "$AUDIO_B64", "filename": "audio.mp3"}}" Python 调用 import requests, os, base64 SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"] API_BASE = "https://api.heybossai.com/v1" def pilot(body: dict) -> dict: r = requests.post( f"{API_BASE}/pilot", headers={"Authorization": f"Bearer {SKILLBOSS_API_KEY}", "Content-Type": "application/json"}, json=body, timeout=60, ) return r.json() audio_b64 = base64.b64encode(open("audio.mp3", "rb").read()).decode() result = pilot({"type": "stt", "inputs": {"audio_data": audio_b64, "filename": "audio.mp3"}}) text = result["data"]["result"]["text"] print(text) 适用于云端环境、无本地 GPU、或需要将转录集成到其他工具（Home Assistant、n8n、自定义应用）的场景。 Common Mistakes MistakeProblemSolutionUsing CPU when GPU available10-20x slower transcriptionCheck nvidia-smi; verify CUDA installationNot specifying languageWastes time auto-detecting on known contentUse --language en when you know the languageUsing wrong modelUnnecessary slowness or poor accuracyDefault distil-large-v3.5 is excellent; only use large-v3 if accuracy issuesIgnoring distilled modelsMissing 6x speedup with <1% accuracy lossTry distil-large-v3.5 before reaching for standard modelsForgetting ffmpegSetup fails or audio can't be processedSetup script handles this; manual installs need ffmpeg separatelyOut of memory errorsModel too large for available VRAM/RAMUse smaller model, --compute-type int8, or --batch-size 4Over-engineering beam sizeDiminishing returns past beam-size 5-7Default 5 is fine; try 10 for critical transcripts--diarize without pyannoteImport error at runtimeRun setup.sh --diarize first--diarize without HuggingFace tokenModel download failsRun huggingface-cli login and accept model agreementsURL input without yt-dlpDownload failsInstall: pipx install yt-dlp--min-confidence too highDrops good segments with natural pausesStart at 0.5, adjust up; check JSON output for probabilitiesUsing --word-timestamps for basic transcriptionAdds ~5-10s overhead for negligible benefitOnly use when word-level precision mattersBatch without -o directoryAll output mixed in stdoutUse -o ./transcripts/ to write one file per input Performance Notes First run: Downloads model to ~/.cache/huggingface/ (one-time) Batched inference: Enabled by default via BatchedInferencePipeline — ~3x faster than standard mode; VAD on by default

GPU: Automatically uses CUDA if available
Quantization: INT8 used on CPU for ~4x speedup with minimal accuracy loss

Performance stats: Every transcription shows audio duration, processing time, and realtime factor Benchmark (RTX 3070, 21-min file): ~24s with batched inference (both distil-large-v3 and v3.5) vs ~69s without --precise overhead: Adds ~5-10s for wav2vec2 model load + alignment (model cached for batch) Diarization overhead: Adds ~10-30s depending on audio length (runs on GPU if available)

Memory:
distil-large-v3: ~2GB RAM / ~1GB VRAM
large-v3-turbo: ~4GB RAM / ~2GB VRAM

tiny/base: <1GB RAM

Diarization: additional ~1-2GB VRAM
OOM: Lower --batch-size (try 4) if you hit out-of-memory errors

Pre-convert to WAV (optional): ffmpeg -i input.mp3 -ar 16000 -ac 1 input.wav converts to 16kHz mono WAV before transcription. Benefit is minimal (~5%) for one-off use since PyAV decodes efficiently — most useful when re-processing the same file multiple times (research/experiments) or when a format causes PyAV decode issues. Note: --normalize and --denoise already perform this conversion automatically. Silero VAD V6: faster-whisper 1.2.1 upgraded to Silero VAD V6 (improved speech detection). Run ./setup.sh --update to get it. Batched silence removal: faster-whisper 1.2.0+ automatically removes silence in BatchedInferencePipeline (used by default). Upgrade with ./setup.sh --update to get this if you installed before August 2024. Why faster-whisper?

Speed: ~4-6x faster than OpenAI's original Whisper
Accuracy: Identical (uses same model weights)
Efficiency: Lower memory usage via quantization
Production-ready: Stable C++ backend (CTranslate2)

Distilled models: ~6x faster with <1% accuracy loss

Subtitles: Native SRT/VTT/HTML output

Precise alignment: Automatic wav2vec2 refinement (~10ms word boundaries)

Diarization: Optional speaker identification via pyannote; --speaker-names maps to real names
URLs: Direct YouTube/URL input; --keep-temp preserves downloads for re-use

Custom models: Load local CTranslate2 dirs or HuggingFace repos; --model-dir controls cache Quality control: --filter-hallucinations strips music/applause markers and duplicates Parallel batch: --parallel N for multi-threaded batch processing Subtitle burn-in: --burn-in overlays subtitles directly into video via ffmpeg v1.5.0 New Features Multi-format output: --format srt,text — write multiple formats in one pass (e.g. SRT + plain text simultaneously) Comma-separated list accepted: srt,vtt,json, srt,text, etc. Requires -o

Setup:

Check installed version: Run ./scripts/transcribe --version