oma-voice

音声スキル - Voicebox によるローカル TTS と STT

スケジュール

目標

Voicebox のローカルアプリを MCP サーバー経由で操作し、MCP 対応のエージェントがクラウドベンダーを呼び出さずに音声を生成（TTS）したり、音声を聞き取ったり（STT）できるようにします。このスキルでは、意図の振り分け、音声プロファイルの解決、出力レイアウト、ガードレールを標準化します。一方、エンジン、音声クローニングの UI、キャプチャのアーカイブ、ストーリーエディターは Voicebox 自体が管理します。

意図のシグネチャ

• 音声の生成、テキストのナレーション、ナレーション音声の作成、テキストからの mp3 または wav の生成を依頼された場合。
• 音声ファイルをテキスト、会議メモ、または書き起こしに変換するよう依頼された場合。
• 長時間のタスクが完了したとき、またはワークフローのステップがブロックされたときに音声通知を求められた場合。
• 別のスキルがローカル音声生成のインフラストラクチャを必要とする場合。

使用する場面

• エージェントのタスク完了やブロックを知らせる短い通知音声の生成。
• アプリやコンテンツ向けのナレーション、朗読、音声アセット（mp3 または wav）の作成。
• ローカルの音声ファイル（mp3、wav、m4a、webm、flac）の Markdown への書き起こし。
• 同じテキストを異なるプロファイル ID に対して再実行し、音声プロファイルを比較する場合。

使用しない場面

• クラウド TTS や高忠実度の多言語クラウド音声 → 対象外です。将来的にマルチベンダー拡張を予定しています。
• ターミナルでのリアルタイムなマイク音声入力ループ → Voicebox アプリ内蔵のホットキー音声入力を使用してください。
• 音声クローニング用サンプルのアップロードやプロファイルの作成 → Voicebox デスクトップアプリの UI で行います。
• 動画生成、音楽、サウンドデザイン → 対象外です。
• ストーリーエディターでの複数音声タイムラインの構成 → Voicebox アプリの UI を使用してください。

想定される入力

• TTS：テキスト（1 回の呼び出しにつき最大 5000 文字）、任意のプロファイル ID、エンジン、言語、出力パス。
• STT：音声ファイルのパス（絶対パス、または $CWD からの相対パス）、任意の言語ヒント。
• 通知：短いメッセージ（最大 240 文字）、設定から解決されたプロファイル ID。

想定される出力

• TTS：.agents/results/voice/{timestamp}-{shortid}/output.{wav|mp3} に音声ファイル（wav — Voicebox のネイティブ TTS 出力形式。mp3 はローカルの ffmpeg による変換で任意に指定可能）と manifest.json。
• STT：.agents/results/voice/transcripts/{timestamp}-{shortid}/ に transcript.md と manifest.json。
• 通知：Voicebox 経由で一時的に再生します。デフォルトではディスクに書き込みません。

依存関係

• Voicebox デスクトップアプリがインストールされ、ローカルで実行されていること。
• Voicebox MCP が登録されていること（claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp）。
• TTS のみ：Voicebox アプリの UI で、少なくとも 1 つの音声プロファイルが作成されていること。
• TTS のみ：選択したプロファイル用のエンジンモデルが事前にダウンロードされていること（任意）。

制御フローの機能

• モード（通知、アセット、文字起こし）、言語、プロファイルの有無に応じて分岐します。
• MCP ツール経由で Voicebox を呼び出し、ハンドシェイクのプローブとして REST GET /health を使用します。
• 入力音声ファイルを読み込み、生成した音声とマニフェストを書き込みます。
• 最初の tools/list 成功後に、検出した MCP ツール名をキャッシュします。

構造フロー

開始

1. 依頼されたモードを検出します：通知、アセット TTS、または文字起こし。
2. MCP ハンドシェイクまたは GET /health を通じて Voicebox に到達できることを確認します。
3. 初回実行時のみ、MCP tools/list を呼び出し、解決したツール名をキャッシュします。
4. 通知またはアセット TTS の場合は、対象の音声プロファイル ID を解決します。文字起こしの場合は、音声入力を検証し、プロファイルなしで続行します。

シーン

1. 準備：テキストの長さ、音声の再生時間、言語、出力パス、プロファイル ID を検証します。
2. 取得：必要な情報が不足している場合は、確認プロトコルを 1 回実行します。
3. 実行：解決済みのパラメーターを使って、適切な MCP ツール（TTS または STT）を呼び出します。
4. 検証：応答に音声出力または文字起こしの内容が含まれていることを確認します。マニフェストのフィールドを検証します。
5. 完了：出力とともに manifest.json を書き込みます。パスまたは文字起こしをユーザーに報告します。

遷移

• Voicebox に接続できない場合は、インストールまたは起動方法のヒントを提示して終了します。自動再起動は試みません。
• TTS リクエストで使用可能なプロファイルがない場合は、Voicebox アプリの UI でプロファイルを作成するようユーザーに案内してから終了します。文字起こしリクエストではプロファイルは不要です。
• TTS リクエストが 5000 文字を超える場合は、切り詰めるか分割するかを尋ねます。v1 では自動的に分割しません。
• STT 入力が 30 分を超える場合は、続行するか尋ねます。自動分割はしません。
• 選択したエンジンモデルが読み込まれていない場合は、ダウンロードを開始する前にユーザーに確認します。

失敗と復旧

失敗	復旧方法
Voicebox アプリが起動していない	インストール／起動方法のヒントを表示し、終了コード 5 で終了
TTS 用の音声プロファイルがない	「Voicebox でプロファイルを作成してください」というヒントを表示し、終了コード 3 で終了
エンジンモデルがない	ダウンロードを開始する前に確認
出力パスが $PWD の外にある	明示的に指定されたパスを使用します。宛先が曖昧な場合、または無関係なデータを上書きする場合に限り確認
TTS が 5000 文字を超える	分割するか切り詰めるかをユーザーに尋ねる
STT が 30 分を超える	リクエストされた時間またはリソースコストが未確定の場合に限り確認
MCP ツール名の不一致	tools/list を再実行してキャッシュを更新
SIGINT	MCP 呼び出しを中止し、不完全な出力は書き込まない

終了条件

• 成功：完全なマニフェストを伴う音声ファイルまたは文字起こしが存在し、そのパスが報告されている。
• 部分的な成功：出力は存在するものの、ガードレールの警告（長さ、ディスク、モデルのフォールバック）が提示されている。
• 失敗：出力がなく、阻害要因（認証、プロファイル、エンジン、ネットワーク）が明示されている。

論理操作

アクション

アクション	SSL プリミティブ	根拠
モードと入力を検証する	VALIDATE	execution-protocol.md の確認プロトコル
TTS 音声プロファイルを解決する	SELECT	voicebox_list_profiles と設定のデフォルト
ヘルスチェック	READ	MCP ハンドシェイクまたは GET /health
音声を生成する	CALL_TOOL	MCP voicebox_speak
音声を文字起こしする	CALL_TOOL	MCP voicebox_transcribe
出力とマニフェストを書き込む	WRITE	音声または文字起こしと manifest.json
結果を検査する	VALIDATE	出力の存在、長さ、マニフェストのフィールド
結果を報告する	NOTIFY	ユーザー向けの最終要約

ツールと関連機能

• http://127.0.0.1:17493/mcp にある Voicebox MCP サーバー。
• ヘルスチェックと音声取得用の REST インターフェース（GET /health、GET /audio/{generation_id}）。
• リソース参照：音声マトリックス、プロンプトのヒント、実行プロトコル、チェックリスト。

標準的なコマンドパス

# 1. MCP handshake or REST health
GET http://127.0.0.1:17493/health  ->  200 OK

# 2. Discover tool names on first run
MCP tools/list                      ->  cache real names

# 3. TTS only: resolve profile
MCP voicebox_list_profiles          ->  pick profile by name or config default

# 4. Generate or transcribe (STT skips profile lookup and model-status check)
MCP voicebox_speak     { text, profile, language?, engine?, personality? }
MCP voicebox_transcribe { audio_path | audio_base64, language?, model? }

# 5. Fetch the generated audio (MCP has no save-to-disk; TTS output is wav)
GET http://127.0.0.1:17493/audio/{generation_id}  ->  wav bytes

# 6. Persist output + manifest
.agents/results/voice/<timestamp>-<shortid>/output.wav + manifest.json
.agents/results/voice/transcripts/<timestamp>-<shortid>/transcript.md + manifest.json

MCP ツールの対応関係（Voicebox 0.5.0 で検証済み）

用途	MCP ツール	対応する REST
TTS 生成	voicebox_speak	POST /speak
STT 文字起こし	voicebox_transcribe	POST /transcribe
プロファイル一覧	voicebox_list_profiles	GET /profiles
キャプチャ一覧	voicebox_list_captures	GET /history（キャプチャビュー）

MCP では公開されていないツール（REST のみ）：モデルの状態（GET /models/status）、音声ファイルの提供（GET /audio/{generation_id}）、バージョン別の音声（GET /audio/version/{version_id}）。必要に応じて、スキルはループバック HTTP 経由でこれらを呼び出します。

voicebox_speak に関する注意事項：

• 必須：text。任意：profile、engine、language、personality（bool）。
• 音声はユーザーのスピーカーで再生され、自動的に Captures / History パネルに保存されます。MCP ツール自体には save_to_disk の切り替え機能はありません。ローカルコピーを保存するには、GET /audio/{generation_id} で取得してください（Voicebox TTS は常に wav を保存します）。
• Voicebox Settings でデフォルトプロファイルが設定されていない場合、profile= が必須です。

voicebox_transcribe に関する注意事項：

• audio_base64 または audio_path（ループバックのみ）のいずれか一方を指定します。任意：language、model。

リソースの範囲

範囲	リソースの対象
LOCAL_FS	入力音声、生成音声、文字起こし、マニフェスト
PROCESS	ローカルの Voicebox アプリのサブプロセス（ユーザーが管理）
NETWORK	127.0.0.1:17493 へのループバック HTTP のみ
MEMORY	キャッシュされた MCP ツール名、解決済みのプロファイルメタデータ
CREDENTIALS	なし。Voicebox はローカルで、キーは不要です。

前提条件

• Voicebox アプリが起動しており、MCP ハンドシェイクが成功していること。
• TTS のみ：少なくとも 1 つの音声プロファイルが存在すること。
• TTS のみ：選択したエンジンモデルが読み込まれているか、ユーザーがダウンロードを承認していること。
• 出力ディレクトリは、明示的に許可されていない限り $PWD の内側にあること。

影響と副作用

• .agents/results/voice/ の下に音声ファイル、文字起こし、マニフェストを作成します。
• CPU または GPU を消費するローカルの Voicebox 生成を実行します。
• ユーザーが承認した場合、エンジンモデルのダウンロードが実行されることがあります。
• クラウドサービスは呼び出しません。外部へのネットワーク通信はありません。

ガードレール

1. Voicebox が必須：MCP ハンドシェイクまたは GET /health が失敗した場合、インストールまたは起動を促すヒントを 1 回だけ表示して終了します。再試行や自動再起動は行いません。
2. TTS のみプロファイルが必須：通知モードまたはアセットモードの場合に限り、プロファイルを解決して TTS エンジンを確認します。プロファイルが存在しなくても、有効な音声入力と任意の STT モデルがあれば文字起こしを続行します。
3. ツール名の検出：初回の呼び出し時に MCP tools/list を呼び出し、解決済みの名前をキャッシュします。同じセッション内の以降の呼び出しではキャッシュを再利用します。
4. 長さの上限：TTS の呼び出しは 1 回あたり最大 5000 文字で、2000 文字で警告します。STT 入力は最大 30 分です。v1 では自動チャンク化や自動分割は行いません。
5. 自動呼び出しの透明性：アクティブなタスクが auto_notify_after_sec（デフォルトは 60 秒）を超えた場合にのみ、通知を自動的に行います。このしきい値はエージェントが適用する目安であり、タスクの所要時間を測定するフックはありません。そのため、長時間のタスクが完了またはブロックされた際に、判断して適用してください。音声を生成する前に、必ず意図を短い一文で伝えてください。
6. パスの安全性：出力パスが明示的に指定された場合、その場所への書き込みが許可されます。依存する書き込みを行う前に、曖昧さや無関係なデータの置き換えを解決してください。必須の CLI パスフラグは維持してください。
7. キャンセル：SIGINT により MCP 呼び出しを中止し、部分的な出力は書き込みません。
8. 永続化する出力にはマニフェストが必須：アセット TTS モードと文字起こしモードでは、最低限、skill、mode、voicebox_generation_id、text（または transcript_preview）、profile、engine、language、format（TTS のみ）、created_at を含む manifest.json を書き込みます。通知モードは例外です。Voicebox Captures が記録システムであり、デフォルトではディスクに出力を書き込みません。
9. 対象範囲外：ボイスクローニング UI、captures アーカイブ、ストーリーエディター、マイクによるディクテーションループ、クラウドベンダーは意図的に公開していません。
10. コストガードなし：Voicebox は無料です。oma-image のコストガードレールは適用されません。

明確化の手順

TTS または STT を呼び出す前に、エージェントは以下を確認します。必須の情報が不足している場合は、まずユーザーに確認してください。

TTS（アセットモード）で必須：

• テキストの内容が提供されていますか？
• 音声プロファイル ID または声の特徴の説明が提供されていますか？

TTS で強く推奨：

• 言語が明示されているか、テキストから判別できますか？
• 出力形式が指定されていますか（デフォルトは wav、mp3 にはローカルでの ffmpeg トランスコードが必要です）？

STT で必須：

• 音声パスが指定され、ファイルが存在しますか？
• 再生時間は 30 分以内ですか？それとも、ユーザーが分割を承認していますか？

**通知モードでは確認を省略します。**設定の notification_profile を使用し、言語はメッセージから自動検出します。

呼び出し

単独で使用

/oma-voice "build succeeded, 4 minor warnings"
/oma-voice transcribe ~/Downloads/standup.m4a
/oma-voice --profile prof_warm_korean "다음 단계 진행 준비됐어요"

共有インフラストラクチャ（他のスキル）

他のスキルは、同じ MCP ツールを直接呼び出すか、テキストを指定して /oma-voice を呼び出すことで、音声出力を要求できます。独立した CLI はありません。このスキルは MCP ネイティブです。

参考資料

• 音声エンジンの一覧：resources/voice-matrix.md
• プロンプト作成のルール：resources/prompt-tips.md
• 実行プロトコル：resources/execution-protocol.md
• 実行前チェックリスト：resources/checklist.md
• 設定：まず .agents/oma-config.yaml の voice: セクションを読み込み、設定されていないキーについては config/voice-config.yaml を参照します。どちらのプロファイルも初期状態では null のため、マシンごとに設定する必要があります。oma update によってスキル設定が上書きされるため、.agents/oma-config.yaml に記述してください。
• コンテキストの読み込み：../_shared/core/context-loading.md
• 品質原則：../_shared/core/quality-principles.md
• デザインの参考資料：../../../docs/plans/designs/012-oma-voice.md（ソースリポジトリのみ。グローバルモードのインストールには含まれません）