faster-whisper

Faster Whisper

faster-whisper を使用したローカル音声文字起こしです。OpenAI の Whisper を CTranslate2 で再実装したもので、精度はそのままに 4～6 倍高速で動作します。GPU アクセラレーションを使用すると、リアルタイムの約 20 倍の速度で文字起こしできます（10 分の音声ファイルを約 30 秒で処理）。

使用する場面

次のような場合にこのスキルを使用します。

• 音声／動画ファイルを文字起こしする — 会議、インタビュー、ポッドキャスト、講義、YouTube 動画
• 字幕を生成する — SRT、VTT、ASS、LRC、または TTML 放送標準字幕
• 話者を識別する — 話者ダイアライゼーションにより、誰が何を話したかをラベル付けします（--diarize）
• URL から文字起こしする — YouTube のリンクや音声への直接 URL（yt-dlp で自動ダウンロード）
• ポッドキャストのフィードを文字起こしする — --rss <feed-url> でエピソードを取得して文字起こしします
• ファイルを一括処理する — glob パターン、ディレクトリ、処理済みファイルのスキップに対応し、残り時間を自動表示します
• 音声をローカルでテキストに変換する — API 費用が不要で、オフラインでも動作します（モデルのダウンロード後）
• 英語に翻訳する — --translate であらゆる言語を英語に翻訳します
• 多言語の文字起こしを行う — 99 以上の言語に対応し、自動検出します
• 異なる言語のファイルを一括で文字起こしする — --language-map でファイルごとに異なる言語を割り当てます
• 多言語音声を文字起こしする — 言語が混在する音声には --multilingual を使用します
• 特定の用語を含む音声を文字起こしする — 専門用語の多い内容や、注意すべきその他の用語には --initial-prompt を使用します
• ノイズの多い音声を前処理する（文字起こし前） — 文字起こしの前に --normalize と --denoise を使用します
• 出力をストリーミングする — --stream で文字起こし中のセグメントを表示します
• 時間範囲を切り出す — --clip-timestamps で特定の区間を文字起こしします
• 文字起こし結果を検索する — --search "term" で単語やフレーズが出現するすべてのタイムスタンプを検索します
• チャプターを検出する — --detect-chapters で無音区間からセクションの区切りを検出します
• 話者ごとの音声を書き出す — --export-speakers DIR で各話者の発話を個別の WAV ファイルとして保存します
• スプレッドシート形式で出力する — --format csv でタイムスタンプを適切に引用符で囲んだ CSV を生成します

起動フレーズ： 「この音声を文字起こしして」「音声をテキストに変換して」「何と言っていましたか」「文字起こしを作成して」 「音声をテキストに」「この動画に字幕を付けて」「誰が話していますか」「この音声を翻訳して」「英語に翻訳して」 「X が言及されている箇所を探して」「文字起こし結果から検索して」「いつ言いましたか」「どのタイムスタンプですか」 「チャプターを追加して」「チャプターを検出して」「音声の区切りを探して」「この録音の目次を作成して」 「TTML 字幕」「DFXP 字幕」「放送形式の字幕」「Netflix 形式」 「ASS 字幕」「aegisub 形式」「advanced substation alpha」「mpv 字幕」 「LRC 字幕」「タイム付き歌詞」「カラオケ字幕」「音楽プレーヤー用の歌詞」 「HTML 文字起こし」「信頼度を色分けした文字起こし」「色分けした文字起こし」 「話者ごとに音声を分けて」「話者ごとの音声を書き出して」「話者ごとに分割して」 「CSV 形式の文字起こし」「スプレッドシート形式で出力して」「ポッドキャストを文字起こしして」「ポッドキャストの RSS フィード」 「一括処理で異なる言語を使う」「ファイルごとに言語を指定」 「複数の形式で文字起こしして」「srt と txt を同時に」「srt とテキストの両方を出力して」 「フィラーを削除して」「えーやあーを取り除いて」「ためらいの音を削除して」「you know や I mean を削除して」 「左チャンネルを文字起こしして」「右チャンネルを文字起こしして」「ステレオチャンネル」「左トラックのみ」 「字幕の行を折り返して」「1 行あたりの文字数制限」「字幕ごとの最大文字数」 「段落を検出して」「段落の区切り」「段落ごとにまとめて」「段落間に空白を追加して」

⚠️ エージェントへのガイダンス — 呼び出しは最小限にしてください：

基本ルール：デフォルトのコマンド（./scripts/transcribe audio.mp3）が最速の方法です。ユーザーがその機能を明示的に求めた場合にのみ、フラグを追加してください。

文字起こし：

• ユーザーが「誰が何を言ったか」「話者を特定して」「話者にラベルを付けて」と依頼した場合にのみ、--diarize を追加します
• ユーザーが指定した形式の字幕／キャプションを求めた場合にのみ、--format srt/vtt/ass/lrc/ttml を追加します
• ユーザーが CSV またはスプレッドシート形式の出力を求めた場合にのみ、--format csv を追加します
• ユーザーが単語単位のタイミングを必要としている場合にのみ、--word-timestamps を追加します
• 音声に専門分野特有の用語があり、事前に指定する必要がある場合にのみ、--initial-prompt を追加します
• ユーザーが英語以外の音声を英語に翻訳するよう求めた場合にのみ、--translate を追加します
• ユーザーが音質の悪さやノイズに言及した場合にのみ、--normalize／--denoise を追加します
• ユーザーが長いファイルのライブ出力や逐次出力を求めた場合にのみ、--stream を追加します
• ユーザーが特定の時間範囲を指定した場合にのみ、--clip-timestamps を追加します
• モデルが音楽や無音部分について幻覚を起こしている場合にのみ、--temperature 0.0 を追加します
• VAD が音声を過剰にカットしている、またはノイズを含めている場合にのみ、--vad-threshold を追加します
• 話者数がわかっている場合にのみ、--min-speakers／--max-speakers を追加します
• トークンが ~/.cache/huggingface/token にキャッシュされていない場合にのみ、--hf-token を追加します
• 長いセグメントの字幕の読みやすさを確保する場合にのみ、--max-words-per-line を追加します
• トランスクリプトに明らかなアーティファクト（音楽のマーカー、重複）が含まれている場合にのみ、--filter-hallucinations を追加します
• ユーザーが文単位の字幕キューを求めた場合にのみ、--merge-sentences を追加します
• ユーザーがフィラーワード（um、uh、you know、I mean、ためらいの音）を削除するよう求めた場合にのみ、--clean-filler を追加します
• ユーザーがステレオトラックやデュアルチャンネル録音に言及した、または特定のチャンネルを指定した場合にのみ、--channel left|right を追加します
• ユーザーが字幕の1行あたりの文字数制限（例：「Netflix 形式」「1行42文字」）を指定した場合にのみ、--max-chars-per-line N を追加します。--max-words-per-line より優先されます
• ユーザーが段落分けや構造化テキスト出力を求めた場合にのみ、--detect-paragraphs を追加します。カスタムの間隔を求めている場合にのみ、--paragraph-gap（デフォルトは3.0s）を追加します
• ユーザーが SPEAKER_1/2 を置き換える実名を指定した場合にのみ、--speaker-names "Alice,Bob" を追加します。必ず --diarize も指定します
• ユーザーが --initial-prompt では十分に扱えない具体的な珍しい用語を指定した場合にのみ、--hotwords WORDS を追加します。一般的な専門用語には --initial-prompt を優先します
• ユーザーが音声の冒頭の正確な語句を把握している場合にのみ、--prefix TEXT を追加します
• ユーザーが文字起こしではなく言語の特定のみを求めた場合にのみ、--detect-language-only を追加します
• ユーザーがパフォーマンス統計、RTF、またはベンチマーク情報を求めた場合にのみ、--stats-file PATH を追加します
• CPU で大規模なバッチ処理を行う場合にのみ、--parallel N を追加します。GPU は単一ファイルを効率よく処理するため、単一ファイルや小規模なバッチには追加しないでください
• 一時的な失敗が予想される信頼性の低い入力（URL、ネットワーク上のファイル）に対してのみ、--retries N を追加します
• ユーザーが字幕を動画に埋め込むことを明示的に求めた場合にのみ、--burn-in OUTPUT を追加します。ffmpeg と動画ファイルの入力が必要です
• 同じ URL を再処理する可能性があり、再ダウンロードを避ける必要がある場合にのみ、--keep-temp を追加します
• ユーザーがバッチモードでカスタムの命名パターンを指定した場合にのみ、--output-template を追加します
• 複数形式の出力（--format srt,text）：ユーザーが1回の処理で複数形式を明示的に求めた場合にのみ指定します。必ず -o <dir> と併用します
• 単語単位の機能を使うと、wav2vec2 によるアライメントが自動的に実行されます（約5～10秒の追加時間）
• --diarize を追加すると、さらに約20～30秒かかります

検索：

• ユーザーが音声内の特定の単語やフレーズを探すよう求めた場合にのみ、--search "term" を追加します
• --search を指定すると通常のトランスクリプト出力は置き換えられ、タイムスタンプ付きの一致セグメントのみが出力されます
• ユーザーが近似一致／部分一致や誤字に言及した場合にのみ、--search-fuzzy を追加します
• 検索結果をファイルに保存するには、-o results.txt を使用します

チャプター検出：

• ユーザーがチャプター、セクション、目次、または「トピックが変わるのはどこか」を求めた場合にのみ、--detect-chapters を追加します
• デフォルトの --chapter-gap 8（8 秒間の無音で新しいチャプター）は、ほとんどのポッドキャストや講義で適切です。内容が密な場合は値を小さく調整してください
• --chapter-format youtube（デフォルト）は YouTube ですぐに使えるタイムスタンプを出力します。プログラムで使う場合は json を使用してください
• 文字起こしの出力とチャプターを組み合わせる場合は、必ず --chapters-file PATH を使用してください。これにより、チャプターマーカーが文字起こしテキストに混ざるのを防げます
• ユーザーがチャプターのみを希望する場合（文字起こしは不要）、-o /dev/null で標準出力をファイルにパイプし、--chapters-file を使用してください
• バッチモードの制限： --chapters-file に指定できるパスは 1 つだけです。バッチモードでは、各ファイルのチャプターが前のファイルの内容を上書きします。バッチでチャプターを検出するには、--chapters-file を省略してください（チャプターは === CHAPTERS (N) === の下に標準出力されます）。または、ファイルごとに個別に実行してください

話者ごとの音声エクスポート：

• ユーザーが各話者の音声を個別に保存するよう明示的に依頼した場合にのみ、--export-speakers DIR を追加します
• 必ず --diarize と組み合わせてください。話者ラベルがない場合は、通知なしでスキップされます
• ffmpeg が必要です。SPEAKER_1.wav、SPEAKER_2.wav などが出力されます（--speaker-names が設定されている場合は実際の名前になります）

言語マップ：

• ファイル間で言語が異なることをユーザーが確認した場合に限り、バッチモードで --language-map を追加します
• インライン形式："interview*.mp3=en,lecture*.mp3=fr" — ファイル名に対する fnmatch グロブです
• JSON ファイル形式：{"pattern": "lang_code"} という内容のファイルを指定する @/path/to/map.json

RSS / ポッドキャスト：

• ユーザーがポッドキャストの RSS フィード URL を指定した場合にのみ、--rss URL を追加します
• デフォルトでは新しいエピソードを 5 件取得します。すべて取得するには --rss-latest 0 を使用し、安全に再開するには --skip-existing を使用します
• --rss では 必ず -o <dir> を使用してください。指定しない場合、すべてのエピソードの文字起こしが連結されて標準出力に表示され、使いにくくなります。-o <dir> を設定すると、エピソードごとに個別のファイルが作成されます

エージェントへの中継時の出力形式：

• 検索結果（--search）→ そのままユーザーに表示します。人が読みやすい形式で出力されます
• チャプター出力 → --chapters-file を指定しない場合、文字起こしの後に === CHAPTERS (N) === という見出しの下にチャプターが標準出力されます。--format json の場合、チャプターは JSON の "chapters" キーにも含まれます
• 字幕形式（SRT、VTT、ASS、LRC、TTML）→ 必ず -o で指定したファイルに書き込みます。出力先のパスをユーザーに伝え、生の字幕内容は貼り付けないでください
• データ形式（CSV、HTML、TTML、JSON）→ 必ず -o で指定したファイルに書き込みます。出力先のパスをユーザーに伝え、生の XML/CSV/HTML は貼り付けないでください
• ASS 形式 → Aegisub、VLC、mpv 用です。ファイルに書き込み、Aegisub で開くか VLC/mpv で再生できることをユーザーに伝えます
• LRC 形式 → 音楽プレーヤー（Foobar2000、AIMP、VLC）用のタイムスタンプ付き歌詞です。ファイルに書き込みます
• 複数形式（--format srt,text）→ -o <dir> が必要です。形式ごとに別のファイルに出力されるため、書き込まれたすべてのパスをユーザーに伝えます
• JSON 形式 → プログラムで後処理する場合に便利ですが、全内容をユーザーに貼り付ける用途には適していません
• テキスト／文字起こし → 短いファイルならユーザーにそのまま表示しても問題ありません。長い場合は要約してください
• 統計情報の出力（--stats-file）→ 生の JSON を貼り付けるのではなく、主要な項目（再生時間、処理時間、RTF）を要約してユーザーに伝えます
• 言語検出（--detect-language-only）→ 結果をそのまま表示します。1 行だけの出力です
• ETA はバッチジョブでは stderr に自動出力されます。対応は不要です

使用しない場合：

• ローカルの計算リソースがない、クラウドのみの環境
• API 呼び出しのレイテンシが問題にならない、10 秒未満のファイル

faster-whisper と whisperx の比較： このスキルは、話者ダイアライゼーション（--diarize）、単語レベルのタイムスタンプ（--word-timestamps）、SRT/VTT 字幕など、whisperx の機能をすべてカバーするため、whisperx は不要です。ここでカバーされていない pyannote パイプラインやバッチ GPU 機能が特に必要な場合に限り、whisperx を使用してください。

クイックリファレンス

タスク	コマンド	備考
基本の文字起こし	./scripts/transcribe audio.mp3	バッチ推論、VAD 有効、distil-large-v3.5
SRT 字幕	./scripts/transcribe audio.mp3 --format srt -o subs.srt	単語のタイムスタンプが自動的に有効になります
VTT 字幕	./scripts/transcribe audio.mp3 --format vtt -o subs.vtt	WebVTT 形式
単語のタイムスタンプ	./scripts/transcribe audio.mp3 --word-timestamps --format srt	wav2vec2 によるアラインメント（約 10ms）
話者ダイアライゼーション	./scripts/transcribe audio.mp3 --diarize	pyannote.audio が必要です
英語に翻訳	./scripts/transcribe audio.mp3 --translate	あらゆる言語から英語へ
ストリーム出力	./scripts/transcribe audio.mp3 --stream	文字起こしされたセグメントをリアルタイムで出力
時間範囲を切り抜く	./scripts/transcribe audio.mp3 --clip-timestamps "30,60"	30 秒～60 秒のみ
ノイズ除去＋正規化	./scripts/transcribe audio.mp3 --denoise --normalize	まず音声のノイズを除去します
幻覚を抑制	./scripts/transcribe audio.mp3 --hallucination-silence-threshold 1.0	幻覚による無音部分をスキップします
YouTube／URL	./scripts/transcribe https://youtube.com/watch?v=...	yt-dlp 経由で自動ダウンロードします
バッチ処理	./scripts/transcribe *.mp3 -o ./transcripts/	ディレクトリに出力します
スキップ付きバッチ処理	./scripts/transcribe *.mp3 --skip-existing -o ./out/	中断したバッチ処理を再開します
ドメイン用語	./scripts/transcribe audio.mp3 --initial-prompt 'Kubernetes gRPC'	出現頻度の低い専門用語を優先します
ホットワードの強調	./scripts/transcribe audio.mp3 --hotwords 'JIRA Kubernetes'	デコーダーが特定の単語を優先するよう調整します
プレフィックス条件付け	./scripts/transcribe audio.mp3 --prefix 'Good morning,'	既知の冒頭語句を最初のセグメントに設定します
モデルバージョンを固定	./scripts/transcribe audio.mp3 --revision v1.2.0	リビジョンを固定して再現可能な文字起こしを行います
ライブラリのログをデバッグ	./scripts/transcribe audio.mp3 --log-level debug	faster_whisper の内部ログを表示します
Turbo モデル	./scripts/transcribe audio.mp3 -m turbo	large-v3-turbo の別名です
英語の文字起こしを高速化	./scripts/transcribe audio.mp3 --model distil-medium.en -l en	英語専用、6.8 倍高速
最高精度	./scripts/transcribe audio.mp3 --model large-v3 --beam-size 10	フルモデル
JSON 出力	./scripts/transcribe audio.mp3 --format json -o out.json	統計情報を含む、プログラムからのアクセス向け
ノイズをフィルタリング	./scripts/transcribe audio.mp3 --min-confidence 0.6	信頼度の低いセグメントを除外します
ハイブリッド量子化	./scripts/transcribe audio.mp3 --compute-type int8_float16	VRAM を節約し、品質の低下を最小限に抑えます
バッチサイズを縮小	./scripts/transcribe audio.mp3 --batch-size 4	GPU で OOM が発生する場合に使用します
TSV 出力	./scripts/transcribe audio.mp3 --format tsv -o out.tsv	OpenAI Whisper 互換の TSV
幻覚を修正	./scripts/transcribe audio.mp3 --temperature 0.0 --no-speech-threshold 0.8	温度を固定し、無音部分をスキップします
VAD の感度を調整	./scripts/transcribe audio.mp3 --vad-threshold 0.6 --min-silence-duration 500	音声検出をより厳密にします
話者数が既知の場合	./scripts/transcribe meeting.wav --diarize --min-speakers 2 --max-speakers 3	ダイアライゼーションの範囲を制限します
字幕の単語折り返し	./scripts/transcribe audio.mp3 --format srt --word-timestamps --max-words-per-line 8	長い字幕キューを分割します
非公開／アクセス制限付きモデル	./scripts/transcribe audio.mp3 --hf-token hf_xxx	トークンを直接渡します
バージョンを表示	./scripts/transcribe --version	faster-whisper のバージョンを表示します
上書き更新	./setup.sh --update	完全に再インストールせずにアップグレードします
システムチェック	./setup.sh --check	GPU、Python、ffmpeg、venv、yt-dlp、pyannote を確認します
言語のみ検出	./scripts/transcribe audio.mp3 --detect-language-only	高速な言語識別を行い、文字起こしはしません
言語検出を JSON で出力	./scripts/transcribe audio.mp3 --detect-language-only --format json	機械可読形式の言語検出結果
LRC 字幕	./scripts/transcribe audio.mp3 --format lrc -o lyrics.lrc	音楽プレーヤー向けのタイムスタンプ付き歌詞形式
ASS 字幕	./scripts/transcribe audio.mp3 --format ass -o subtitles.ass	Advanced SubStation Alpha（Aegisub、mpv、VLC）
文を結合	./scripts/transcribe audio.mp3 --format srt --merge-sentences	断片を結合して文単位にします
統計サイドカー	./scripts/transcribe audio.mp3 --stats-file stats.json	文字起こし後にパフォーマンス統計を JSON で書き込みます
バッチ統計	./scripts/transcribe *.mp3 --stats-file ./stats/	ディレクトリ内の入力ファイルごとに統計ファイルを作成します
テンプレートによる命名	./scripts/transcribe audio.mp3 -o ./out/ --output-template "{stem}_{lang}.{ext}"	バッチ出力ファイル名をカスタマイズします
標準入力から入力	ffmpeg -i input.mp4 -f wav - | ./scripts/transcribe -	標準入力から音声を直接パイプします
カスタムモデルディレクトリ	./scripts/transcribe audio.mp3 --model-dir ~/my-models	HuggingFace のキャッシュディレクトリを指定します
ローカルモデル	./scripts/transcribe audio.mp3 -m ./my-model-ct2	CTranslate2 のモデルディレクトリ
HTML 文字起こし	./scripts/transcribe audio.mp3 --format html -o out.html	信頼度に応じて色分けします
字幕を焼き込む	./scripts/transcribe video.mp4 --burn-in output.mp4	ffmpeg と動画入力が必要です
話者に名前を付ける	./scripts/transcribe audio.mp3 --diarize --speaker-names "Alice,Bob"	SPEAKER_1/2 を置き換えます
幻覚をフィルタリング	./scripts/transcribe audio.mp3 --filter-hallucinations	アーティファクトを削除します
一時ファイルを保持	./scripts/transcribe https://... --keep-temp	URL を再処理する場合に使用します
並列バッチ処理	./scripts/transcribe *.mp3 --parallel 4 -o ./out/	CPU で複数ファイルを処理します
RTX 3070 に推奨	./scripts/transcribe audio.mp3 --compute-type int8_float16	VRAM を約 1GB 節約し、品質の低下を最小限に抑えます
CPU スレッド数	./scripts/transcribe audio.mp3 --threads 8	CPU スレッド数を指定します（デフォルト：自動）
ポッドキャスト RSS（最新 5 件）	./scripts/transcribe --rss https://feeds.example.com/podcast.xml	最新 5 件のエピソードをダウンロードして文字起こしします
ポッドキャスト RSS（全エピソード）	./scripts/transcribe --rss https://... --rss-latest 0 -o ./episodes/	全エピソードをそれぞれ別ファイルに出力します
ポッドキャスト＋SRT 字幕	./scripts/transcribe --rss https://... --format srt -o ./subs/	すべてのエピソードに字幕を付けます
失敗時に再試行	./scripts/transcribe *.mp3 --retries 3 -o ./out/	エラー時にバックオフを挟んで最大 3 回再試行します
CSV 出力	./scripts/transcribe audio.mp3 --format csv -o out.csv	ヘッダー行付きでスプレッドシート向けに出力します。適切に引用符で囲みます
話者付き CSV	./scripts/transcribe audio.mp3 --diarize --format csv -o out.csv	話者列を追加します
言語マップ（インライン）	./scripts/transcribe *.mp3 --language-map "interview*.mp3=en,lecture.wav=fr"	バッチ処理でファイルごとに言語を指定します
言語マップ（JSON）	./scripts/transcribe *.mp3 --language-map @langs.json	JSON ファイル：{"pattern": "lang"}
ETA 付きバッチ処理	./scripts/transcribe *.mp3 -o ./out/	バッチ内の各ファイルについて ETA を自動表示します
TTML 字幕	./scripts/transcribe audio.mp3 --format ttml -o subtitles.ttml	放送標準の DFXP/TTML（Netflix、BBC、Amazon）
話者ラベル付き TTML	./scripts/transcribe audio.mp3 --diarize --format ttml -o subtitles.ttml	話者ラベル付き TTML
文字起こしを検索	./scripts/transcribe audio.mp3 --search "keyword"	キーワードが出現するタイムスタンプを検索します
検索結果をファイルに保存	./scripts/transcribe audio.mp3 --search "keyword" -o results.txt	検索結果を保存します
あいまい検索	./scripts/transcribe audio.mp3 --search "aproximate" --search-fuzzy	類似・部分一致検索
チャプターを検出	./scripts/transcribe audio.mp3 --detect-chapters	無音の間隔からチャプターを自動検出します
チャプター間隔の調整	./scripts/transcribe audio.mp3 --detect-chapters --chapter-gap 5	5 秒以上の間隔でチャプターを作成します（デフォルト：8 秒）
チャプターをファイルに保存	./scripts/transcribe audio.mp3 --detect-chapters --chapters-file ch.txt	YouTube 形式のチャプターリストを保存します
チャプターを JSON で出力	./scripts/transcribe audio.mp3 --detect-chapters --chapter-format json	機械可読形式のチャプターリスト
話者ごとの音声をエクスポート	./scripts/transcribe audio.mp3 --diarize --export-speakers ./speakers/	話者ごとの音声を個別の WAV ファイルとして保存します
複数形式で出力	./scripts/transcribe audio.mp3 --format srt,text -o ./out/	1 回の処理で SRT と TXT を出力します
フィラー語を削除	./scripts/transcribe audio.mp3 --clean-filler	um／uh／er／ah／hmm や談話標識を取り除きます
左チャンネルのみ	./scripts/transcribe audio.mp3 --channel left	文字起こし前にステレオ音声の左チャンネルを抽出します
右チャンネルのみ	./scripts/transcribe audio.mp3 --channel right	ステレオ音声の右チャンネルを抽出します
行あたりの最大文字数	./scripts/transcribe audio.mp3 --format srt --max-chars-per-line 42	文字数に基づいて字幕を折り返します
段落を検出	./scripts/transcribe audio.mp3 --detect-paragraphs	テキスト出力に段落区切りを挿入します
段落間隔の調整	./scripts/transcribe audio.mp3 --detect-paragraphs --paragraph-gap 5.0	間隔のしきい値を調整します（デフォルト：3.0 秒）

モデルの選択

ニーズに合ったモデルを選択してください。

digraph model_selection {
    rankdir=LR;
    node [shape=box, style=rounded];

    start [label="Start", shape=doublecircle];
    need_accuracy [label="Need maximum\naccuracy?", shape=diamond];
    multilingual [label="Multilingual\ncontent?", shape=diamond];
    resource_constrained [label="Resource\nconstraints?", shape=diamond];

    large_v3 [label="large-v3\nor\nlarge-v3-turbo", style="rounded,filled", fillcolor=lightblue];
    large_turbo [label="large-v3-turbo", style="rounded,filled", fillcolor=lightblue];
    distil_large [label="distil-large-v3.5\n(default)", style="rounded,filled", fillcolor=lightgreen];
    distil_medium [label="distil-medium.en", style="rounded,filled", fillcolor=lightyellow];
    distil_small [label="distil-small.en", style="rounded,filled", fillcolor=lightyellow];

    start -> need_accuracy;
    need_accuracy -> large_v3 [label="yes"];
    need_accuracy -> multilingual [label="no"];
    multilingual -> large_turbo [label="yes"];
    multilingual -> resource_constrained [label="no (English)"];
    resource_constrained -> distil_small [label="mobile/edge"];
    resource_constrained -> distil_medium [label="some limits"];
    resource_constrained -> distil_large [label="no"];
}

モデル一覧

標準モデル（Whisper フル版）

モデル	サイズ	速度	精度	用途
tiny / tiny.en	39M	最速	基本	手早い下書き
base / base.en	74M	非常に速い	良好	一般的な用途
small / small.en	244M	速い	より高い	ほとんどのタスク
medium / medium.en	769M	中程度	高い	高品質な文字起こし
large-v1/v2/v3	1.5GB	遅め	最高	最大限の精度
large-v3-turbo	809M	速い	非常に高い	高精度（distil より遅い）

蒸留モデル（約6倍高速、WER の差は約1%）

モデル	サイズ	標準モデルとの速度比較	精度	用途
distil-large-v3.5	756M	約6.3倍高速	WER 7.08%	デフォルト、最適なバランス
distil-large-v3	756M	約6.3倍高速	WER 7.53%	以前のデフォルト
distil-large-v2	756M	約5.8倍高速	WER 10.1%	フォールバック
distil-medium.en	394M	約6.8倍高速	WER 11.1%	英語専用、リソースが限られた環境
distil-small.en	166M	約5.6倍高速	WER 12.1%	モバイル／エッジデバイス

.en モデルは英語専用で、英語のコンテンツではわずかに高速かつ高精度です。

distil モデルに関する注意： HuggingFace は、繰り返しループを防ぐため、すべての distil モデルで condition_on_previous_text を無効にすることを推奨しています。スクリプトは distil-* モデルを検出すると、--no-condition-on-previous-text を自動的に適用します。必要に応じて --condition-on-previous-text を渡すと上書きできます。

カスタムモデルとファインチューニング済みモデル

WhisperModel は、ローカルの CTranslate2 モデルディレクトリと HuggingFace のリポジトリ名をそのまま受け入れるため、コードを変更する必要はありません。

ローカルの CTranslate2 モデルを読み込む

./scripts/transcribe audio.mp3 --model /path/to/my-model-ct2

HuggingFace モデルを CTranslate2 に変換する

pip install ctranslate2
ct2-transformers-converter \
  --model openai/whisper-large-v3 \
  --output_dir whisper-large-v3-ct2 \
  --copy_files tokenizer.json preprocessor_config.json \
  --quantization float16
./scripts/transcribe audio.mp3 --model ./whisper-large-v3-ct2

HuggingFace のリポジトリ名でモデルを読み込む（自動ダウンロード）

./scripts/transcribe audio.mp3 --model username/whisper-large-v3-ct2

カスタムモデルのキャッシュディレクトリ

デフォルトでは、モデルは ~/.cache/huggingface/ にキャッシュされます。--model-dir を使って変更できます。

./scripts/transcribe audio.mp3 --model-dir ~/my-models

セットアップ

Linux / macOS / WSL2

# Base install (creates venv, installs deps, auto-detects GPU)
./setup.sh

# With speaker diarization support
./setup.sh --diarize

要件：

• Python 3.10+
• 基本的な文字起こしに ffmpeg は不要です。faster-whisper にバンドルされている PyAV が音声のデコードを処理します。ffmpeg が必要なのは --burn-in、--normalize、--denoise の場合のみです。
• オプション：yt-dlp（URL／YouTube 入力用）
• オプション：pyannote.audio（--diarize 用。setup.sh --diarize でインストール）

プラットフォームのサポート

プラットフォーム	アクセラレーション	速度
Linux + NVIDIA GPU	CUDA	リアルタイムの約20倍 🚀
WSL2 + NVIDIA GPU	CUDA	リアルタイムの約20倍 🚀
macOS Apple Silicon	CPU*	リアルタイムの約3～5倍
macOS Intel	CPU	リアルタイムの約1～2倍
Linux（GPU なし）	CPU	リアルタイムの約1倍

*faster-whisper が使用する CTranslate2 は macOS では CPU のみですが、Apple Silicon なら実用上十分な速度です。

GPU サポート（重要！）

セットアップスクリプトは GPU を自動検出し、CUDA 対応の PyTorch をインストールします。利用可能な場合は必ず GPU を使用してください。CPU での文字起こしは非常に遅くなります。

ハードウェア	速度	9 分の動画
RTX 3070（GPU）	リアルタイムの約20倍	約27秒
CPU（int8）	リアルタイムの約0.3倍	約30分

RTX 3070 のヒント：ハイブリッド量子化には --compute-type int8_float16 を使用してください。品質をほとんど損なわずに VRAM を約1GB節約できます。文字起こしと並行して話者ダイアライゼーションを実行するのに最適です。

セットアップで GPU が検出されなかった場合は、PyTorch と CUDA を手動でインストールしてください。

# For CUDA 12.x
uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cu121

# For CUDA 11.x
uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cu118

• WSL2 ユーザー：Windows に NVIDIA CUDA drivers for WSL がインストールされていることを確認してください。

使用方法

# Basic transcription
./scripts/transcribe audio.mp3

# SRT subtitles
./scripts/transcribe audio.mp3 --format srt -o subtitles.srt

# WebVTT subtitles
./scripts/transcribe audio.mp3 --format vtt -o subtitles.vtt

# Transcribe from YouTube URL
./scripts/transcribe https://youtube.com/watch?v=dQw4w9WgXcQ --language en

# Speaker diarization
./scripts/transcribe meeting.wav --diarize

# Diarized VTT subtitles
./scripts/transcribe meeting.wav --diarize --format vtt -o meeting.vtt

# Prime with domain terminology
./scripts/transcribe lecture.mp3 --initial-prompt "Kubernetes, gRPC, PostgreSQL, NGINX"

# Batch process a directory
./scripts/transcribe ./recordings/ -o ./transcripts/

# Batch with glob, skip already-done files
./scripts/transcribe *.mp3 --skip-existing -o ./transcripts/

# Filter low-confidence segments
./scripts/transcribe noisy-audio.mp3 --min-confidence 0.6

# JSON output with full metadata
./scripts/transcribe audio.mp3 --format json -o result.json

# Specify language (faster than auto-detect)
./scripts/transcribe audio.mp3 --language en

オプション

Input:
  AUDIO                 Audio file(s), directory, glob pattern, or URL
                        Accepts: mp3, wav, m4a, flac, ogg, webm, mp4, mkv, avi, wma, aac
                        URLs auto-download via yt-dlp (YouTube, direct links, etc.)

Model & Language:
  -m, --model NAME      Whisper model (default: distil-large-v3.5; "turbo" = large-v3-turbo)
  --revision REV        Model revision (git branch/tag/commit) to pin a specific version
  -l, --language CODE   Language code, e.g. en, es, fr (auto-detects if omitted)
  --initial-prompt TEXT  Prompt to condition the model (terminology, formatting style)
  --prefix TEXT         Prefix to condition the first segment (e.g. known starting words)
  --hotwords WORDS      Space-separated hotwords to boost recognition
  --translate           Translate any language to English (instead of transcribing)
  --multilingual        Enable multilingual/code-switching mode (helps smaller models)
  --hf-token TOKEN      HuggingFace token for private/gated models and diarization
  --model-dir PATH      Custom model cache directory (default: ~/.cache/huggingface/)

Output Format:
  -f, --format FMT      text | json | srt | vtt | tsv | lrc | html | ass | ttml (default: text)
                        Accepts comma-separated list: --format srt,text writes both in one pass
                        Multi-format requires -o <dir> when saving to files
  --word-timestamps     Include word-level timestamps (wav2vec2 aligned automatically)
  --stream              Output segments as they are transcribed (disables diarize/alignment)
  --max-words-per-line N  For SRT/VTT, split segments into sub-cues of at most N words
  --max-chars-per-line N  For SRT/VTT/ASS/TTML, split lines so each fits within N characters
                        Takes priority over --max-words-per-line when both are set
  --clean-filler        Remove hesitation fillers (um, uh, er, ah, hmm, hm) and discourse markers
                        (you know, I mean, you see) from transcript text. Off by default.
  --detect-paragraphs   Insert paragraph breaks (blank lines) in text output at natural boundaries.
                        A new paragraph starts when: silence gap ≥ --paragraph-gap, OR the previous
                        segment ends a sentence AND the gap ≥ 1.5s.
  --paragraph-gap SEC   Minimum silence gap in seconds to start a new paragraph (default: 3.0).
                        Used with --detect-paragraphs.
  --channel {left,right,mix}
                        Stereo channel to transcribe: left (c0), right (c1), or mix (default: mix).
                        Extracts the channel via ffmpeg before transcription. Requires ffmpeg.
  --merge-sentences     Merge consecutive segments into sentence-level chunks
                        (improves SRT/VTT readability; groups by terminal punctuation or >2s gap)
  -o, --output PATH     Output file or directory (directory for batch mode)
  --output-template TEMPLATE
                        Batch output filename template. Variables: {stem}, {lang}, {ext}, {model}
                        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

出力形式

テキスト（デフォルト）

プレーンな文字起こしテキストです。--diarize を指定すると、話者ラベルが挿入されます。

[SPEAKER_1]
 Hello, welcome to the meeting.
[SPEAKER_2]
 Thanks for having me.

JSON（--format json）

セグメント、タイムスタンプ、言語検出、パフォーマンス統計などの完全なメタデータです。

{
  "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）

動画プレーヤー向けの標準字幕形式です。

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 形式です。

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）

タブ区切り値形式で、OpenAI Whisper と互換性があります。列は start_ms、end_ms、text です。

0	2500	Hello, welcome to the meeting.
2800	4200	Thanks for having me.

ほかのツールやスプレッドシートにパイプで渡す場合に便利です。ヘッダー行はありません。

ASS/SSA（--format ass）

Advanced SubStation Alpha 形式です。Aegisub、VLC、mpv、MPC-HC、およびほとんどの動画編集ソフトでサポートされています。[V4+ Styles] セクションでフォント、サイズ、色、位置を指定できるため、SRT より詳細なスタイル設定が可能です。

[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.

タイムスタンプは H:MM:SS.cc（センチ秒）形式です。文字起こしをやり直さずにフォント、色、位置をカスタマイズするには、Aegisub で [V4+ Styles] ブロックを編集してください。

LRC（--format lrc）

音楽プレーヤー（例：Foobar2000、VLC、AIMP）で使われる、タイムスタンプ付き歌詞形式です。タイムスタンプは [mm:ss.xx] 形式で、xx はセンチ秒です。

[00:00.50]Hello, welcome to the meeting.
[00:02.80]Thanks for having me.

話者ダイアライゼーションを有効にすると、話者ラベルが含まれます。

[00:00.50][SPEAKER_1] Hello, welcome to the meeting.
[00:02.80][SPEAKER_2] Thanks for having me.

デフォルトのファイル拡張子は .lrc です。音楽の文字起こし、カラオケ、音楽プレーヤーとの互換性があるタイムスタンプ付きテキストを必要とするあらゆるワークフローに便利です。

話者ダイアライゼーション

pyannote.audio を使用して、誰がいつ話したかを特定します。

セットアップ：

./setup.sh --diarize

要件：

• HuggingFace トークンが ~/.cache/huggingface/token にあること（huggingface-cli login）
• モデル利用規約への同意：
  • https://hf.co/pyannote/speaker-diarization-3.1
  • https://hf.co/pyannote/segmentation-3.0

使用方法：

# 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

話者には、最初に登場した順に SPEAKER_1、SPEAKER_2 などのラベルが付けられます。CUDA が利用可能な場合、話者ダイアライゼーションは自動的に GPU で実行されます。

高精度な単語タイムスタンプ

単語レベルのタイムスタンプが計算される場合（--word-timestamps、--diarize、または --min-confidence）、wav2vec2 の強制アライメント処理によって、Whisper の約100～200msの精度から約10msの精度に自動で調整されます。追加のフラグは不要です。

# 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

torchaudio の MMS（Massively Multilingual Speech）モデルを使用しており、1000以上の言語に対応しています。モデルは初回の読み込み後にキャッシュされるため、バッチ処理も高速です。

URL と YouTube の入力

任意の URL を入力として渡すと、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

yt-dlp が必要です（PATH と ~/.local/share/pipx/venvs/yt-dlp/bin/yt-dlp を確認します）。

バッチ処理

glob パターン、ディレクトリ、または複数のパスを指定して、複数のファイルを一度に処理できます。

# 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/

出力先にディレクトリを指定した場合、ファイル名は {input-stem}.{ext} になります（例：audio.mp3 → audio.srt）。

バッチモードでは、すべてのファイルの処理完了後に概要が表示されます。

📊 Done: 12 files, 3h24m audio in 10m15s (19.9× realtime)

ワークフロー

よく使われる用途向けのエンドツーエンドのパイプラインです。

ポッドキャスト文字起こしパイプライン

任意のポッドキャスト RSS フィードから最新の5エピソードを取得して文字起こしします。

# 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/

会議メモ作成パイプライン

話者ラベル付きで会議の録音を文字起こしし、整形されたテキストとして出力します。

# 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

動画字幕作成パイプライン

動画ファイルから、そのまま使える字幕を生成します。

# 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 バッチパイプライン

複数の YouTube 動画を一度に文字起こしします：

# 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

ノイズの多い音声のパイプライン

音質の悪い録音を文字起こしする前にクリーンアップします：

# 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/

バッチ復旧パイプライン

再試行を行いながら大きなフォルダーを処理します。失敗後も安全に再実行できます：

# 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

サーバーモード（OpenAI 互換 API）

speaches は faster-whisper を OpenAI 互換の /v1/audio/transcriptions エンドポイントとして実行します。ストリーミング、Docker 対応、ライブ文字起こしを備えた、OpenAI Whisper API のドロップイン置換です。

クイックスタート（Docker）

docker run --gpus all -p 8000:8000 ghcr.io/speaches-ai/speaches:latest-cuda

テストする

# Transcribe a file via the API (same format as OpenAI)
curl http://localhost:8000/v1/audio/transcriptions \
  -F [email protected] \
  -F model=Systran/faster-whisper-large-v3

任意の OpenAI SDK で使用する

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000", api_key="none")
with open("audio.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="Systran/faster-whisper-large-v3", file=f)
print(result.text)

Home Assistant、n8n、カスタムアプリなどの他のツール向けに、文字起こしをローカル API として公開したい場合に便利です。

よくある間違い

間違い	問題	解決策
GPU が利用可能なのに CPU を使用する	文字起こしが 10～20 倍遅くなります	nvidia-smi を確認し、CUDA のインストールを検証します
言語を指定しない	言語が既知のコンテンツでも自動検出に時間がかかります	言語がわかっている場合は --language en を使用します
誤ったモデルを使用する	不必要に遅くなる、または精度が低下します	デフォルトの distil-large-v3.5 は優れています。精度に問題がある場合のみ large-v3 を使用します
蒸留モデルを無視する	精度の低下が 1% 未満で速度が 6 倍になる利点を逃します	標準モデルを使う前に distil-large-v3.5 を試します
ffmpeg を忘れる	セットアップに失敗するか、音声を処理できません	セットアップスクリプトが対応します。手動でインストールする場合は ffmpeg が別途必要です
メモリ不足エラー	モデルが利用可能な VRAM/RAM に対して大きすぎます	小さいモデル、--compute-type int8、または --batch-size 4 を使用します
ビームサイズを過剰に調整する	ビームサイズ 5～7 を超えると効果が薄れます	デフォルトの 5 で問題ありません。重要な文字起こしでは 10 を試してください
pyannote なしで --diarize を使用する	実行時にインポートエラーが発生します	まず setup.sh --diarize を実行します
HuggingFace トークンなしで --diarize を使用する	モデルのダウンロードに失敗します	huggingface-cli login を実行し、モデルの利用規約に同意します
yt-dlp なしで URL を入力する	ダウンロードに失敗します	インストールします：pipx install yt-dlp
--min-confidence の値が高すぎる	自然な間がある良好なセグメントも除外されます	0.5 から始めて値を上げます。JSON 出力で確率を確認してください
基本的な文字起こしに --word-timestamps を使用する	大きな利点がないのに約 5～10 秒余計にかかります	単語レベルの精度が必要な場合のみ使用します
出力先ディレクトリに -o を指定せずにバッチ処理する	すべての出力が stdout に混在します	-o ./transcripts/ を使用し、入力ごとに 1 つのファイルへ書き込みます

パフォーマンスに関する注意事項

• 初回実行：モデルを ~/.cache/huggingface/ にダウンロードします（初回のみ）。
• バッチ推論：BatchedInferencePipeline によってデフォルトで有効です。標準モードより約3倍高速で、VAD もデフォルトで有効です。
• GPU：利用可能な場合は CUDA を自動的に使用します。
• 量子化：CPU では INT8 を使用し、精度をほとんど損なわずに約4倍高速化します。
• パフォーマンス統計：文字起こしごとに、音声の長さ、処理時間、リアルタイム係数が表示されます。
• ベンチマーク（RTX 3070、21分のファイル）：バッチ推論では約24秒（distil-large-v3 と v3.5 の両方）、使用しない場合は約69秒です。
• --precise のオーバーヘッド：wav2vec2 モデルの読み込みとアライメントに約5～10秒かかります（モデルはバッチ処理中にキャッシュされます）。
• 話者分離のオーバーヘッド：音声の長さに応じて約10～30秒かかります（利用可能な場合は GPU で実行します）。
• メモリ：
  • distil-large-v3：RAM 約2GB／VRAM 約1GB
  • large-v3-turbo：RAM 約4GB／VRAM 約2GB
  • tiny/base：RAM 1GB 未満
  • 話者分離：VRAM を追加で約1～2GB使用します。
• OOM：メモリ不足エラーが発生する場合は、--batch-size を小さくしてください（4をお試しください）。
• 事前の WAV 変換（任意）：ffmpeg -i input.mp3 -ar 16000 -ac 1 input.wav は、文字起こしの前に 16kHz のモノラル WAV に変換します。PyAV が効率よくデコードするため、1回だけ使う場合の効果はわずか（約5％）です。同じファイルを複数回再処理する場合（研究／実験）や、形式が原因で PyAV のデコードに問題が起きる場合に最も役立ちます。注：--normalize と --denoise は、すでにこの変換を自動的に実行します。
• Silero VAD V6：faster-whisper 1.2.1 で Silero VAD V6 にアップグレードされました（音声検出が改善されています）。適用するには ./setup.sh --update を実行してください。
• バッチ処理時の無音除去：faster-whisper 1.2.0 以降では、BatchedInferencePipeline（デフォルトで使用）で無音が自動的に除去されます。2024年8月より前にインストールした場合は、./setup.sh --update でアップグレードすると利用できます。

faster-whisper を選ぶ理由

• 速度：OpenAI のオリジナル版 Whisper より約4～6倍高速です。
• 精度：同等です（同じモデルの重みを使用します）。
• 効率性：量子化によりメモリ使用量を抑えます。
• 本番環境対応：安定した C++ バックエンド（CTranslate2）を使用します。
• 蒸留モデル：精度の低下を1％未満に抑えながら約6倍高速です。
• 字幕：SRT／VTT／HTML 形式でネイティブに出力します。
• 高精度アライメント：wav2vec2 による自動補正で、単語境界を約10msの精度で特定します。
• 話者分離：pyannote による話者識別を任意で利用できます。--speaker-names で実際の名前に対応付けられます。
• URL：YouTube／URL を直接入力できます。--keep-temp を指定するとダウンロードしたファイルを再利用できるよう保持します。
• カスタムモデル：ローカルの CTranslate2 ディレクトリまたは HuggingFace リポジトリを読み込めます。--model-dir でキャッシュの場所を指定します。
• 品質管理：--filter-hallucinations で、音楽／拍手のマーカーや重複を除去します。
• 並列バッチ処理：--parallel N でマルチスレッドのバッチ処理を行います。
• 字幕の焼き込み：--burn-in で ffmpeg を使用し、字幕を動画に直接重ねます。

v1.5.0 の新機能

複数形式での出力：

• --format srt,text — 1回の処理で複数の形式を書き出します（例：SRT とプレーンテキストを同時に出力）。
• カンマ区切りのリストを指定できます：srt,vtt,json、srt,text など。
• 複数の形式を書き出す場合は -o <dir> が必要です。単一形式の場合は変更ありません。

フィラー語の削除：

• --clean-filler — 文字起こしテキストから、ためらいの音（um、uh、er、ah、hmm、hm）と談話標識（you know、I mean、you see）を除去します。デフォルトでは無効です。
• 誤検出を避けるため、単語境界で保守的な正規表現マッチングを行います。
• クリーンアップ後に空になったセグメントは自動的に削除されます。

ステレオチャンネルの選択：

• --channel left|right|mix — 文字起こしの前に、特定のステレオチャンネルを抽出します（デフォルト：mix）。
• 2トラック録音（左がインタビュアー、右がインタビュイーなど）に便利です。
• ffmpeg の pan フィルターを使用します。ffmpeg が見つからない場合は、全体のミックスに適切にフォールバックします。

文字数に基づく字幕の折り返し：

• --max-chars-per-line N — 各行が N 文字以内に収まるように字幕キューを分割します。
• SRT、VTT、ASS、TTML 形式で動作し、--max-words-per-line より優先されます。
• 単語単位のタイムスタンプが必要です。単語データがない場合は、セグメント全体にフォールバックします。

段落の検出：

• --detect-paragraphs — 自然な区切りでテキスト出力に段落区切り \n\n を挿入します
• --paragraph-gap SEC — 段落として区切る最小無音時間（デフォルト：3.0s）
• 直前のセグメントが文末で終わり、ギャップが 1.5s 以上の場合も段落区切りを検出します

字幕形式：

• --format ass — Advanced SubStation Alpha（Aegisub、VLC、mpv、MPC-HC）
• --format lrc — 音楽プレーヤー向けのタイムスタンプ付き歌詞形式
• --format html — 単語ごとに信頼度を色分けした HTML 文字起こし（緑／黄／赤）
• --format ttml — W3C TTML 1.0（DFXP）放送標準（Netflix、Amazon Prime、BBC）
• --format csv — ヘッダー行付きのスプレッドシート対応 CSV。RFC 4180 に準拠した引用符処理。話者分離時は speaker 列を追加します

文字起こしツール：

• --search TERM — 単語／フレーズが出現するすべてのタイムスタンプを検索します。通常の出力を置き換えます。保存するには -o を指定します
• --search-fuzzy — --search で近似／部分一致検索を行います
• --detect-chapters — 無音区間からチャプター区切りを自動検出します。--chapter-gap SEC（デフォルト：8s）
• --chapters-file PATH — 標準出力ではなくファイルにチャプターを書き込みます。--chapter-format youtube|text|json
• --export-speakers DIR — --diarize の実行後、ffmpeg を使って各話者の発話を個別の WAV ファイルとして保存します

バッチ処理の改善：

• ETA — 順次バッチ処理では、各ファイルの処理前に [N/total] filename | ETA: Xm Ys を表示します。フラグは不要です
• --language-map "pat=lang,..." — ファイルごとに言語を上書きします。fnmatch グロブパターンに対応し、@file.json 形式も使用できます
• --retries N — 失敗したファイルを指数バックオフで再試行します。最後に失敗したファイルの概要を表示します
• --rss URL — ポッドキャストの RSS フィードを文字起こしします。エピソード数は --rss-latest N で指定します
• --skip-existing / --parallel N / --output-template / --stats-file / --merge-sentences

モデルと推論：

• デフォルトを distil-large-v3.5 に変更しました（distil-large-v3 から置き換え）
• distil モデルでは condition_on_previous_text を自動的に無効化します（繰り返しループを防止）
• 上書きするには --condition-on-previous-text を指定します。ライブラリのデバッグ出力には --log-level を指定します
• --model-dir PATH — HuggingFace のキャッシュディレクトリをカスタム指定します。ローカルの CTranslate2 モデルに対応します
• --no-timestamps、--chunk-length、--length-penalty、--repetition-penalty、--no-repeat-ngram-size
• --clip-timestamps、--stream、--progress、--best-of、--patience、--max-new-tokens
• --hotwords、--prefix、--revision、--suppress-tokens、--max-initial-timestamp

話者と品質：

• --speaker-names "Alice,Bob" — SPEAKER_1/2 を実名に置き換えます（--diarize が必要です）
• --filter-hallucinations — 音楽／拍手のマーカー、重複、「Thank you for watching」を削除します
• --burn-in OUTPUT — ffmpeg を使って字幕を動画に焼き込みます
• --keep-temp — URL からダウンロードした音声を再処理用に保持します

セットアップ：

• setup.sh --check — システム診断：GPU、CUDA、Python、ffmpeg、pyannote、HuggingFace トークンを確認します（約 12s で完了）
• 基本的な文字起こしでは ffmpeg が不要になりました（PyAV がデコードを処理します）。これを反映して skill.json を更新しました（ffmpeg は optionalBins に変更されています）

トラブルシューティング

「CUDA not available — using CPU」：PyTorch を CUDA 対応でインストールしてください（上記の GPU サポートを参照）。 セットアップに失敗する場合：Python 3.10 以降がインストールされていることを確認してください。 メモリ不足の場合：より小さいモデルを使用するか、--compute-type int8 または --batch-size 4 を指定してください。 CPU で遅い場合：想定される動作です。実用的な文字起こしには GPU を使用してください。 モデルのダウンロードに失敗する場合：~/.cache/huggingface/ の権限を確認してください。 話者分離モデルに失敗する場合：HuggingFace トークンが存在し、モデルの利用規約に同意していることを確認してください。 または、--hf-token hf_xxx でトークンを直接渡してください。 URL のダウンロードに失敗する場合：yt-dlp がインストールされていることを確認してください（pipx install yt-dlp）。 バッチ処理で音声ファイルが見つからない場合：ファイル拡張子がサポート対象の形式と一致していることを確認してください。 インストール済みのバージョンを確認する：./scripts/transcribe --version を実行してください。 faster-whisper をアップグレードする：./setup.sh --update を実行してください（その場でアップグレードされ、完全な再インストールは不要です）。 無音や音楽で幻覚が発生する場合：--temperature 0.0 --no-speech-threshold 0.8 を試してください。 VAD が音声を正しく分割しない場合：--vad-threshold 0.3（値を下げる）または --min-silence-duration 300 で調整してください。 音声検出を改善する：./setup.sh --update を実行して、faster-whisper を最新バージョンにアップグレードしてください（Silero VAD V6 が含まれます）。

参考資料

• faster-whisper GitHub
• Distil-Whisper 論文
• HuggingFace モデル
• pyannote.audio（話者分離）
• yt-dlp（URL／YouTube のダウンロード）