Oma Voice

Voice Skill - Local TTS and STT via Voicebox

Scheduling

Goal

Drive the Voicebox local app through its MCP server so any MCP-aware agent can speak (TTS) or listen (STT) without invoking cloud vendors. The skill standardizes intent routing, voice profile resolution, output layout, and guardrails while voicebox itself owns the engines, voice cloning UI, captures archive, and stories editor.

Intent signature

• User asks to generate speech, narrate text, produce a voiceover, create an mp3 or wav from text.
• User wants an audio file transcribed into text, meeting notes, or a transcript.
• User asks for a voice notification when a long task completes or a workflow step is blocked.
• Another skill needs local audio generation infrastructure.

When to use

• Generating short notification audio for agent task completion or blockers.
• Producing voiceover, narration, or audio assets (mp3 or wav) for apps and content.
• Transcribing local audio files (mp3, wav, m4a, webm, flac) to Markdown.
• Comparing voice profiles by re-running the same text against different profile ids.

When NOT to use

• Cloud TTS or high-fidelity multilingual cloud voices -> out of scope; future multi-vendor extension.
• Real-time microphone dictation loop in the terminal -> use Voicebox app's built-in hotkey dictation.
• Voice cloning sample upload and profile creation -> done in the Voicebox desktop app UI.
• Video synthesis, music, sound design -> out of scope.
• Stories Editor multi-voice timeline composition -> use the Voicebox app UI.

Expected inputs

• TTS: text (<= 5000 chars per call), optional profile id, optional engine, optional language, optional output path.
• STT: audio file path (absolute or relative to $CWD), optional language hint.
• Notification: short message (<= 240 chars), profile id resolved from config.

Expected outputs

• TTS: audio file (mp3 default, wav optional) at .agents/results/voice/{timestamp}-{shortid}/output.{mp3|wav} plus manifest.json.
• STT: transcript.md at .agents/results/voice/transcripts/{timestamp}-{shortid}/ plus manifest.json.
• Notification: ephemeral playback through Voicebox; no disk write by default.

Dependencies

• Voicebox desktop app installed and running locally.
• Voicebox MCP registered (claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp).
• At least one voice profile created in the Voicebox app UI.
• Optionally pre-downloaded engine models for the selected profile.

Control-flow features

• Branches by mode (notify, asset, transcribe), language, and profile availability.
• Calls voicebox via MCP tools, with REST GET /health as the handshake probe.
• Reads input audio files and writes generated audio plus manifests.
• Caches discovered MCP tool names after the first successful tools/list.

Structural Flow

Entry

1. Detect the requested mode: notification, asset TTS, or transcription. 2. Verify Voicebox is reachable via MCP handshake or GET /health. 3. On the first run only, call MCP tools/list and cache the resolved tool names. 4. Resolve the target voice profile id (notification, asset, or explicit user choice).

Scenes

1. PREPARE: Validate text length, audio duration, language, output path, and profile id. 2. ACQUIRE: If a required signal is missing, run the clarification protocol once. 3. ACT: Invoke the appropriate MCP tool (TTS or STT) with the resolved parameters. 4. VERIFY: Confirm the response carries audio output or transcript content. Validate manifest fields. 5. FINALIZE: Write manifest.json alongside the output. Report the path or transcript to the user.

Transitions

• If voicebox is unreachable, surface the install or launch hint and exit. Do not attempt auto-relaunch.
• If voicebox_list_profiles is empty, point the user at the Voicebox app UI to create a profile, then exit.
• If a TTS request exceeds 5000 chars, ask whether to truncate or split. Do not auto-chunk in v1.
• If an STT input exceeds 30 minutes, ask whether to proceed. Do not auto-split.
• If the selected engine model is not loaded, ask the user before triggering a download.

Failure and recovery

Exit

• Success: audio file or transcript exists with a complete manifest, and the path is reported.
• Partial success: output exists but a guardrail warning is surfaced (length, disk, model fallback).
• Failure: no output, the blocker (auth, profile, engine, network) is explicit.

Logical Operations

Actions

Tools and instruments

• Voicebox MCP server at http://127.0.0.1:17493/mcp.
• REST surface for health and audio retrieval (GET /health, GET /audio/{generation_id}).
• Resource references: voice matrix, prompt tips, execution protocol, checklist.

Canonical command path

# 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. Resolve profile
MCP voicebox_list_profiles          ->  pick profile by name or config default

# 4. Generate or transcribe
MCP voicebox_speak     { text, profile, language?, engine?, personality? }
MCP voicebox_transcribe { audio_path | audio_base64, language?, model? }

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

MCP tool mapping (verified against Voicebox 0.5.0)

Tools not exposed via MCP (REST only): model status (GET /models/status), audio file serving (GET /audio/{generation_id}). The skill calls those over loopback HTTP when needed.

Notes on `voicebox_speak`:

• Required: text. Optional: profile, engine, language, personality (bool).
• Audio plays on the user speakers and is saved to the Captures / History panel automatically. There is no save_to_disk toggle on the MCP tool itself.
• Without a default profile set in Voicebox Settings, profile= is required.

Notes on `voicebox_transcribe`:

• Accepts exactly one of audio_base64 or audio_path (loopback only). Optional language, model.

Resource scope

Preconditions

• Voicebox app is running and the MCP handshake succeeds.
• At least one voice profile exists.
• The selected engine model is loaded or the user approves a download.
• Output directory is inside $PWD unless explicitly allowed.

Effects and side effects

• Creates audio files, transcripts, and manifests under .agents/results/voice/.
• Triggers local Voicebox generation, which consumes CPU or GPU.
• May trigger an engine model download when the user approves.
• Does not call any cloud service. No external network traffic.

Guardrails

1. Voicebox required: if the MCP handshake or GET /health fails, exit with a one-shot install or launch hint. Do not retry, do not auto-relaunch. 2. Profile required: if voicebox_list_profiles returns empty, instruct the user to create a profile in the Voicebox app (Profiles tab → + New Profile → pick Kokoro preset for the fastest path), then exit. 3. Tool-name discovery: on first invocation, call MCP tools/list and cache the resolved names. Reuse the cache for subsequent calls in the same session. 4. Length limits: TTS calls cap at 5000 chars per call; warn at 2000. STT inputs cap at 30 minutes. v1 does not auto-chunk or auto-split. 5. Auto-invocation transparency: notifications fire automatically only when the active task exceeds auto_notify_after_sec (default 60s). Always announce intent in one short line before generating audio. 6. Path safety: when the user requests an output path outside $PWD, warn once and require explicit confirmation. 7. Cancellation: SIGINT aborts the MCP call and writes no partial output. 8. Manifest required: every generation writes manifest.json with at minimum: skill, mode, voicebox_generation_id, text (or transcript_preview), profile, engine, language, format (TTS only), created_at. 9. Out of scope: voice cloning UI, captures archive, stories editor, microphone dictation loop, and cloud vendors are intentionally not exposed. 10. No cost guard: Voicebox is free. The cost guardrail from oma-image does not apply.

Clarification protocol

Before invoking a TTS or STT call, the agent checks the following. If any required signal is missing, clarify with the user first.

TTS (asset mode) required:

• [ ] Text content provided?
• [ ] Voice profile id or tone description provided?

TTS strongly recommended:

• [ ] Language explicit or detectable from the text?
• [ ] Output format (mp3 default, wav optional)?

STT required:

• [ ] Audio path provided and the file exists?
• [ ] Duration within 30 minutes, or user approves splitting?

Notification mode skips clarification. It uses notification_profile from config and language is auto-detected from the message.

Invocation

Standalone

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

Shared infrastructure (other skills)

Other skills can request audio output by calling the same MCP tools directly, or by invoking /oma-voice with their text. There is no separate CLI; the skill is MCP-native.

References

• Voice engine matrix: resources/voice-matrix.md
• Prompt writing rules: resources/prompt-tips.md
• Execution protocol: resources/execution-protocol.md
• Pre-flight checklist: resources/checklist.md
• Configuration: config/voice-config.yaml
• Context loading: ../_shared/core/context-loading.md
• Quality principles: ../_shared/core/quality-principles.md
• Design reference: ../../../docs/plans/designs/012-oma-voice.md (source repo only; absent in global-mode installs)

Pre-flight Checklist

Run this check before every TTS or STT call. The agent should be able to answer "yes" to every applicable item, or surface a clarification before invoking voicebox.

Environment

• [ ] Voicebox desktop app is running.
• [ ] GET http://127.0.0.1:17493/health returned 200 within 5 seconds.
• [ ] Voicebox MCP server is registered with the host CLI.

Profiles and models

• [ ] At least one voice profile exists (cached from voicebox_list_profiles).
• [ ] Target profile id is resolved for the current mode (explicit > config default > user choice).
• [ ] Engine model for the resolved profile is loaded, or the user approved a download.

Inputs

• [ ] Mode (notify, asset, transcribe) is identified.
• [ ] TTS text length is within the mode limit (notify <= 240, asset <= 5000).
• [ ] STT audio path exists and is one of the supported formats.
• [ ] STT audio duration is within 30 minutes, or the user approved splitting.
• [ ] Language is set to auto or to a single explicit BCP-47 code.

Output

• [ ] Output directory is inside $PWD, or the user explicitly confirmed an external path.

Safety

• [ ] Auto-invocation announcement was emitted (one short pre-line) if the call is automatic.
• [ ] The user has not asked to suppress notifications in the current session.
• [ ] No partial output from a prior cancellation is being overwritten.

Manifest

• [ ] All required manifest fields (skill, mode, voicebox_generation_id, profile, engine, language, created_at) can be populated.
• [ ] Mode-specific field is set: text for TTS, transcript_preview for STT.
• [ ] format is set for TTS manifests.

Post-call

• [ ] Output file exists and is non-empty.
• [ ] Duration in the manifest matches the audio (or the transcript word count looks plausible).
• [ ] User-facing report includes mode, path, duration, and any warning.

Execution Protocol

This file lays out the runtime sequence for every oma-voice call. SKILL.md gives the high-level scenes; this file is the operational checklist the agent executes.

Step 0: Mode detection

Detect one of three modes from the user request:

If the signal is ambiguous, ask one question before proceeding.

Step 1: Health check

1. Probe GET http://127.0.0.1:17493/health with a 5-second timeout (configurable). 2. On success, continue to Step 2. 3. On failure, surface this hint and exit with code 5:

   Voicebox is not reachable. Install or launch the Voicebox desktop app
   from GitHub Releases (https://github.com/jamiepine/voicebox/releases).
   Voicebox is not in Homebrew.
     - Apple Silicon: download Voicebox_<ver>_aarch64.dmg
     - Intel Mac:     download Voicebox_<ver>_x64.dmg
     - Windows:       Voicebox_<ver>_x64-setup.exe
   Then register the MCP server:
     claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp

Step 2: Tool discovery cache

Verified Voicebox MCP tool names (as of v0.5.0):

tts        -> voicebox_speak
stt        -> voicebox_transcribe
profiles   -> voicebox_list_profiles
captures   -> voicebox_list_captures

Model status and audio retrieval are REST-only at the Voicebox app, not exposed as MCP tools. Call them over loopback HTTP when needed:

• GET http://127.0.0.1:17493/models/status
• GET http://127.0.0.1:17493/audio/{generation_id}

On the first call in this session:

1. Invoke MCP tools/list on the voicebox server. 2. Confirm all four tool names above are present. 3. If a required tool is missing, exit with code 4 and surface the gap. Voicebox may have renamed a tool in a newer release.

Step 3: Profile resolution

1. Call the cached profiles tool. 2. If the list is empty, surface this hint and exit with code 3:

   No voice profile found in Voicebox.
   Create one in the app UI (cloning or preset), then retry.

3. Resolve the target profile in this order: 1. Explicit profile argument from the user. 2. notification_profile from voice-config.yaml when mode is notify. 3. asset_profile from voice-config.yaml when mode is asset and the user did not specify one. 4. Else ask the user which profile to use.

Step 4: Clarification (asset and transcribe modes only)

Run the checklist from SKILL.md > Clarification protocol. Notification mode skips this step.

Step 5: Length and duration guard

Step 6: Model availability (optional)

For asset and notify modes:

1. Call the cached models tool. 2. If the selected engine reports loaded: false, ask the user before triggering a download. Voicebox owns the download flow; this skill only relays the prompt.

Step 7: Invoke MCP tool

TTS path

MCP call: voicebox_speak
  text:        <normalized text, required>
  profile:     <resolved profile name from voicebox_list_profiles>
  language:    <auto or explicit; optional>
  engine:      <optional engine override>
  personality: <optional bool>

Voicebox plays the audio on the user speakers and saves a capture entry automatically. The tool returns a generation id; the audio file lives inside the Voicebox app's Captures panel and is also reachable over loopback at GET /audio/{generation_id} when a local copy is needed.

STT path

MCP call: voicebox_transcribe
  audio_path:    <absolute local path; loopback only>
  # OR
  audio_base64:  <base64-encoded audio bytes>
  language:      <auto or explicit; optional>
  model:         <optional model override>

Expected response: transcript text and detected language. Pass exactly one of audio_path or audio_base64.

Step 8: Persist output and manifest

TTS output

.agents/results/voice/<YYYYMMDD-HHMMSS>-<shortid>/
├── output.mp3
└── manifest.json

STT output

.agents/results/voice/transcripts/<YYYYMMDD-HHMMSS>-<shortid>/
├── transcript.md
└── manifest.json

Manifest shape

TTS:

{
  "skill": "oma-voice",
  "mode": "tts",
  "voicebox_generation_id": "gen_abc123",
  "text": "...",
  "profile": "Nova",
  "engine": "kokoro",
  "language": "en",
  "format": "mp3",
  "duration_sec": 7.4,
  "created_at": "2026-05-15T09:15:33+09:00"
}

STT:

{
  "skill": "oma-voice",
  "mode": "stt",
  "voicebox_generation_id": "gen_def456",
  "transcript_preview": "first 200 chars...",
  "source_path": "/abs/path/to/input.mp3",
  "profile": null,
  "engine": "whisper",
  "language": "ko",
  "duration_sec": 312.0,
  "created_at": "2026-05-15T09:18:20+09:00"
}

For notification mode no manifest is required: Voicebox auto-saves the clip to its Captures panel and that is the system of record.

Step 9: Report

Report to the user in one short message:

• Mode (notify / tts / stt)
• Output path (or "played" for ephemeral notifications)
• Duration in seconds
• Any warnings (length truncated, disk warn fired, model fallback used)

Error code mapping

Mirror oma-image exit codes:

Cancellation

On SIGINT or SIGTERM:

1. Send an abort signal to the in-flight MCP call when supported. 2. Do not write partial output. 3. Exit with the originating signal's conventional code.

Idempotency

• Two identical TTS calls produce two separate generations and two separate output folders. The skill does not de-duplicate.
• Voicebox's own History panel tracks all generations; users can prune it from the app UI.

Prompt Writing Rules for TTS

These rules apply to the text that the agent sends to Voicebox. STT input is audio, so these tips cover only the TTS side.

Core rules

1. Plain text only. Do not include SSML tags. Voicebox does not advertise SSML support; tags will either be read aloud or stripped silently. Use punctuation, line breaks, and pacing words to control delivery. 2. One call per logical thought. Keep a sentence intact rather than splitting mid-clause across MCP calls. Voicebox prosody works best on whole sentences. 3. Strip markdown markers before sending. Remove #, *, _, backticks, list bullets, and table characters. They have no audible meaning and add awkward pauses. 4. Strip emojis. Voicebox usually reads them as the literal Unicode name, which sounds wrong. Replace with the intended word when relevant ("success" instead of a check mark). 5. Mixed-language text stays in a single call. Pick a multilingual engine. Splitting Korean and English into separate calls breaks intonation and timing.

Punctuation and pacing

• Use a comma where you want a short breath. Use a period for a longer stop.
• A blank line between paragraphs produces a longer pause than punctuation alone.
• Avoid stacked exclamation marks. Voicebox treats them as a single emphatic stop. Use one when emphasis matters.
• Use ellipsis sparingly for hesitation. Three dots ... works; one dot does not.

Numbers, units, and acronyms

• Spell out numbers when natural reading matters: "삼 킬로그램" rather than "3kg", or "three kilograms" rather than "3 kg".
• Decimals: keep digit form when context is data-heavy ("0.42 percent"), spell out when conversational ("nearly half").
• Currency: write the symbol where readers expect it ("$12.50") and let Voicebox handle the read-out. If Voicebox misreads, switch to spelled form ("twelve dollars fifty").
• Acronyms: spell out the first occurrence when the meaning matters ("Application Programming Interface, A P I"). For short notifications, leave well-known acronyms as is.

Notifications

• One sentence, fewer than 240 characters.
• Lead with the outcome: "Build succeeded, 4 minor warnings" rather than "I have completed the build process and there are 4 minor warnings".
• Do not stack adjectives. "Tests passed" beats "All the tests have now successfully passed".
• Skip filler ("just to let you know that"). Time is the entire value of a voice notification.

Asset narration

• Read the text aloud yourself before sending. Awkward phrasing becomes obvious.
• Prefer active voice. Voicebox handles passive voice but it stretches the pacing.
• Where ambiguity exists ("read" past vs present), reword. Voicebox cannot disambiguate from context alone.

Caveats

• These are recommendations, not hard validators. The skill does not strip markdown or emojis automatically in v1; the calling agent should normalize text before invoking the MCP tool.
• If a future Voicebox release supports SSML or prosody hints, revisit rule 1 and add a section on supported tags.

Voice Engine Matrix

Voicebox bundles seven engines. All run locally; the user picks one when creating a voice profile in the Voicebox app, and the skill respects that choice. This matrix exists so the agent can recommend a profile-engine pair when the user has not yet decided.

Engine comparison

Picks by use case

Language-first rules

• Korean text: prefer Qwen3-TTS. If Korean mixes English technical terms, stay on Qwen3-TTS rather than switching engines mid-sentence.
• English text: Kokoro for clean defaults; Chatterbox Turbo when emotion tags or character voices matter.
• Mixed sentences: pick a multilingual engine and keep the call as a single request. Splitting hurts prosody.
• Bottom-tier hardware: LuxTTS or Kokoro stay snappy without a GPU.
• Long-form narration (over 5 minutes total in chunks): prefer TADA or Chatterbox Turbo for sustained expression; reserve Kokoro for short bursts.

Profile selection heuristic

1. If the user passes an explicit profile argument, use it. 2. Else use notification_profile (notify mode) or asset_profile (asset mode) from voice-config.yaml. 3. Else use the first available profile from voicebox_list_profiles whose engine matches the detected language pick in the table above. 4. Else exit with a setup hint pointing the user to the Voicebox app Profiles tab.

Caveats

• Engine names above are the ones Voicebox surfaces in its UI. If voicebox renames an engine, the skill defers to whatever get_model_status returns.
• Voice cloning quality depends on the reference sample voicebox captured. The skill does not judge sample quality; it routes by language only.
• Some engines auto-download large model weights on first use. Trigger the download from the Voicebox app UI to keep the agent loop responsive.