OrkasVideoStudio: an editable plan.json instead of a black-box video agent

The problem is the timeline, not the model

Most text-to-video tools hide the edit. You supply a prompt, a service returns a file, and any correction means regenerating the whole thing. OrkasVideoStudio takes the opposite position. The README states plainly that the project is not a black-box video agent, and that a video is expressed as a readable, diffable, re-renderable plan called plan.json. The claim attached to that file is narrow and testable: change one line and only that piece re-renders. The intended user is someone who already has a coding agent open in a terminal and wants video assembly to be another tool in that session rather than a separate web app. The README frames the division of labour as the agent being the brain, with the project shipping knowledge, deterministic capabilities, and the editable intermediate representation.

Four production lines and the router that picks one

The capability surface is split into three orthogonal axes plus a pipeline that combines them. Compose goes from script to designed HTML motion graphics to mp4, covering explainers, kinetic typography, lower thirds, data viz and transitions, and the README says it needs no paid keys. Edit handles cut, join, trim-silence, de-filler, mix, burn-in subtitles and dubbing over footage you supply, also with no paid keys. Generate produces talking-head or cinematic footage through your own provider keys, naming OpenAI, Gemini and Doubao as examples, with no managed backend. Auto is the interesting one: when a deliverable spans axes, the agent routes to a single cross-modal plan.json, where stage-plan builds the EDL and stage-assemble walks it, delegating each segment back to compose, generate or edit. A delivery guard, invoked as `ovs plan promise-check`, then verifies the finished cut keeps its promise, with the README's example being real motion rather than a silent slideshow. That guard is the part worth scrutinising, because it is the only mechanism described that checks intent against output rather than just checking that a file exists.

How a session actually flows through the skills

The agent reads a skill called video-router first, which locks the production line, then reads the relevant stage skills, authors the composition or plan.json, runs the deterministic operations, and self-verifies with the delivery guard. The README walks through an example: a request for a 60-second vertical explainer on vector databases with a Chinese voiceover leads the agent to read video-router, lock compose-primary, read stage-plan, stage-compose and video-craft, write composition/composition-manifest.json plus plan.json, and then run `ovs composition prepare`. The knowledge pack is deliberately layered so an agent does not pull the whole thing into context at once. Three integration paths exist: native skills for Claude Code and Codex, MCP typed tools that mirror the CLI one to one, and a self-describing CLI for any agent that can run a shell. That third path matters because it means the project does not depend on a specific agent vendor shipping a loader.

Getting it running: doctor, skills, MCP

Prerequisites are Node 22 or later plus ffmpeg and ffprobe on PATH, which the README ties to edit, transcribe and local media QA. Compose drafts use a VideoStudio QA gate backed by a pinned HyperFrames 0.7.60 package dependency, with npx described as a compatibility fallback only. The README is explicit that early development means the npm packages are still being published, so the from-source path is the one that works today: clone the repository, run `pnpm install && pnpm build`, then `node packages/cli/dist/index.js doctor` to verify ffmpeg, ffprobe and node. The README suggests aliasing that to `ovs`. For agent integration, `ovs skills --install --target claude` writes to ~/.claude/skills, `ovs skills --install --target codex` writes to ~/.agents/skills, and adding `--scope repo` relocates the Claude target to ./.claude/skills. MCP registration is `claude mcp add ovs -- npx -y @orkas/video-studio-mcp`, with the equivalent codex command, and a from-source variant pointing at node packages/mcp/dist/index.js. The npm install path, `npm i -g @orkas/video-studio`, is documented but gated on publication.

The npm gap and the ffmpeg dependency are real constraints

Two constraints stand out. The first is distribution. The README states the npm packages are being published, which means the documented `npm i -g @orkas/video-studio` and the `npx -y @orkas/video-studio-mcp` registration may not resolve for you, leaving the from-source build as the only reliable install. That is a meaningful difference for anyone evaluating this in a CI image or a locked-down machine, because it turns a one-line install into a clone, a pnpm build and a path alias. The second is the ffmpeg requirement. Edit, transcribe and local media QA all sit on ffmpeg and ffprobe being present on PATH, and the doctor command exists precisely to confirm that. There is no bundled binary mentioned. On a machine without ffmpeg, the compose line may still work while the edit line does not, which is a split capability surface that is easy to miss before you have committed to a workflow. Generation is also opt-in and needs your own keys, so a zero-key setup covers compose and edit only.

Where it is the wrong tool

This is not a hosted rendering service, and the README says so directly: there is no managed backend for generation. If your deliverable is a cinematic shot you cannot source yourself, the project will not produce it without provider keys you supply and pay for. The design also assumes an agent that can run a shell or speak MCP. If your workflow is a person sitting in a GUI timeline dragging clips, plan.json is a worse interface than a track editor, not a better one. And the re-render claim, while central to the pitch, is scoped: the README says changing one line re-renders only that piece, which is an architectural property of segment-level delegation, not a guarantee about every edit you might make to a composition. Anyone whose main need is frame-accurate manual grading should look elsewhere.

How it differs from running ffmpeg scripts by hand

The obvious alternative is a folder of shell scripts wrapping ffmpeg, and the difference is not capability but representation. A shell script is imperative and one-directional: it runs and produces a file, and the only record of what happened is the script itself. OrkasVideoStudio keeps plan.json as the contract, so the timeline is an artifact you can read, diff and re-render partially, and the stage skills carry production knowledge that a script would have to encode as comments. The trade-off is a dependency stack. You now need Node 22, pnpm, the pinned HyperFrames 0.7.60 dependency and an agent that understands the skill format, in exchange for a plan file that survives between sessions. If your videos are one-off and small, that stack is overhead. If you are producing the same format repeatedly and want the agent to remember the shape, the plan is the point.

Licence, maintenance and what to check before adopting

The licence is MIT, which permits commercial use and modification, and the repository is not archived, with the last push recorded on 2026-09-10. The project began as the built-in video agent inside the Orkas desktop app, where the README says it was validated end-to-end, and was then extracted into this agent-agnostic toolkit. That origin cuts both ways. It suggests the pipeline has been exercised against real deliverables, but it also means the standalone packaging is newer than the capability, which is consistent with the npm publication still being in progress. Maintenance cost in practice is the dependency chain: Node 22, ffmpeg and ffprobe on PATH, the pinned HyperFrames version, and whichever provider keys you enable for generation. Before committing, run `ovs doctor` on the target machine, then `ovs skills` and `ovs skill video-router` to confirm the knowledge pack loads into your agent, and only then attempt a compose-only draft with no provider keys to see whether the zero-key trunk behaves as the README describes. This is not legal advice; read the MIT text in the repository before relying on it for a commercial deliverable.

Editorial conclusion

Adopt OrkasVideoStudio if you already run Claude Code, Codex or Cursor and want video assembly to live in the same shell session as the rest of your work, and if you are comfortable installing from source because the npm packages are not published yet. Do not adopt it if you need a hosted render farm, a GUI timeline, or a support contract; there is no managed backend and generation depends on your own provider keys. Verify first that `ovs doctor` passes on your machine with Node 22 or later plus ffmpeg and ffprobe on PATH, then run `ovs skills` and confirm the video-router skill actually loads in your agent before you plan any real deliverable.

Official sources

1. Issues
2. License: MIT
3. Orkas-AI/Orkas-VideoStudio on GitHub
4. Project website
5. README