/oma-voice

name: oma-voice
description: Generate or transcribe speech with Voicebox or VoiceStudio, or
  process existing audio locally. Use for narration, transcripts, timed speech,
  and loudness conversion; video editing uses oma-video.

Voice Skill - Speech and Local Audio Processing

Scheduling

Goal

Generate and transcribe speech through a local speech backend (the Voicebox app, or VoiceStudio per `voice.backend`), and process existing audio with local media tools. The backend owns synthesis engines and profiles; FFmpeg owns file conversion, duration adjustment, and loudness processing.

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.
• User needs existing speech fitted to a time window, resampled, converted, or loudness-normalized.

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.
• Processing an existing audio asset, including speech used in an `oma-video` dubbing job.

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 editing and audio/video placement -> `oma-video`; music and sound design are 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.
• Processing: existing audio path, requested operations, and any stated duration, sample rate, channel layout, loudness, or format constraints. Derive targets from the brief, not a universal mastering preset.

Expected outputs

• TTS: audio file (`wav` — Voicebox's native TTS output format; `mp3` optional via a local ffmpeg transcode) at `.agents/results/voice/{timestamp}-{shortid}/output.{wav|mp3}` 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.
• Processing: a separate processed audio file plus `manifest.json` containing source/output paths, operations, and measured audio properties. Keep the source intact. A generation id is present only when Voicebox actually generated the audio.

Dependencies

• Processing only: installed `ffmpeg` and `ffprobe`; no Voicebox app or voice profile is required.
• Generation/transcription: Voicebox desktop app installed and running locally, or a running VoiceStudio backend selected through `voice.backend` (`resources/voicestudio.md`).
• Generation/transcription only: Voicebox MCP registered (`claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp`).
• TTS only: at least one voice profile created in the Voicebox app UI.
• TTS only: 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, transcription, or existing-audio processing. For processing, follow `resources/audio-processing.md` directly, before any Voicebox health, profile, or model lookup. 2. Resolve `voice.backend` (`auto` tries Voicebox, then VoiceStudio). For VoiceStudio, follow `resources/voicestudio.md` from here; the steps below describe Voicebox. 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. For notification or asset TTS, resolve the target voice profile id. For transcription, validate the audio input and continue without a profile.

Scenes

1. **PREPARE**: Resolve the operation and its inputs. Voicebox modes use text/audio and language; TTS additionally needs a profile. File processing uses the source and requested media properties. 2. **ACQUIRE**: If a required signal is missing, run the clarification protocol once. 3. **ACT**: Invoke the appropriate MCP tool (TTS or STT), or process the existing asset with local FFmpeg commands. 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

• For generation/transcription, if Voicebox is unreachable, surface the install or launch hint and exit. Do not attempt auto-relaunch. Existing-file processing continues without it.
• Loopback addresses refer to the process's own host or container. Invoke a host Voicebox service from the host, then transfer the resulting file to the task container; a container's `127.0.0.1` does not probe the host app.
• For timed narration, keep the raw generation. Select a language-capable available profile, measure the raw duration, and use `resources/audio-processing.md` for fitting. A neural engine or