oma-voice

Voice Skill - 音声とローカル音声処理

スケジューリング

目標

ローカルのVoiceboxアプリを通じて音声を生成・文字起こしし、ローカルのメディアツールで既存の音声を処理します。合成エンジンとプロファイルはVoiceboxが管理し、ファイル変換、長さの調整、ラウドネス処理はFFmpegが担当します。

インテントのシグネチャ

• ユーザーが音声の生成、テキストのナレーション、ボイスオーバーの作成、テキストからのmp3またはwavの作成を依頼している。
• ユーザーが音声ファイルをテキスト、会議メモ、またはトランスクリプトに文字起こししたい。
• ユーザーが長時間のタスクの完了時やワークフローの手順がブロックされたときに、音声通知を求めている。
• 別のスキルがローカル音声生成のインフラストラクチャを必要としている。
• ユーザーが既存の音声を指定の時間枠に合わせたり、リサンプリング、変換、またはラウドネス正規化したりする必要がある。

使用する場合

• エージェントのタスク完了やブロッカー通知用の短い音声を生成する場合。
• アプリやコンテンツ用のボイスオーバー、ナレーション、音声アセット（mp3またはwav）を作成する場合。
• ローカル音声ファイル（mp3、wav、m4a、webm、flac）をMarkdownに文字起こしする場合。
• 同じテキストを異なるプロファイルIDで再実行して、音声プロファイルを比較する場合。
• oma-videoの吹き替えジョブで使用する音声など、既存の音声アセットを処理する場合。

使用しない場合

• クラウドTTSや高忠実度の多言語クラウド音声 -> 対象外です。将来的なマルチベンダー拡張の対象です。
• ターミナルでのリアルタイムマイク入力によるディクテーションループ -> Voiceboxアプリ内蔵のホットキーによるディクテーションを使用してください。
• 音声クローン用サンプルのアップロードとプロファイルの作成 -> VoiceboxデスクトップアプリのUIで行います。
• 動画編集と音声・動画の配置 -> oma-videoを使用してください。音楽とサウンドデザインは対象外です。
• Stories Editorでの複数音声タイムライン構成 -> VoiceboxアプリのUIを使用してください。

想定される入力

• TTS：テキスト（1回あたり<= 5000文字）、任意のプロファイルID、任意のエンジン、任意の言語、任意の出力パス。
• STT：音声ファイルのパス（絶対パス、または$CWDからの相対パス）、任意の言語ヒント。
• 通知：短いメッセージ（<= 240文字）、設定から解決されるプロファイルID。
• 処理：既存の音声パス、要求する操作、および指定された長さ、サンプルレート、チャンネル構成、ラウドネス、またはフォーマットの制約。普遍的なマスタリングプリセットではなく、依頼内容から目標を導き出してください。

想定される出力

• TTS：.agents/results/voice/{timestamp}-{shortid}/output.{wav|mp3}に音声ファイル（wav — VoiceboxネイティブのTTS出力形式。ローカルのffmpegでトランスコードすることで、任意でmp3にもできます）とmanifest.jsonを出力します。
• STT：.agents/results/voice/transcripts/{timestamp}-{shortid}/にtranscript.mdとmanifest.jsonを出力します。
• 通知：Voiceboxを通じて一時的に再生します。デフォルトではディスクに書き込みません。
• 処理：別の処理済み音声ファイルと、ソースおよび出力のパス、操作、測定した音声特性を含むmanifest.jsonを出力します。ソースは変更せずに保持してください。生成IDを含めるのは、Voiceboxが実際に音声を生成した場合のみです。

依存関係

• 処理のみ：ffmpegとffprobeがインストールされていること。Voiceboxアプリや音声プロファイルは不要です。
• 生成・文字起こし：Voiceboxデスクトップアプリがインストールされ、ローカルで実行中であること。
• 生成・文字起こしのみ：Voicebox MCPが登録されていること（claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp）。
• TTSのみ：VoiceboxアプリのUIで少なくとも1つの音声プロファイルが作成されていること。
• TTSのみ：選択したプロファイル用のエンジンモデルを事前にダウンロードしておくこともできます。

制御フローの機能

• モード（notify、asset、transcribe）、言語、プロファイルの利用可否に応じて分岐します。
• MCPツール経由でvoiceboxを呼び出し、ハンドシェイクの確認にはREST GET /healthを使用します。
• 入力音声ファイルを読み込み、生成した音声とマニフェストを書き込みます。
• 最初に成功したtools/listの後、検出したMCPツール名をキャッシュします。

構造フロー

エントリー

1. 要求されたモードを検出します。通知、アセットの TTS、文字起こし、既存音声の処理のいずれかです。処理の場合は、Voicebox のヘルスチェック、プロファイル、モデルの確認を行う前に、resources/audio-processing.md の手順に従います。
2. MCP ハンドシェイクまたは GET /health で、Voicebox に到達できることを確認します。
3. 初回のみ、MCP の tools/list を呼び出し、解決したツール名をキャッシュします。
4. 通知またはアセットの TTS の場合は、対象の音声プロファイル ID を解決します。文字起こしの場合は、音声入力を検証し、プロファイルなしで続行します。

シーン

1. PREPARE：操作とその入力を解決します。Voicebox の各モードでは、テキストまたは音声と言語を使用します。TTS にはさらにプロファイルが必要です。ファイル処理では、ソースと要求されたメディア属性を使用します。
2. ACQUIRE：必須の情報が不足している場合は、確認プロトコルを一度実行します。
3. ACT：適切な MCP ツール（TTS または STT）を呼び出すか、ローカルの FFmpeg コマンドで既存のアセットを処理します。
4. VERIFY：応答に音声出力または文字起こしの内容が含まれていることを確認します。マニフェストのフィールドを検証します。
5. FINALIZE：出力と同じ場所に manifest.json を書き込みます。パスまたは文字起こしをユーザーに報告します。

遷移

• 音声の生成または文字起こしで Voicebox に到達できない場合は、インストールまたは起動のヒントを提示して終了します。自動再起動は試みないでください。既存ファイルの処理は Voicebox なしで続行します。
• ループバックアドレスは、プロセス自身のホストまたはコンテナを指します。ホストの Voicebox サービスを呼び出す場合はホストから実行し、生成されたファイルをタスクコンテナに転送します。コンテナの 127.0.0.1 ではホストアプリを確認できません。
• 時間指定のナレーションでは、生の生成結果を保持します。対応言語の利用可能なプロファイルを選択し、生の音声の長さを測定して、フィッティングには resources/audio-processing.md を使用します。ニューラルエンジンの使用や適切なラウドネスだけでは、自然な発音や韻律が保証されません。
• TTS リクエストに使用可能なプロファイルがない場合は、Voicebox アプリの UI でプロファイルを作成するようユーザーに案内してから終了します。文字起こしのリクエストにプロファイルは必要ありません。
• TTS リクエストが 5000 文字を超える場合は、切り詰めるか分割するかをユーザーに尋ねます。v1 では自動分割しないでください。
• STT 入力が 30 分を超える場合は、続行するかユーザーに尋ねます。自動分割しないでください。
• 選択したエンジンモデルが読み込まれていない場合は、ダウンロードを開始する前にユーザーに尋ねます。

失敗と復旧

失敗	復旧
Voicebox アプリが起動していない	インストールまたは起動のヒントを表示し、終了コード 5 で終了します
TTS 用の音声プロファイルがない	「Voicebox でプロファイルを作成してください」というヒントを表示し、終了コード 3 で終了します
エンジンモデルがない	ダウンロードを開始する前に確認します
出力パスが $PWD の外にある	明示的に要求されたパスを使用します。保存先が曖昧な場合、または無関係なデータを上書きする場合にのみ確認します
TTS が 5000 文字を超える	分割するか切り詰めるか、ユーザーに尋ねます
STT が 30 分を超える	要求された長さまたはリソースコストが未確定の場合にのみ確認します
MCP ツール名の変更	tools/list を再実行し、キャッシュを更新します
SIGINT	MCP 呼び出しを中断し、部分的な出力は書き込みません
ローカルメディア実行ファイルがない	要求された操作に必要なツールがないことを報告します。Voicebox を起動したり、音声をプレースホルダーに置き換えたりしないでください
音声が自然に収まらない	生の音声を保持します。合成が利用可能で許可されている場合は生成時のペースを調整するか、単語を切り取るのではなく、解決できていない時間の制約を報告します

終了

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

論理操作

アクション

アクション	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 サーバー、既存の音声にはローカルの FFmpeg と ffprobe を使用します。
• ヘルスチェックと音声の取得には REST エンドポイント（GET /health、GET /audio/{generation_id}）を使用します。
• リソースの参照先：音声マトリックス、プロンプトのヒント、実行プロトコル、チェックリスト。

標準的なコマンドパス

既存音声の処理は resources/audio-processing.md に振り分けます。以下のパスは Voicebox での生成／書き起こし専用です。タイミング指定の TTS は、生の WAV を取得した後、処理リファレンスに従います。

# 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 アプリ（ユーザーが管理）、FFmpeg／ffprobe による処理
NETWORK	127.0.0.1:17493 へのループバック HTTP のみ
MEMORY	キャッシュされた MCP ツール名、解決済みのプロファイルメタデータ
CREDENTIALS	なし。Voicebox はローカルで動作し、キーは不要です。

前提条件

• 処理：ローカルの ffmpeg と ffprobe でソースアセットを読み取れること。
• 生成／書き起こし：Voicebox アプリが実行中で、MCP ハンドシェイクが成功すること。
• TTS のみ：音声プロファイルが 1 つ以上存在すること。
• TTS のみ：選択したエンジンモデルが読み込まれているか、ユーザーがダウンロードを承認していること。
• 明示的に許可されていない限り、出力ディレクトリは $PWD 内であること。

影響と副作用

• .agents/results/voice/ 以下に音声ファイル、書き起こし、マニフェストを作成します。
• 既存音声の処理ではローカルのメディアサブプロセスを実行し、入力ファイルを保持します。
• ローカルの Voicebox による生成を実行し、CPU または GPU を使用します。
• ユーザーが承認した場合、エンジンモデルのダウンロードが実行されることがあります。
• クラウドサービスは呼び出しません。外部ネットワーク通信はありません。

ガードレール

1. Voicebox のモード：生成／文字起こしには MCP ハンドシェイクまたは GET /health が必要です。失敗した場合は、インストールまたは起動方法を一度だけ案内して終了します。再試行や自動再起動は行いません。ローカル処理に Voicebox は必要ありません。
2. プロファイルが必要なのは TTS のみ：通知モードまたはアセットモードの場合に限り、プロファイルを解決し、TTS エンジンを確認します。有効な音声入力と任意の STT モデルがあれば、プロファイルがなくても文字起こしを実行します。
3. ツール名の検出：Voicebox を初めて呼び出す際に、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 を書き込みます。処理では resources/audio-processing.md に指定されたとおりにソース、操作、測定した出力プロパティを記録し、Voicebox の来歴を捏造することはありません。通知モードは例外です。Voicebox Captures が記録システムであり、デフォルトではディスクに出力を書き込まないためです。
9. 対象範囲外：音声クローン UI、キャプチャアーカイブ、ストーリーエディター、マイクによるディクテーションループ、クラウドベンダーは、意図的に公開していません。
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（TTS プロファイル／エンジンの選択）
• プロンプト作成ルール：resources/prompt-tips.md（TTS テキスト）
• 実行プロトコル：resources/execution-protocol.md（Voicebox による生成／文字起こし）
• 既存の音声とタイミング付きナレーション：resources/audio-processing.md（処理、長さの調整、または指定された音量への変換）
• 事前チェックリスト：resources/checklist.md（Voicebox の呼び出し）
• 設定：まず .agents/oma-config.yaml の voice: セクションを読み込み、そのセクションで設定されていないキーは config/voice-config.yaml を参照します。両方のプロファイルは null の状態で提供されるため、マシンごとに設定する必要があります。oma update によってスキル設定が上書きされるため、.agents/oma-config.yaml に記述してください。
• コンテキストの読み込み：references/_shared/core/context-loading.md
• 品質原則：references/_shared/core/quality-principles.md
• デザインリファレンス：../../../docs/plans/designs/012-oma-voice.md（ソースリポジトリのみ。グローバルモードでのインストールには含まれません）