oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-voice/resources/execution-protocol.md

@@ -0,0 +1,215 @@
+# Execution Protocol
+
+This file lays out the Voicebox generation/transcription sequence. Existing-audio processing dispatches to `audio-processing.md` before the health check; it does not require Voicebox or a profile.
+
+## 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` |
+| Existing audio plus conversion, loudness, or duration fitting | `process`: use `audio-processing.md`; skip the Voicebox steps below |
+
+If the signal is ambiguous, ask one question before proceeding.
+
+## Step 1: Health check
+
+Resolve `voice.backend` first (`resources/voicestudio.md`). When it selects
+VoiceStudio, follow that resource instead of Steps 1-3 and 6-7; the remaining
+steps still apply.
+
+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 with `voice.backend: auto`, probe VoiceStudio as described in
+   `resources/voicestudio.md`. With `voice.backend: voicebox`, or when no
+   backend is healthy, 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.

package/skills/oma-voice/resources/prompt-tips.md

@@ -0,0 +1,43 @@
+# 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.

package/skills/oma-voice/resources/voice-matrix.md

@@ -0,0 +1,51 @@
+# Voice Engine Matrix
+
+This matrix covers the Voicebox backend. On VoiceStudio, discover installed engines and their languages from the running backend instead (`voicestudio.md`).
+
+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
+
+| Engine | Languages | Strengths | Best for | Weight | Notes |
+|---|---|---|---|---|---|
+| Qwen3-TTS | 10, strong CJK | Natural CJK prosody, fast on consumer GPU | Korean, Japanese, Chinese narration | Medium | First choice for mixed CJK content |
+| Qwen CustomVoice | 9 presets | Quick start, no sample needed | Demo and prototyping in CJK | Medium | Limited tonal variety |
+| LuxTTS | English only | Lightweight, CPU-friendly | Low-resource machines, quick notifications | Light | Less expressive than Kokoro |
+| Chatterbox Multilingual | 23 | Broad coverage, decent quality | Multilingual content, mixed sentences | Medium-Heavy | Slower than Kokoro on CPU |
+| Chatterbox Turbo | English | Emotion tags, expressive delivery | Character voices, podcast intros | Medium | Best with voice cloning |
+| TADA (HumeAI) | 10 | Strong emotional range, narration cadence | Audiobook, story narration | Heavy | Largest models, GPU recommended |
+| Kokoro | 8, 50 preset voices | Polished English, dependable defaults | Notifications and short English assets | Light-Medium | Default English fallback |
+
+## Picks by use case
+
+| Use case | First choice | Second choice |
+|---|---|---|
+| Korean notification | Qwen3-TTS | Chatterbox Multilingual |
+| English notification | Kokoro | LuxTTS |
+| Japanese or Chinese narration | Qwen3-TTS | Chatterbox Multilingual |
+| Mixed-language sentence | Chatterbox Multilingual | Qwen3-TTS |
+| CPU-only laptop, short clips | LuxTTS | Kokoro |
+| Expressive narration | TADA | Chatterbox Turbo |
+| Character voice or cloned voice | Chatterbox Turbo + cloning | Qwen CustomVoice |
+| Quick voiceover, English | Kokoro | Chatterbox Turbo |
+
+## 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 REST `GET /models/status` returns (model status is not exposed as an MCP tool).
+- 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.

package/skills/oma-voice/resources/voicestudio.md

@@ -0,0 +1,87 @@
+# VoiceStudio Backend
+
+Use this branch when `voice.backend` resolves to VoiceStudio
+(`https://github.com/debpalash/VoiceStudio`), a local speech backend with
+voice cloning, voice design, transcription and dubbing. Voicebox steps in
+`execution-protocol.md` do not apply on this branch; the OMA modes, limits,
+output layout, manifest and report still do. Existing-file processing stays
+with `audio-processing.md` and needs no backend.
+
+## Resolve the backend
+
+1. Read `voice.backend` from `.agents/oma-config.yaml`. Values: `auto`
+   (default), `voicebox`, `voicestudio`. The oma-video narration provider
+   resolves the same setting.
+2. The VoiceStudio base URL is `OMA_VOICESTUDIO_URL`, then `VOICESTUDIO_URL`,
+   then `http://127.0.0.1:3900`.
+3. `auto` probes Voicebox `GET /health` first and VoiceStudio `GET /health`
+   second; the first healthy one wins. An explicit backend probes only itself
+   and never falls through.
+4. With no healthy backend, print the Voicebox hint from `execution-protocol.md`
+   plus "or open the VoiceStudio app", and exit with code 5. Do not launch,
+   install or update either app.
+
+## Route to the upstream skill
+
+1. Check the runtime skill catalog for `voicestudio` from
+   `https://github.com/debpalash/VoiceStudio` and read its complete `SKILL.md`.
+2. If it is absent, load it without a persistent installation or another agent:
+
+   ```bash
+   bunx skills use debpalash/VoiceStudio@voicestudio
+   ```
+
+   Omit `--agent`. `voicestudio-maintainer` maintains that repository and is
+   not part of this route.
+3. Follow the loaded upstream instructions for discovery (`/openapi.json`,
+   `/v1/audio/voices`), endpoints, authentication, and the clone, design,
+   dubbing and long-form job operations. Do not copy them into OMA resources.
+4. An already-connected VoiceStudio MCP server is an optional surface. Discover
+   its actual tools before calling them. Prefer the REST speech endpoint for a
+   file on disk, unless the MCP server runs in `files` mode with
+   `OMNIVOICE_MCP_BASE_PATH` inside `$PWD`.
+
+## OMA keeps
+
+- **Modes and limits**: notify, asset and transcribe modes, the 240 / 5000
+  character and 30-minute limits, and the clarification protocol are unchanged.
+- **Profiles**: resolve TTS voices from VoiceStudio's discovered profile IDs.
+  A `notification_profile` or `asset_profile` written for Voicebox does not
+  exist in VoiceStudio; ask instead of guessing. OpenAI voice names
+  (`alloy`, ...) are compatibility aliases, not saved voices; do not use one for
+  repeatable narration unless the user accepts it.
+- **Output and manifest**: write to the same `.agents/results/voice/` layout.
+  Record `"backend": "voicestudio"`, the profile ID, the engine and language
+  when the backend reports them, `format`, `duration_sec` and `created_at`.
+  Omit `voicebox_generation_id`; never invent a Voicebox field.
+- **Verification**: check the HTTP status, then probe the saved file with
+  ffprobe before calling it audio; an error body can be written to the output
+  path.
+- **Notification mode**: VoiceStudio does not play generations on the
+  speakers. Write the clip to a temporary file, play it with an available local
+  player (`afplay`, or `ffplay -nodisp -autoexit`), then delete it. Without a
+  player, report that playback was unavailable.
+- **Timed narration**: request `verbose_json` transcription for word timing,
+  then fit the raw WAV through `audio-processing.md`.
+
+## Consent and side effects
+
+- Clone a voice only on an explicit request and with the voice owner's
+  permission. Cloning and `design_voice` create persistent profiles; confirm
+  before creating one.
+- First use of an engine may download model weights (OmniVoice is about
+  2.3 GB). Ask before triggering a download.
+- Cloud translation, cloud sync, community features and remote backends run
+  only when the user chooses them. Send `OMNIVOICE_API_KEY` or a sharing PIN
+  only to the user's configured backend, over HTTPS unless it is loopback or
+  an explicitly trusted LAN. Never print a key or PIN.
+- VoiceStudio is AGPL-3.0; OMA uses it only through its local API and does not
+  vendor or bundle it. Model, voice and output licences are per model in its
+  Model Manager; report them when the user asks about reuse.
+
+## References
+
+- [Upstream VoiceStudio](https://github.com/debpalash/VoiceStudio):
+  `skills/voicestudio/SKILL.md`, `docs/mcp.md` and `docs/speech-platform.md`.
+- [Skills CLI use](https://github.com/vercel-labs/skills/blob/main/docs/commands.md#skills-use):
+  prompt and complete support-directory loading without an installed skill.