media-transcriber

media-transcriber — 音声・動画の文字起こし

作者：43 COLLEGE 凯寓 (KAIYU) 制作 バージョン：v1.0

OpenAI Whisper を使用して、動画・音声ファイルをタイムスタンプ付きの文字起こしに変換します。話者識別と Claude による句読点復元に対応しています。

初回実行時には、仮想環境の作成、依存関係のインストール、Whisper モデルのダウンロード（turbo で約 1.5GB）が自動で行われます。すべて自動で完了し、手動での設定は不要です。

重要：初回の文字起こしの前に、必ずユーザーへ事前に伝えてください——モデルのダウンロードと依存関係のインストールには 5～15 分かかる場合があります（回線速度によります）。その間、ターミナルに長時間新しい出力が表示されないことがありますが、これはフリーズではありません。文字起こしコマンドを実行する前に必ずこの点をユーザーに説明し、ユーザーが途中で強制中断して環境が破損するのを防いでください。

実行時に ffmpeg が見つからないというエラーが出た場合や、話者識別の設定が必要な場合は、SETUP.md を読んで初回設定を完了してください。

クロスプラットフォーム互換性

項目	macOS / Linux	Windows
Python	python3	python
パス区切り文字	/	\
スクリプトパス	${CLAUDE_SKILL_DIR}/scripts/transcribe.py	${CLAUDE_SKILL_DIR}\scripts\transcribe.py

${CLAUDE_SKILL_DIR} について：これはドキュメント上のプレースホルダーで、本 skill のインストールディレクトリ（通常は ~/.claude/skills/media-transcriber/）を表します。Claude が bash でコマンドを実行する際に実際のパスへ自動的に置き換えます。ユーザーはこの文字列をそのままターミナルにコピーしないでください——そのままコピー＆ペーストすると、変数が未定義のために失敗します。コマンドを AI に実行させるか、ご自身で具体的なディレクトリに置き換えてください。

呼び出し方

品質モード（デフォルト推奨）

話者識別 + Claude 句読点復元付きで、正式なコンテンツの蓄積に適しています。速度はリアルタイムの約 1/2（turbo モデル、CPU）です。

# 预检环境和权限（推荐首次运行）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py --check

# 质量模式：说话人识别 + 标点恢复
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate

# 指定说话人数量（不指定则自动检测）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --speakers 2

# 整个文件夹批量转录（质量模式）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "/path/to/folder" --language zh --diarize --punctuate

# 强制覆盖已有逐字稿
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --overwrite

Python インライン呼び出し：

import sys; sys.path.insert(0, f"{CLAUDE_SKILL_DIR}/scripts")
from transcribe import transcribe_file

transcribe_file("video.mp4", language="zh", diarize=True, punctuate=True)

高速モード

話者識別なし、句読点復元なしで、速度は 3～5 倍速く、コンテンツの素早いプレビューに適しています。

# 快速模式：仅转录，无说话人，无标点
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh

# Windows 快速模式
python ${CLAUDE_SKILL_DIR}\scripts\transcribe.py "C:\path\to\video.mp4" --language zh

環境情報

• 仮想環境: 初回実行時に skill ディレクトリの venv/ に自動作成されます
• モデル保存先: models/（ローカル化されており、システムキャッシュに依存しません）
• 自動インストール: openai-whisper, numpy<2.4, numba, anthropic
• オンデマンドインストール: pyannote-audio（--diarize 時のみインストール）
• GPU: CUDA がない場合は自動的に CPU にフォールバックします

モデル選択

モデル	サイズ	CPU 速度	中国語品質	用途
turbo	1.5GB	リアルタイムの約 2 倍	優秀	デフォルト推奨
medium	1.4GB	リアルタイムの約 3 倍	良好	turbo の代替
small	461MB	リアルタイムの約 1 倍	普通	速度重視
base	139MB	リアルタイムの約 0.3 倍	やや不良	素早いプレビュー

「N 倍のリアルタイム」= 1 分の音声の処理に N 分かかる（CPU）

出力形式

各ファイルごとに <元のファイル名>_逐字稿.txt を生成します：

話者識別なし（デフォルト）：

# 文件名

[00:00 - 00:05] 文本内容
[00:05 - 00:12] 文本内容

---

# 完整文本

完整的文本内容。

話者識別あり（--diarize）：

# 文件名

**[说话人A]**
[00:00 - 00:05] 文本内容

**[说话人B]**
[00:05 - 00:12] 文本内容

---

# 完整文本

[说话人A] 第一段话内容。
[说话人B] 第二段话内容。

対応形式：.mp4 .mkv .avi .mov .wmv .flv .webm .mp3 .wav .flac .aac .ogg .m4a .wma

主要な設計

• 自動 bootstrap: 初回実行時に自動で venv を作成して依存関係をインストールします。以降は python3 で直接呼び出すだけでよく、activate は不要です
• ハルシネーション防止: condition_on_previous_text=False でエラーの伝播を防ぎ、ffprobe の長さで超過セグメントをフィルタリングします
• 句読点ガイド: --language zh を指定すると、自動的に initial_prompt を注入して句読点の出力を促します
• Claude 句読点復元: --punctuate で Claude Haiku を呼び出し、全文に対して全体的な句読点復元を行います
• 話者マッチング: 時間の重なり量に基づいて、Whisper のセグメントを pyannote の話者セグメントにマッチングします
• オンデマンドインストール: pyannote-audio はサイズが大きいため、--diarize 使用時のみ自動インストールします
• モデルのローカル化: Whisper モデルは models/ ディレクトリに保存され、download_root を介して読み込まれます

既知の制限

1. NumPy バージョン: numba は numpy<2.4 を必要とするため、自動インストール時にバージョンを固定しています
2. 長尺動画のメモリ: 2 時間を超える動画では、turbo モデルで約 4～6GB の RAM が必要です
3. BGM: 末尾の純粋な音楽区間で、少量の誤認識が残る場合があります
4. 話者識別の精度: 複数人が同時に話すと正確率が低下します
5. 句読点復元の速度: Claude API の呼び出しに約 3～10 秒の遅延があります