ドキュメントを更新し、型注釈を追加してコードの可読性とメンテナンス性を向上。各モジュールの使用例や依存関係を明示化し、エラーハンドリングを改善。

src-python/docs/modules/transcription.md

@@ -1,3 +1,78 @@
+## 文字起こしモジュール (models.transcription)
+
+このドキュメントでは `models/transcription` に関する設計・セットアップ・使用例・テスト方針・トラブルシュートをまとめます。
+
+### 概要
+- `models/transcription` は音声入力をテキストに変換する機能を提供します。主に:
+  - `transcription_recorder.py` — マイクやスピーカからの音声取得ラッパー
+  - `transcription_transcriber.py` — 音声バッファを認識エンジンに渡して文字起こしを行うロジック
+  - `transcription_whisper.py` — faster-whisper（WhisperModel）周りのダウンロード/ロード補助
+  - `transcription_languages.py` — 各言語・国別のエンジン別コードマップ
+
+### 最近の変更点
+- 各モジュールに型注釈と docstring を追加しました。これによりメンテナンス性が向上します。
+- `transcription_whisper.py` にダウンロード進捗コールバックを明記した実装を追加しました。
+
+### 依存関係
+主要な依存:
+- `speech_recognition` — オーディオ録音と Google 音声認識のラッパー
+- `pyaudiowpatch` — クロスプラットフォームのオーディオ設定
+- `pydub` — 音声のチャンネル変換や処理
+- `faster_whisper`（オプショナル）— ローカルで Whisper を使う場合
+- `huggingface_hub`（オプショナル）— モデルアーティファクトのダウンロード
+
+注意: `pydub` は `ffmpeg` が必要です。環境に ffmpeg が無いとワーニングが出ます。
+
+推奨インストール（任意）:
+
+```powershell
+pip install speechrecognition pyaudiowpatch pydub faster-whisper huggingface-hub
+```
+
+テストでは多くの外部依存をモックするため、全てをインストールする必要はありません。
+
+### 初回セットアップ
+1. 必要に応じて `ffmpeg` をインストールしてください（pydub の動作に必要）。
+2. Whisper ローカルモデルを使う場合、`transcription_whisper.downloadWhisperWeight(root, weight_type, callback, end_callback)` を呼んでモデルを取得します。
+   - `callback(progress: float)` は 0.0〜1.0 の進捗通知です。
+   - 例:
+
+```python
+from models.transcription import transcription_whisper as tw
+tw.downloadWhisperWeight("./", "tiny", callback=lambda p: print(f"{p*100:.1f}%"), end_callback=lambda: print("done"))
+```
+
+### API 使用例
+簡単な `AudioTranscriber` の使い方:
+
+```python
+from models.transcription.transcription_transcriber import AudioTranscriber
+
+# source はライブラリが提供するオーディオソースオブジェクト
+tr = AudioTranscriber(speaker=False, source=source, phrase_timeout=3, max_phrases=10, transcription_engine="Google")
+# audio_queue は録音スレッドがプッシュするキュー
+tr.transcribeAudioQueue(audio_queue, languages=["English"], countries=["United States"]) 
+```
+
+戻り値やエラー処理のルールについては各関数の docstring を参照してください。
+
+### テスト方針
+- `AudioTranscriber` と `Whisper` ラッパーはユニットテストでモック化して検証します。
+- 推奨: `pytest` と `unittest.mock` を使い、以下のケースをカバーします:
+  - 正常系: Google/Whisper の成功パス（モックで期待テキストを返す）
+  - エッジ: 無音、低確信、複数言語
+  - フォールバック: Whisper が利用不可の場合のフォールバック動作
+
+### トラブルシュート
+- ffmpeg が見つからない: `pydub` がワーニングを出します。OS に合わせて ffmpeg をインストールしてください。
+- Whisper のロード時に VRAM エラー: `getWhisperModel` は VRAM 不足を検出して `ValueError("VRAM_OUT_OF_MEMORY", message)` を投げます。デバイス設定や compute_type を調整してください。
+- ハッシュ不一致やダウンロード失敗: キャッシュや weights ディレクトリを削除して再ダウンロードしてください。
+
+### 変更履歴
+- 2025-10-09: 型注釈と docstring を追加、ダウンロード/コールバック仕様を明記。
+
+---
+このドキュメントは簡潔な参照用です。さらに詳細な実行手順（ログ収集方法、ffmpeg のインストール手順例など）が必要であれば追記します。
 # transcription — 文字起こしモジュール
 概要: マイク/スピーカー音声の録音と Whisper/Google などのエンジンを使った文字起こしを提供するモジュール群です。主なクラスは録音用の Recorder と `AudioTranscriber` です。