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

package/skills/oma-video/resources/vendor-matrix.md

@@ -0,0 +1,124 @@
+# Vendor Matrix
+
+oma-video is a **key-optional** router (backend rule 11). Each capability has a
+provider `order` (a fallback chain). The orchestrator probes availability and
+walks the chain: the first available provider wins; only chain exhaustion is a
+stage failure. Paid providers auto-enable **only** when their env key is set;
+otherwise the chain falls through to a key-free default.
+
+## Capabilities -> providers
+
+| Capability | order (config) | real (key/resource) | key-free fallback | marker |
+|------------|----------------|---------------------|-------------------|--------|
+| script | `[agent-script]` | agent-authored script (agent-as-key) | — | — |
+| voice | `[oma-voice]` | Voicebox MCP or VoiceStudio REST TTS + STT timing (`voice.backend`) | estimated timing (no wav) | — |
+| visual | `[oma-image, pexels, pixelle]` | Pexels stock · Pixelle AIGC | static oma-image stills | `TODO(oma-deferred): pexels` / `pixelle` |
+| caption | `[oma-captions]` | oma-translation for non-source locale | source-locale text from timing | `TODO(oma-deferred): oma-translation` |
+| capture | Cap / guided capture | Human-recorded video ingestion | guided protocol + `--capture <path>` | `TODO(oma-deferred): cap` |
+| compositor | `[hyperframes, mpt]` | HyperFrames live render (wired, default) · MPT custom-script | none: missing toolchain, failed render, or invalid output fails with diagnostics | — |
+
+## Tier model
+
+| Tier | Surface | Providers | Notes |
+|:---:|---------|-----------|-------|
+| 1 | CLI-first (subprocess) | HyperFrames, MPT, oma-image, oma-slide, oma-voice (REST) | deterministic; preferred whenever a CLI can drive the work |
+| 2 | MCP | Voicebox MCP, Pixelle-MCP | localhost MCP; Pixelle off by default, community-MCP consent + key |
+| 3 | Guided (human) | Cap / human-recorded video | `demo` capture is performed by a human |
+
+## oma-voice (VoiceProvider + timing)
+
+| Field | Value |
+|-------|-------|
+| Surface | Voicebox MCP (Streamable HTTP) at `127.0.0.1:17493/mcp`; REST on the same port |
+| Synthesize | MCP `voicebox_speak{text, profile, language}` -> `generation_id` (REST `POST /speak` fallback) |
+| Retrieve wav | REST `GET /audio/{generation_id}` (MCP has no save-to-disk) |
+| Timing (real) | MCP `voicebox_transcribe{audio_path}` on the wav -> `source: voicebox-stt` (REST `POST /transcribe` fallback) |
+| Timing (fallback) | `estimated` (no wav written, `audio` field empty); a whisper.cpp hop is reserved but not wired (`TODO(oma-deferred): whisper-cpp`) |
+| Side effect | Narration plays on the speakers during synthesis |
+| Health | exit 5 if MCP down; exit 3 if the named profile is missing |
+
+### VoiceStudio backend
+
+`voice.backend` in oma-config selects the speech
+backend behind the same `oma-voice` provider: `auto` (default) uses Voicebox
+when healthy, otherwise VoiceStudio; `voicebox` and `voicestudio` never fall
+through. Any live failure degrades to estimated timing with a warning.
+
+| Field | Value |
+|-------|-------|
+| Surface | VoiceStudio REST at `OMA_VOICESTUDIO_URL` / `VOICESTUDIO_URL` (default `127.0.0.1:3900`) |
+| Synthesize | `POST /v1/audio/speech{model: tts-1, voice: <profile id>, input, response_format: wav}`; a non-WAV body is rejected |
+| Timing (real) | `POST /v1/audio/transcriptions` (`verbose_json`, word + segment timestamps) -> `source: voicestudio-stt`; a failed transcription keeps the wav with estimated segments |
+| Auth | none on loopback; `OMNIVOICE_API_KEY` bearer only to a loopback or HTTPS backend |
+| Side effect | none on the speakers; first use of an engine may download its model inside the backend |
+| Doctor | `oma video doctor` reports `voicestudio` as an optional check |
+
+## oma-image (VisualProvider: generate) — default key-free visual
+
+| Field | Value |
+|-------|-------|
+| Transport | `oma image generate "<prompt>" --vendor auto --size <16-multiple> --output json --output-dir <runDir>/visuals` |
+| Aspect -> size | snapped to nearest 16-multiple: 9:16 -> 1088×1920, 16:9 -> 1920×1088, 1:1 -> 1088×1088 |
+| Crop | HyperFrames crops the still to the exact frame; the still stays static |
+| Cost | free defaults (pollinations / antigravity); codex per-image per oma-image config |
+
+## oma-slide (VisualProvider: slide, explainer) — key-free
+
+| Field | Value |
+|-------|-------|
+| Transport | `oma slide` generate deck -> `oma slide export png --workspace <deck> --output-dir <runDir>/visuals` -> 1920×1080 frames |
+| Layering | oma-slide internally calls oma-image (same key-free chain) |
+| Use | explainer code/diagram frames |
+
+## Pexels (VisualProvider: stock) — paid, opt-in
+
+| Field | Value |
+|-------|-------|
+| Auth | `PEXELS_API_KEY` env var |
+| Enabled | only when the key is present (`providers.pexels.enabled` gate) |
+| Fallback | absent key -> skip; chain falls to static oma-image stills |
+| Marker | `TODO(oma-deferred): pexels` on the real-call branch until the key is provisioned |
+
+## Pixelle-MCP + RunningHub (VisualProvider: aigc) — paid, off by default
+
+| Field | Value |
+|-------|-------|
+| Surface | MCP `http://localhost:9004/pixelle/mcp`; RunningHub cloud or local ComfyUI |
+| Setup | `uvx pixelle@latest` + wizard; one-time **explicit consent + source review** |
+| Auth | `RUNNINGHUB_API_KEY` env var; cost gates on RunningHub credits via `--max-usd` |
+| Enabled | off by default (`providers.pixelle.enabled`); never auto-connects |
+| Fallback | absent/declined -> oma-image stills |
+| Marker | `TODO(oma-deferred): pixelle` on the real-call branch |
+
+## Cap (CaptureProvider, demo) — Tier 3 guided
+
+| Field | Value |
+|-------|-------|
+| Real | Cap CLI trigger when installed |
+| Fallback | guided protocol: instruct the human to record, then pass `--capture <path>` |
+| Path safety | `--capture` is absolutized, `$PWD`-guarded, existence + format validated |
+| Marker | `TODO(oma-deferred): cap` on the CLI-trigger branch |
+
+## Compositor: HyperFrames (default) / MPT (alt)
+
+| Field | Value |
+|-------|-------|
+| Real | Agent-authored `<runDir>/hyperframes/index.html`; `compose` stages local assets and the authoring contract. `render` runs the cached CLI: lint → strict MP4 render → ffprobe. |
+| Requires | Node + Chrome Headless Shell + FFmpeg (bootstrapped once via `oma video doctor --install`) |
+| Failure | Missing toolchain, render error, missing video stream, or non-positive duration fails with diagnostics. `OMA_VIDEO_MOCK=1` may write a deterministic placeholder only for tests. |
+| Determinism | Saved render spec, local assets, authored HTML, seed, recorded CLI version, and embedded font. Byte identity across different browser/OS versions is not guaranteed. |
+| MPT alt | inject the agent-written script (custom-script mode); keys env-only + log masking; `--compositor mpt` |
+
+## Error Classification
+
+| Error kind | Retry policy | Exit code when solo |
+|------------|-------------|---------------------|
+| `provider-unavailable` | try next provider in `order`; chain-exhaustion fails | 5 |
+| `auth-required` | fail; hint tells the user how to authenticate | 5 |
+| `compositor-bootstrap` | fail; point to `oma video doctor` or `oma video doctor --install-mpt` | 1 |
+| `cost-guardrail` | confirm; decline -> stop | 1 |
+| `capture-required` | guided protocol; not a hard error | (guided) |
+| `schema-validation` | fail; identify the offending field | 4 |
+| `safety-refused` | short-circuit (no fallback) | 2 |
+| `not-found` | fail; missing profile / asset | 3 |
+| `timeout` | record; fail | 6 |

package/skills/oma-voice/SKILL.md

@@ -0,0 +1,249 @@
+---
+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 correct loudness does not establish natural pronunciation or prosody.
+- If a TTS request has no usable profile, point the user at the Voicebox app UI to create a profile, then exit. A transcription request never needs a profile.
+- 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
+| Failure | Recovery |
+|---------|----------|
+| No selected backend reachable | Print the Voicebox install/launch hint (and VoiceStudio for `auto`), exit code 5 |
+| No voice profile for TTS | Print "create a profile in Voicebox" hint, exit code 3 |
+| Engine model missing | Ask before triggering download |
+| Output path outside `$PWD` | Use an explicitly requested path; ask only if the destination is ambiguous or overwrites unrelated data |
+| TTS over 5000 chars | Ask the user to split or truncate |
+| STT over 30 minutes | Confirm only if the requested duration or resource cost is unresolved |
+| MCP tool name drift | Re-run `tools/list` and update the cache |
+| SIGINT | Abort the MCP call, write no partial output |
+| Local media executable missing | Report the missing tool for the requested operation; do not start Voicebox or replace audio with a placeholder |
+| Speech cannot fit naturally | Retain the raw audio; adjust generation pacing when synthesis is available and authorized, or report the unresolved timing constraint instead of clipping words |
+
+### 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
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Validate mode and inputs | `VALIDATE` | Clarification protocol in execution-protocol.md |
+| Resolve TTS voice profile | `SELECT` | `voicebox_list_profiles` + config defaults |
+| Health check | `READ` | MCP handshake or `GET /health` |
+| Generate speech | `CALL_TOOL` | MCP `voicebox_speak` |
+| Transcribe audio | `CALL_TOOL` | MCP `voicebox_transcribe` |
+| Write output and manifest | `WRITE` | Audio or transcript plus `manifest.json` |
+| Inspect result | `VALIDATE` | Output presence, duration, manifest fields |
+| Report result | `NOTIFY` | Final user-facing summary |
+
+### Tools and instruments
+- Voicebox MCP server at `http://127.0.0.1:17493/mcp` for generation/transcription; local FFmpeg and ffprobe for existing audio.
+- 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
+
+Dispatch existing-audio work to `resources/audio-processing.md`. The path below
+is for Voicebox generation/transcription only; timed TTS follows the processing
+reference after fetching the raw WAV.
+
+```text
+# 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 tool mapping (verified against Voicebox 0.5.0)
+
+| Use case | MCP tool | REST backing |
+|---|---|---|
+| TTS generation | `voicebox_speak` | `POST /speak` |
+| STT transcription | `voicebox_transcribe` | `POST /transcribe` |
+| Profile listing | `voicebox_list_profiles` | `GET /profiles` |
+| Captures listing | `voicebox_list_captures` | `GET /history` (captures view) |
+
+Tools not exposed via MCP (REST only): model status (`GET /models/status`), audio file serving (`GET /audio/{generation_id}`), per-version audio (`GET /audio/version/{version_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; to persist a local copy, fetch `GET /audio/{generation_id}` (Voicebox TTS always stores `wav`).
+- 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
+| Scope | Resource target |
+|-------|-----------------|
+| `LOCAL_FS` | Input audio, generated audio, transcripts, manifests |
+| `PROCESS` | Local Voicebox app (managed by the user), FFmpeg/ffprobe processing |
+| `NETWORK` | Loopback HTTP to Voicebox `127.0.0.1:17493`, or the user's configured VoiceStudio backend (default `127.0.0.1:3900`) |
+| `MEMORY` | Cached MCP tool names, resolved profile metadata |
+| `CREDENTIALS` | None for Voicebox. A protected VoiceStudio backend uses the user's `OMNIVOICE_API_KEY`; never print it. |
+
+### Preconditions
+- Processing: local `ffmpeg` and `ffprobe` can read the source asset.
+- Generation/transcription: Voicebox app is running and the MCP handshake succeeds.
+- TTS only: at least one voice profile exists.
+- TTS only: 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/`.
+- Existing-audio processing runs local media subprocesses and preserves the input file.
+- 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. VoiceStudio cloud features and remote backends run only when the user chooses them.
+
+### Guardrails
+
+1. **Voicebox modes**: generation/transcription requires the MCP handshake or `GET /health`. On failure, exit with a one-shot install or launch hint; do not retry or auto-relaunch. Local processing does not require Voicebox.
+2. **Profile required for TTS only**: resolve a profile and check the TTS engine only for notification or asset mode. Transcription proceeds with a valid audio input and optional STT model even when no profile exists.
+3. **Tool-name discovery**: on the first Voicebox 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). This threshold is agent-enforced guidance — no hook measures task duration — so apply it by judgment when a long task completes or blocks. Always announce intent in one short line before generating audio.
+6. **Path safety**: an explicitly requested output path authorizes writing there. Resolve ambiguity or unrelated-data replacement before the dependent write; preserve required CLI path flags.
+7. **Cancellation**: SIGINT aborts the MCP call and writes no partial output.
+8. **Manifest required for persisted output**: asset TTS and transcription modes write `manifest.json` with at minimum: `skill`, `mode`, `voicebox_generation_id`, `text` (or `transcript_preview`), `profile`, `engine`, `language`, `format` (TTS only), `created_at`. Processing records the source, operations, and measured output properties as specified in `resources/audio-processing.md`; it never invents Voicebox provenance. Notification mode is exempt because Voicebox Captures is its system of record and no disk output is written by default.
+9. **Out of scope**: the Voicebox cloning UI, captures archive, stories editor, microphone dictation loop, and cloud vendors are intentionally not exposed. VoiceStudio cloning and voice design run only on an explicit request with the voice owner's permission (`resources/voicestudio.md`).
+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 (wav default; mp3 requires a local ffmpeg transcode)?
+
+**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
+```text
+/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` (TTS profile/engine selection)
+- Prompt writing rules: `resources/prompt-tips.md` (TTS text)
+- Execution protocol: `resources/execution-protocol.md` (Voicebox generation/transcription)
+- VoiceStudio backend: `resources/voicestudio.md` (backend resolution, upstream skill routing, consent)
+- Existing audio and timed narration: `resources/audio-processing.md` (processing, duration fitting, or requested loudness conversion)
+- Pre-flight checklist: `resources/checklist.md` (Voicebox calls)
+- Configuration: read the `voice:` section of `.agents/oma-config.yaml` first, then fall back to `config/voice-config.yaml` for any key it does not set. `voice.backend` (`auto` | `voicebox` | `voicestudio`, default `auto`) lives only in oma-config. Both profiles ship as `null` and must be set per machine — write them to `.agents/oma-config.yaml`, since `oma update` overwrites the skill config.
+- 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)

package/skills/oma-voice/config/voice-config.yaml

@@ -0,0 +1,30 @@
+# oma-voice configuration
+# Design reference: docs/plans/designs/012-oma-voice.md
+#
+# NOT the place to put your settings: `oma update` overwrites this file. Put
+# overrides under `voice:` in .agents/oma-config.yaml, which is preserved —
+# that section wins, and this file supplies only the shipped defaults the skill
+# falls back to. Migration 022 moves anything you changed here for you.
+#
+
+# Speech backend: set `voice.backend` in oma-config (auto | voicebox |
+# voicestudio). It is not a key in this file; the shipped default is auto.
+
+# Profile names returned by `voicebox_list_profiles`. Set after creating a
+# profile in the Voicebox app (Profiles tab → + New Profile). When null, the
+# skill asks the user which profile to use, or disables auto-notification.
+notification_profile: null
+asset_profile: null
+
+# Where TTS asset audio and STT transcripts are written.
+output_dir: .agents/results/voice
+
+# Trigger automatic voice notifications when the active task exceeds this many
+# seconds. Set to null to disable auto-notification.
+# NOTE: agent-enforced guidance — no hook measures task duration, so the agent
+# applies this threshold by judgment when a long task completes or blocks.
+auto_notify_after_sec: 60
+
+# Hard limits. Above these the skill asks the user to split or truncate.
+max_tts_chars: 5000
+max_stt_minutes: 30

package/skills/oma-voice/resources/audio-processing.md

@@ -0,0 +1,119 @@
+# Existing Audio and Timed Speech
+
+Load for conversion, speech duration fitting, loudness processing, or dubbing
+audio. These are local FFmpeg operations, not new `oma` CLI subcommands.
+Video cuts and placement belong to `oma-video`.
+
+## Source and targets
+
+Keep the source and raw TTS generation. Write separate working/output files
+under the requested destination or `.agents/results/voice/<run>/`. Use
+`ffmpeg -n` to avoid replacing an unrelated output.
+
+Inspect the audio stream before selecting operations:
+
+```bash
+ffprobe -v error -select_streams a:0 \
+  -show_entries stream=codec_name,sample_rate,channels,start_time,duration:format=duration \
+  -of json "$INPUT"
+```
+
+Use the brief's time window, channel layout, sample rate, and delivery profile.
+If no conversion is requested, preserve those properties. Keep source stream
+offsets when handing audio to a video timeline. A container duration can include
+other streams or padding; use decoded audio duration for speech fitting.
+
+## Generating speech for a window
+
+Resolve an available language-capable Voicebox profile before synthesizing.
+Run host-local Voicebox calls on the host, even when the media work is in a
+container; transfer the fetched WAV into that workspace. A failed container
+loopback probe is not evidence that the host service is unavailable. Do not
+launch the app, expose its port, download a model, or substitute a provider
+outside existing authorization.
+
+Measure the raw utterance, including its audible beginning and ending. Prefer
+generation pacing appropriate to the window before stretching the waveform.
+Changing the transcript, repeating words, or truncating speech is not duration
+control unless the user requested those edits.
+
+For a modest pitch-preserving adjustment, set `TEMPO` to raw speech duration
+divided by target speech duration. Use the duration of the actual input WAV:
+if leading/trailing silence has been removed, point `INPUT` at that trimmed
+working copy before calculating the ratio. Do not use an unpadded duration
+with a file that still contains padding.
+
+```bash
+ffmpeg -hide_banner -n -i "$INPUT" -map 0:a:0 \
+  -af "atempo=${TEMPO},asetpts=PTS-STARTPTS" \
+  -c:a pcm_f32le "$FITTED_WAV"
+```
+
+For ratios outside one filter's useful range, compose supported `atempo`
+factors rather than replacing sample-rate metadata. Large changes can still
+damage pronunciation and rhythm: change generation pacing or retain the
+unresolved timing constraint instead of forcing a fit. Only trim identified
+leading/trailing silence; pad unused time with silence after speech ends.
+Keep a segment's unpadded speech duration distinct from its timeline slot.
+
+When choosing pacing or processing parameters, compare the raw and processed
+speech through an available audio inspection tool, focusing on pronunciation,
+rhythm, and clipped beginnings/endings. Engine names, pitch variation, ASR
+agreement, and loudness measurements do not establish naturalness. If speech
+quality cannot be assessed, state that limit. Preserve the raw asset so a
+different setting can be tried without repeated lossy encodes.
+
+## Loudness and format
+
+Apply only a requested or stated delivery profile. Set `TARGET_I`,
+`TARGET_LRA`, `TARGET_TP`, `SAMPLE_RATE`, and `CHANNELS` from that profile.
+Measure the actual fitted/edited input, not a different raw generation:
+
+```bash
+ffmpeg -hide_banner -nostats -i "$INPUT" -map 0:a:0 \
+  -af "loudnorm=I=${TARGET_I}:LRA=${TARGET_LRA}:TP=${TARGET_TP}:print_format=json" \
+  -f null - 2> "$LOUDNESS_LOG"
+```
+
+Use the final JSON block's `input_i`, `input_lra`, `input_tp`, `input_thresh`,
+and `target_offset` as the corresponding `MEASURED_*` and `OFFSET` values:
+
+```bash
+ffmpeg -hide_banner -n -i "$INPUT" -map 0:a:0 \
+  -af "loudnorm=I=${TARGET_I}:LRA=${TARGET_LRA}:TP=${TARGET_TP}:measured_I=${MEASURED_I}:measured_LRA=${MEASURED_LRA}:measured_TP=${MEASURED_TP}:measured_thresh=${MEASURED_THRESH}:offset=${OFFSET}:linear=true:print_format=json" \
+  -ar "$SAMPLE_RATE" -ac "$CHANNELS" -c:a pcm_s24le "$OUTPUT_WAV" \
+  2> "$NORMALIZATION_LOG"
+```
+
+Do not pass non-finite measurements from a silent asset into the second pass
+or amplify silence into a replacement voice. FFmpeg can fall back to dynamic
+normalization when linear-mode conditions are not met; record the actual
+mode and measured result. Set the output sample rate explicitly because the
+normalizer can change it. Encode the requested delivery format once from
+the PCM working asset; do not repeatedly transcode a lossy result.
+
+## Handoff and recovery
+
+Pass the processed audio and its intended position to `oma-video` for muxing.
+A shorter audio file must not shorten the original video automatically.
+For basic conversion, no TTS profile, transcript, or model is needed.
+
+Persist `manifest.json` with `skill: "oma-voice"`, `mode: "process"`,
+`source_path`, `output_path`, `operations` and their parameters,
+`duration_sec`, `sample_rate_hz`, `channels`, and `created_at`. Include
+Voicebox generation/profile/engine identifiers only when they are real.
+Record requested constraints that could not be met without changing speech.
+
+| Failure mechanism | Recovery |
+|---|---|
+| Timing correction changes pitch | Use pitch-preserving tempo processing; do not relabel the sample rate |
+| Speech sounds distorted after fitting | Return to the raw utterance and adjust pacing or the allowed window |
+| Silence gives infinite loudness measurements | Stop normalization of that input; locate the missing or silent source |
+| An asset plays but its duration differs from its report | Read duration and stream properties from the actual output file |
+| Voicebox is unreachable but an input WAV exists | Process the WAV locally; resolve synthesis availability only if new speech is needed |
+
+## Command reference
+
+- [FFmpeg atempo](https://ffmpeg.org/ffmpeg-filters.html#atempo)
+- [FFmpeg loudnorm](https://ffmpeg.org/ffmpeg-filters.html#loudnorm)
+- [FFprobe options](https://ffmpeg.org/ffprobe.html)

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

@@ -0,0 +1,47 @@
+# Pre-flight Checklist
+
+This checklist applies to Voicebox TTS/STT calls. On the VoiceStudio backend, replace the Environment and profile checks with `voicestudio.md` and record `backend: voicestudio` instead of `voicebox_generation_id`. Existing-file processing uses `audio-processing.md` and does not run Voicebox health, profile, or model checks.
+
+## 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 (TTS only)
+
+- [ ] At least one voice profile exists (cached from `voicebox_list_profiles`).
+- [ ] Target profile id is resolved for notify or asset TTS (explicit > config default > user choice).
+- [ ] Engine model for the resolved profile is loaded, or the user approved a download.
+
+Transcription skips profile lookup and the TTS engine check.
+
+## 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 handling of a longer recording is explicitly resolved; v1 does not auto-split.
+- [ ] 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
+
+- [ ] Persisted output has `skill`, `mode`, `voicebox_generation_id`, `language`, and `created_at`. For TTS, resolve `profile` and `engine`; for STT, use `profile: null` and the actual STT engine/model when returned, otherwise `engine: null`. Notification mode needs no disk manifest.
+- [ ] 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.