/oma-video

name: oma-video
description: Create videos through the OMA video CLI, or analyze and edit
  existing clips with media tools. Use for frame extraction, visual analysis,
  silence cuts, dubbing assembly, sound effects, scripts, and composition;
  audio-only work uses oma-voice.

Video Router

Scheduling

Goal

Create a playable video, or derive requested frames, analysis, or edits from an existing clip while retaining its source timeline.

Intent signature

• Create a short, explainer, or recorded demo.
• Extract frames, count visible objects, remove pauses, or assemble a dubbed clip.
• Add sound effects to a video or check its soundtrack against the picture.

When to use

Use this skill for a short/reel, README or code explainer, demo walkthrough, or analysis and editing of an existing video.

| Request | Mode | Default aspect | Required source | |---|---|---|---| | Short, reel, social clip | `shorts` | `9:16` | Topic or brief | | README, code, data explanation | `explainer` | `16:9` | Topic or source path | | Demo or walkthrough | `demo` | `16:9` | Human recording via `--capture` |

Processing a supplied or already-rendered video conditionally loads the upstream `kajisho5/ffmpeg-skill` through `resources/existing-media.md`. This is separate from the OMA creation modes. Sound effects, a sound-designed soundtrack, or listening checks on a video's audio conditionally load `Leonxlnx/earshot` through `resources/sound-design.md`.

When NOT to use

Use `oma-image` for a still image, `oma-slide` for a deck, `oma-voice` for audio only, and `oma-explanation` for an interactive HTML explainer. Route transcription, synthesis, and TTS duration fitting to `oma-voice`, and spoken translation to `oma-translation`; this skill owns their placement in video. Live streaming is out of scope.

Expected inputs

A creation brief, or an existing clip plus the requested analysis/edit, selected streams, timing or sampling requirements, and output path.

Expected outputs

A generated video and its asset bus, or requested frames/analysis/edited media with source timestamps and the parameters used to derive them.

Dependencies

Creation requires the selected OMA providers/compositor. For processing supplied or rendered video, use the runtime skill catalog first; otherwise load `kajisho5/ffmpeg-skill` with `bunx skills use` as described in the conditional resource. Its complete support bundle, Python, FFmpeg/FFprobe and any operation-specific capabilities are required. Sound effects and audio listening use the upstream earshot skills plus a resolved earshot runtime with FFmpeg/FFprobe; never install it without consent. Visual interpretation uses the host vision tool. Report unavailable capabilities rather than invent results.

Structural Flow

For supplied or already-rendered video, use the existing-media branch in the canonical path. The upstream skill owns its scripts, flags, templates, `project.json` and mechanical editing workflow. OMA retains source-timeline evidence and the visual, speech and editorial decisions described there. Its project format is separate from the OMA creation asset bus below. For creation, inputs are a brief plus optional mode, aspect, locale, captions, visual, voice, music, duration, compositor, capture path, and seed. Outputs live in `.agents/results/videos/<timestamp>-<shortid>-<mode>/`:

• `script.json`, `timing.json`, and `render-spec.json` form the deterministic

asset bus.

• Captions and acquired audio/visual assets are recorded in `manifest.json`

with hashes, providers, cost, warnings, and exit code.

• A successful real render contains `<mode>-<slug>.mp4`, an encoded video

stream, and a positive ffprobe duration.

`OMA_VIDEO_MOCK=1` is a test harness only. It can create deterministic text placeholders with an `.mp4` name; those files are never a user deliverable. A missing HyperFrames/MPT toolchain, an un-authored composition, a render error, or an invalid video fails with diagnostics and leaves the script/render spec for recovery.

Decide and confirm

For creation, infer mode when clear: short/reel -> `shorts`; README/code/data/explain -> `explainer`; demo/walkthrough/capture -> `demo`. For a one-line creation request, state the inferred mode, aspect, duration, visual strategy, captions, locale, and voice/music before invoking. Do not make the user complete a questionnaire when those defaults are clear.

Ask only when it changes the result: an ambiguous mode/source, a required demo recording, or a cost confirmation. Respect an explicit mode, aspect, duration, captions, or voice verbatim.

For a demo, a human records the screen and controls login. `--source web --url` provides context only; it never automates login or starts a recorder. Without `--capture`, return guided capture instructions and stop.

Logical Operations

Guardrails

1. Keep output and capture paths inside `$PWD` unless external output is explicitly allowed. Validate capture formats and copy external assets into the run directory. Mask URL query/hash tokens in logs and manifests. 2. Provider configuration is key-optional: use the configured chain. Paid providers require their environment key and the cost guardrail. Local fallbacks may replace voice, visuals, captions, or music; record coverage in warnings. A compositor failure is never a fallback video. 3. Before a paid provider action or rerun, compare the planning estimate with `cost.guardrail_usd` or `--max-usd` and reuse existing spend authorization. In an active OMA video workflow, record the actual paid, limited, fallback, or declined choice before executing it (execution protocol Step 2). Pass `--yes` or `OMA_VIDEO_YES=1` only for an already authorized paid action; the event does not grant permission. 4. For creation, respect `limits.max_duration_sec` (180) and `limits.max_scenes` (40). Cancel subprocess work on SIGINT/SIGTERM. 5. Keep run directories. Never auto-prun