oliverv/caro / .agents/skills/oma-voice
oma-voice
VerifiedGenerate speech or transcribe audio locally with Voicebox. Use for narration, voice assets, dictation, and meeting transcription.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| config/voice-config.yaml | config | 1.2 KB |
| resources/checklist.md | markdown | 1.8 KB |
| resources/execution-protocol.md | markdown | 7.0 KB |
| resources/prompt-tips.md | markdown | 3.0 KB |
| resources/voice-matrix.md | markdown | 3.4 KB |
resources/execution-protocol.md
View on GitHub# 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:
| Signal | Mode |
|---|---|
| Short message after a long task, "tell me when done", "음성으로 알려줘" | `notify` |
| "Generate a voiceover", "make an mp3", "narrate this text", explicit length over a sentence | `asset` |
| Audio file path provided plus a "transcribe", "회의록", "받아 적어" intent | `transcribe` |
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.
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 the tool required by the selected mode: `voicebox_transcribe` for `transcribe`, or
`voicebox_speak` and `voicebox_list_profiles` for `notify` and `asset`. `captures` is optional.
3. If a required tool is missing, exit with code 4 and surface the gap. A missing profile tool
must not block transcription. Voicebox may have renamed a tool in a newer release.
## Step 3: TTS profile resolution
Run this step only for `notify` and `asset` modes. `transcribe` has no profile
parameter: skip directly to its audio checks and then `voicebox_transcribe`.
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
| Mode | Check | Action |
|---|---|---|
| `notify` | `len(text) <= 240` | Truncate with ellipsis; warn user |
| `asset` | `len(text) <= 5000` | Ask user to split or truncate if exceeded |
| `transcribe` | audio duration <= 30 min | Ask user to confirm if exceeded |
## Step 6: Model availability (optional)
For `asset` and `notify` modes only:
1. Probe `GET http://127.0.0.1:17493/models/status` over loopback REST (model status is not exposed as an MCP tool — see Step 2).
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
```text
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
```text
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
The MCP tool has no save-to-disk: fetch the generated audio over loopback REST
(`GET /audio/{generation_id}`) and write it as `output.wav` — Voicebox stores
TTS generations as wav. If the user asked for mp3, transcode locally with
ffmpeg after the fetch and record `"format": "mp3"` in the manifest.
```text
.agents/results/voice/<YYYYMMDD-HHMMSS>-<shortid>/
├── output.wav
└── manifest.json
```
### STT output
```text
.agents/results/voice/transcripts/<YYYYMMDD-HHMMSS>-<shortid>/
├── transcript.md
└── manifest.json
```
### Manifest shape
TTS:
```json
{
"skill": "oma-voice",
"mode": "tts",
"voicebox_generation_id": "gen_abc123",
"text": "...",
"profile": "Nova",
"engine": "kokoro",
"language": "en",
"format": "wav",
"duration_sec": 7.4,
"created_at": "2026-05-15T09:15:33+09:00"
}
```
STT:
```json
{
"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:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic failure |
| 2 | Safety block (currently unused; reserved) |
| 3 | Resource not found (no profile, missing audio file) |
| 4 | Invalid input (length, format, MCP tool missing) |
| 5 | Auth or environment required (voicebox not reachable) |
| 6 | Timeout |
## 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |