oliverv/caro / .agents/skills/oma-video
oma-video
UnverifiedCreate short, explainer, or recorded-demo videos through the OMA video CLI. Use for scripts, narration, assets, composition, and video delivery.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.4 KB |
| config/video-config.yaml | config | 1.9 KB |
| resources/checklist.md | markdown | 2.3 KB |
| resources/execution-protocol.md | markdown | 7.8 KB |
| resources/hyperframes-authoring/README.md | markdown | 2.1 KB |
| resources/hyperframes-authoring/demo.md | markdown | 966 B |
| resources/hyperframes-authoring/explainer.md | markdown | 901 B |
| resources/hyperframes-authoring/shorts.md | markdown | 1.2 KB |
| resources/mpt/driver.py | script | 11.8 KB |
| resources/prompt-tips.md | markdown | 4.5 KB |
| resources/script-schema.md | markdown | 3.5 KB |
| resources/strudel/package.json | manifest | 464 B |
| resources/strudel/page.html | other | 3.0 KB |
| resources/strudel/render.mjs | script | 9.8 KB |
| resources/vendor-matrix.md | markdown | 6.2 KB |
resources/vendor-matrix.md
View on GitHub# 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 TTS + STT timing | estimated timing (no wav) | — |
| visual | `[oma-image, pexels, pixelle]` | Pexels stock · Pixelle AIGC | oma-image stills + Ken Burns | `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 |
## 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; Ken Burns adds motion |
| 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 --dir <deck> --out-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 oma-image stills + Ken Burns |
| 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 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |