OrkasVideoStudio
Turns your coding agent into a video studio: describe a video in plain language and the agent writes the timeline and produces the file.
Evidence shows a zero-key trunk, BYO keys, local-first design, and boundary checks in tests (e.g. COMPOSITION_MANIFEST_AUDIO_PATH_INVALID), supporting least privilege; but no explicit user-confirmation flow appears in code (Gate C exists only as README narrative); key handling is a single claim about not printing credentials with no implementation evidence; external effects (file writes, billable generation) have cost-count gating but no user-side consent flow; rollback rests on the editable-plan claim with no recovery mechanism files; dependency security shows only a pinned hyperframes 0.7.60 with no audit evidence.
README and tests are self-consistent: validation codes (E_SPEC_*, E_PROMISE_*) cross-corroborate in edl.test.ts; the doctor command and Node≥22/ffmpeg prerequisites are explicit; tests indicate actionable errors for missing runtimes. Deduction: error-message quality rests on tests and README assertion only, with no actual CLI output samples in evidence.
The use-case table covers multiple audiences (explain, edit, generate, end-to-end) and environment requirements are explicit; capability boundaries are notably well handled: MuAPI model-slug allowlist, ratio/duration validation, explicit rejection of unsupported operations with tests. Deduction: router/trigger precision is described only in README flow; the router skill file itself is absent from evidence, so it cannot be verified; cross-platform (Windows) support is unaddressed.
Information architecture is clear (core/tools/cli/mcp/skills packages), install notes are complete with a source fallback and early-development disclosure, naming is consistent; known limitations are well documented (npm unpublished, MuAPI field restrictions, ignored resolution/audio); MIT license with third-party licensing notes earns full marks. Deductions: version is 0.0.0 with no CHANGELOG or versioning policy; maintenance responsibility is evidenced only by CI and pnpm verify, with no governance or maintainer file.
Output usability is supported: diffable plan. IR, per-segment re-render, promise-check delivery guard, deterministic tests and benchmarks; marginal value versus frameworks/SaaS/thin wrappers is argued clearly; cost awareness shows in the zero-key trunk and billable-count validation (E_COST_COUNT_MISMATCH). Deduction: all utility claims are static assertions without execution, so real output quality is unknown.
Some claims trace to tests (validation codes, delivery-guard behavior, narration-signature requirement have matching assertions, and README/tests cross-corroborate); but key claims like 'validated end-to-end inside Orkas' and 'validated Kling endpoints' cannot be traced in the provided files; documentation mixes fact with marketing inference ('real prompt you'd give'), so fact/inference separation is weak.
- Publisher identity is unverified; independently confirm the maintainer and response path before enterprise adoption.
- Sensitive-data handling (key storage, transmission, log redaction) is asserted only in the README; audit the implementation before supplying your own keys.
- No user-confirmation flow appears in code; gate agent-initiated billable generation and file overwrites at the host-agent side.
- npm packages are not yet published; only source install works today, version is 0.0.0 with no changelog, so upgrades carry no compatibility promises.
- The video-router skill file is absent from evidence; trigger behavior cannot be verified statically — spot-check it at runtime.
What does this agent do, and when should you use it?
OrkasVideoStudio is an MIT-licensed, local-first toolkit that lets any coding agent capable of running a shell or speaking MCP — Claude Code, Codex, Cursor — drive video composition, generation, and editing. It is not a black-box video agent: a video is expressed as a readable, diffable, re-renderable plan. IR where editing one line re-renders only that segment. The project ships three capability lines — Compose (HTML motion graphics to MP4), Edit (cut, trim-silence, subtitle burn-in, dubbing, localization), and Generate (BYO keys for image/video/TTS providers) — plus an automatic end-to-end Auto pipeline orchestrated via stage-plan and stage-assemble. The zero-key trunk builds on HyperFrames 0.7.60, ffmpeg, and whisper.cpp, while generation uses your own OpenAI, Gemini, Doubao, or other keys. Originally the built-in video agent inside the Orkas desktop app, it was extracted into an agent-agnostic toolkit exposed through the ovs CLI and an MCP server.
The agent first reads the video-router skill to lock a production line, then reads the stage skills (stage-plan, stage-compose, video-craft), authors composition-manifest. and plan., and runs deterministic operations: ovs composition prepare / ovs draft / ovs render produce HyperFrames-based HTML motion-graphic output; the ovs edit family (probe, trim, concat, burnsubs, overlay, loudness, mix, trim-silence, remove-fillers) processes supplied footage; ovs transcribe plus silence, scenes, and quality use whisper.cpp and ffmpeg to analyze material and select highlights; ovs speak, image, and video call BYO-key providers for narration and footage; and ovs plan validate / promise-check act as a delivery guard verifying the finished cut keeps its promise (real motion, not a silent slideshow) before shipping. Generate segments have ratio, duration, and operation checked against the configured video.provider, and the MuAPI adapter only accepts validated Kling v2.1 endpoints.
- A content creator wants Claude Code to produce a 60-second vertical explainer on vector databases with Chinese voiceover and captions — the Compose line handles HTML motion-graphic scenes, narration synthesis, and burned-in captions.
- An editor needs to turn a one-hour screen recording into three 30-second captioned highlight clips — the Edit line uses scenes/quality to locate good parts, rank-takes to choose, and trim-silence to tighten.
- A product manager wants an English voiceover, subtitles, and normalized loudness added to product-demo.mp4 — the Edit chain runs transcribe, localize, speak, mix, burnsubs, and a loudness pass.
- A podcaster wants silences and 'um's removed from a webcam take — the Edit line performs deterministic jump-cutting with an auditable evidence trail.
- A short-video team needs a 15-second 9:16 promo with a generated opener, composed feature callouts, and one voiceover — the Auto line weaves generate + compose + narration in a single plan. guarded before delivery.
- An indie developer wants a 5-second cinematic city-at-dawn shot generated in Cursor with their own OpenAI/Gemini/Doubao keys — the Generate line calls their own provider keys with no managed backend.
What are this agent's strengths and limitations?
- The plan. IR is readable, diffable, and per-segment re-renderable — every segment, caption, and narration line is independently re-renderable, producing an auditable artifact.
- The zero-key trunk (compose/edit/transcribe) works out of the box with no managed backend; generation is BYO-key (OpenAI, Gemini, Doubao, MuAPI, etc.) with no vendor lock-in.
- Ships both a CLI and an MCP server mirroring it 1:1, with native skill installation for Claude Code and Codex plus a self-describing CLI for any shell-capable agent.
- A deterministic delivery guard (ovs plan promise-check) verifies quality promises before shipping, and provider/ratio/duration/model checks reject plans the provider would refuse.
- The npm packages are still being published; today you must clone the source and run pnpm install && pnpm build.
- Requires Node >= 22 and ffmpeg/ffprobe on PATH; the compose draft QA gate depends on the pinned HyperFrames 0.7.60 dependency, and video tests fail when required runtimes are missing.
- The README flags early development status — command surface and package structure may change, creating upgrade and migration risk.
- The MuAPI adapter currently accepts only validated Kling v2.1 endpoints (duration 5/10s, ratio 16:9/9:16/1:1), rejects edit and additional-reference controls, limiting extension flexibility.
How do you install or deploy this agent?
Prerequisites: Node >= 22, and ffmpeg + ffprobe on your PATH. The npm packages are being published; for now install from source:
git clone https://github.com/Orkas-AI/Orkas-VideoStudio.git
cd Orkas-VideoStudio
pnpm install && pnpm build
node packages/cli/dist/index.js doctor # verify ffmpeg/ffprobe/node
alias ovs="node $PWD/packages/cli/dist/index.js" # optionalOnce published: npm i -g @orkas/video-studio, then run ovs doctor. Generation (image/video/TTS) is opt-in and requires your own keys configured in ~/.config/orkas-video-studio/config. or environment variables such as OVS_IMAGE_API_KEY, OVS_VIDEO_API_KEY, and OVS_TTS_API_KEY.
How do you use this agent?
Three ways to hook it up, whichever your agent supports:
1) Native skills: ovs skills --install --target claude (installs to ~/.claude/skills; add --scope repo for ./.claude/skills); use --target codex for Codex (installs to ~/.agents/skills).
2) MCP server: claude mcp add ovs -- npx -y @orkas/video-studio-mcp (from source: point it at node <repo>/packages/mcp/dist/index.js).
3) Self-describing CLI: any shell-capable agent can run ovs skills to list skills, ovs skill video-router to print full instructions, and ovs --help for the full command surface.
Typical session: the agent reads video-router to lock the line, authors composition-manifest. and plan., runs ovs composition prepare and ovs draft composition --out draft.mp4 --report draft-report., then verifies with ovs plan promise-check plan. before returning the cut.