Skip to content
Back to search

Orkas-VideoStudio

Turn your coding agent into a video studio: describe a video in plain language, and your agent writes the timeline and produces the file.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Orkas-AI/Orkas-VideoStudio with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Orkas-AI/Orkas-VideoStudio'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/orkas-ai--orkas-videostudio/badge.svg)](/listings/orkas-ai--orkas-videostudio)

HTML

<a href="/listings/orkas-ai--orkas-videostudio"><img src="/api/listings/orkas-ai--orkas-videostudio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** Node ≥ 22, and `ffmpeg` + `ffprobe` on your `PATH` (needed for edit / transcribe / local media QA). Compose drafts use a VideoStudio QA gate backed by the pinned [HyperFrames](https://github.com/heygen-com/hyperframes) `0.7.60` package dependency; `npx` is only a compatibility fallback. Generation is opt-in and needs your own keys.

> **Early development:** the npm packages are being published. Until then, install from source > — the `ovs` CLI works exactly the same.

From source (works today)

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
# optionally alias it:  alias ovs="node $PWD/packages/cli/dist/index.js"

From npm (once published)

npm i -g @orkas/video-studio     # provides the `ovs` command
ovs doctor                       # checks ffmpeg/ffprobe/node; guides any install

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 550 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # OrkasVideoStudio
  2. > Turn your coding agent into a video studio. Ask Claude Code, Codex, Cursor or any agent that
  3. > can run a shell or speak MCP for a finished video. It edits your footage, designs motion
  4. > graphics, adds narration, music and captions, generates missing shots with your own keys,
  5. > and delivers a checked MP4. You can keep editing that MP4 in a browser canvas.
  6. https://github.com/user-attachments/assets/be790302-0c4a-4972-995b-9ac9de75fa12
  7. OrkasVideoStudio is **not a black-box video agent**. Your agent does the thinking. This
  8. project gives it the parts it can't improvise:
  9. - **Video know-how.** A host-neutral `SKILL.md` pack, with `video-studio` as the entry skill.
  10. It covers when to ask and when to proceed, how ads, explainers, product demos, music cuts,
  11. presenter videos, short films and commentary differ, and how to check a cut before calling
  12. it done.
  13. - **Deterministic tools.** The `ovs` CLI and an MCP server that mirrors it. They cover the
  14. production timeline, ffmpeg editing, transcription, footage analysis and generation through
  15. your own provider accounts. [HyperFrames](https://github.com/heygen-com/hyperframes) does the
  16. page rendering and frame capture; `ffmpeg` does editing and measurement.
  17. - **An editable production.** Each video is a plain folder: a scene timeline
  18. (`videos/main/manifest.json`), an asset ledger, sourced product facts and an optional
  19. designed page. You, your agent and the browser canvas all edit the same files. Change one
  20. line of text, swap a picture or reorder scenes, then re-render.
  21. Editing, designed motion graphics, captions and transcription need **no API keys**. Image,
  22. video and speech generation are opt-in and use **your own** provider accounts. There is no
  23. hosted backend and no account to create.
  24. ---
  25. ## What you can ask for
  26. You ask once and get one finished video. The agent combines whatever the request needs in a
  27. single timeline:
  28. | Capability | What it covers |
  29. |---|---|
  30. | **Edit real footage** | Trim, join, reframe to 9:16 / 1:1 / 16:9, keep or mix clip sound, overlay, burn subtitles and normalize loudness. For long recordings it can also find highlights, rank repeated takes and remove silences or filler words, recording the evidence for each cut. |
  31. | **Designed motion** | Scenes built in HTML/CSS with animation: kinetic type, price cards, lower-thirds, data callouts and transitions. Editable words live in named text slots, so changing copy never means rebuilding a scene. |
  32. | **Sound and captions** | Narration for each scene, fitted to that scene's length. Licensed music beds that duck under speech. Captions from the narration text or from measured word timing. Cuts aligned to the beat. |
  33. | **Generated shots** | Images, video clips and generated presenters (talking-head) from your configured provider, for shots your material can't show. They are made only within the spending you approve. |
  34. For a script or storyboard, the agent stops at the document. For a finished video it works
  35. through to delivery. It shows you a plan or preview only if you asked for one, if the video
  36. runs longer than about two minutes, or if it must follow an exact script.
  37. ---
  38. ## Use cases
  39. Each row is a prompt you could give your agent. The `video-studio` skill picks the tools.
  40. ### Advertising and marketing
  41. | You say… | What happens |
  42. |---|---|
  43. | *"Make a 20-second vertical ad for this desk lamp from these photos and the product page."* | It imports the photos, records the price and specs as sourced facts, designs the hook, feature and price scenes, adds narration and captions, then checks, renders and delivers. |
  44. | *"Make a 30-second launch video for our app from its website."* | It captures the real product pages in your browser, uses the product's own words and screens, and builds the scenes around them instead of redrawn mock-ups. |
  45. | *"Make a 30-second presenter video where a generated host introduces this serum."* | It writes the monologue first, makes one key image of a fictional host and reuses it on every clip, generates the talking clips with your video provider, and keeps prices and claims as editable on-screen text. |
  46. | *"Make a 15s 9:16 promo from this script: generate the opener, compose the feature callouts, one voiceover."* | One timeline combines the generated opener, designed feature scenes and a single narration track, and the finished file is checked before delivery. |
  47. ### Film and drama
  48. | You say… | What happens |
  49. |---|---|
  50. | *"Make a one-minute short film about a night-shift nurse, with the same two characters in every shot."* | It builds the story on one dramatic question, keeps one look line and key image per character so they stay consistent across shots, and generates the shots with your video provider within the budget you approve. |
  51. | *"Turn these three drama episodes into a 3-minute narrated recap."* | It transcribes the episodes, picks the scenes that carry the story, skips credits and next-episode previews, writes and voices the recap, and cuts your footage under it. |
  52. | *"Generate a 5s shot of the city at dawn for the opening."* | It confirms the provider, model and cost, makes one shot with your video provider and places it on the timeline next to your footage. |
  53. ### Editing
  54. | You say… | What happens |
  55. |---|---|
  56. | *"Turn this 1-hour screen recording into three 30s highlight clips with captions."* | Scene and quality analysis finds the good parts. Repeated takes are ranked, silences and fillers are cut, and captions are burned in from measured word timing. |
  57. | *"Clean the silences and 'um's out of my webcam take and tighten it."* | It detects silent gaps and filler words, makes a deterministic jump cut and records the evidence for every removed span. |
  58. | *"Add an English voiceover and subtitles to product-demo.mp4 and even out the loudness."* | It transcribes the video, translates and voices each line inside its picture window, mixes the voice over the existing sound, burns in subtitles and normalizes loudness. |
  59. | *"Cut these 20 clips from our trip to this track, on the beat."* | It measures the track's beats, cuts the clips to them and checks the beat alignment of the delivered file. |
  60. ### Explainers and tutorials
  61. | You say… | What happens |
  62. |---|---|
  63. | *"Make a 60s explainer on vector databases with a Chinese voiceover."* | It writes motion-graphic scenes, synthesizes the narration with your TTS provider and fits each line to its scene. |
  64. | *"Turn my screen recording of the settings page into a 90-second tutorial."* | It trims the recording, marks each control on the real interface step by step, and adds narration and captions. |
  65. ### Recreating popular videos
  66. | You say… | What happens |
  67. |---|---|
  68. | *"Recreate this viral video's structure and pacing for my product. Show me the plan first."* | It breaks the reference down, maps its beats to your material and waits for your approval before producing. |
  69. | *"This competitor ad performs well. Make ours with the same hook and rhythm, using our photos."* | It borrows the reference's hook, proof and call-to-action rhythm, not its content. Every claim comes from your product facts and every picture from your material. |
  70. Give your agent a **reference video file** and your own product assets, script or footage.
  71. Your agent can use OrkasVideoStudio to recreate its **narrative structure, visual style and
  72. editing pace** for the new content:
  73. 1. **Analyze the reference.** Inspect sampled frames and the relevant audio to identify the
  74. hook, the demonstration or proof, the order of information, the typography, the
  75. transitions, the pacing and the call to action.
  76. 2. **Plan the adaptation.** State what to keep and what to replace, then map reference
  77. moments to the new scenes or timeline. Adapt the timing to your actual narration and
  78. reading time.
  79. 3. **Produce and revise.** Compose motion graphics, edit your footage and generate missing
  80. visuals when needed. Locally authored text, captions, narration and clips stay separately
  81. editable. Text baked into generated footage can only be changed by changing that footage.
  82. This works best for motion-graphic explainers, SaaS and app demos, and product ads made from
  83. existing footage. Start with a file your agent can read, because downloading from
  84. social-platform share links is not built in. Exact camera moves, human performances and
  85. frame-by-frame matching are not guaranteed. Delivery checks don't score how closely the
  86. result matches the reference. For details, see the
  87. [reference-recreation workflow](./packages/skills/video-craft/references/reference-recreation.md).
  88. ---
  89. ## Install
  90. **Prerequisites:** Node ≥ 22, `pnpm`, and `ffmpeg` + `ffprobe` on your `PATH`. The pinned
  91. [HyperFrames](https://github.com/heygen-com/hyperframes) `0.7.60` package is installed as a
  92. dependency and renders pages in headless Chrome for checks and rendering; `npx` is only a
  93. compatibility fallback. Generation is optional and needs your own keys.
  94. ### From source (works today)
  95. ```bash
  96. git clone https://github.com/Orkas-AI/Orkas-VideoStudio.git
  97. cd Orkas-VideoStudio
  98. pnpm install && pnpm build
  99. alias ovs="node $PWD/packages/cli/dist/index.js"
  100. ovs doctor # checks Node, ffmpeg and ffprobe and explains how to install anything missing
  101. ```
  102. ### From npm (once published)
  103. The npm packages are not published yet. Once they are, the `ovs` command works the same way:
  104. ```bash
  105. npm i -g @orkas/video-studio # provides the `ovs` command
  106. ovs doctor
  107. ```
  108. ---
  109. ## Drive it from your coding agent
  110. The `ovs` CLI is the canonical interface, and the MCP tools mirror it. Use whichever of
  111. these your agent supports:
  112. **1) Native skills (Claude Code / Codex).** Install the skill pack so the agent finds it on
  113. its own:
  114. ```bash
  115. ovs skills --install --target claude # → ~/.claude/skills (add --scope repo for ./.claude/skills)
  116. ovs skills --install --target codex # → ~/.agents/skills (add --scope repo for ./.agents/skills)
  117. ```
  118. **2) MCP tools.** Register the server:
  119. ```bash
  120. claude mcp add ovs -- node /path/to/Orkas-VideoStudio/packages/mcp/dist/index.js # Claude Code
  121. codex mcp add ovs -- node /path/to/Orkas-VideoStudio/packages/mcp/dist/index.js # Codex
  122. # once the npm packages are published: claude mcp add ovs -- npx -y @orkas/video-studio-mcp
  123. ```
  124. **3) Self-describing CLI (any agent with a shell).** No loader needed:
  125. ```bash
  126. ovs skills # list the skills
  127. ovs skill video-studio # print the entry skill into context
  128. ovs --help # the full command surface
  129. ```
  130. Then just ask your agent for a video. It reads `video-studio` first and loads the stage and
  131. craft references it needs.
  132. ---
  133. ## How a production works
  134. The agent picks a short folder name and keeps everything in it:
  135. ```text
  136. lamp-ad/
  137. assets.json every file the video uses: id, kind, path, origin (upload / page / generated / edited)
  138. product.json sourced facts such as price and specs, referenced from scenes by id
  139. media/ imported and generated files
  140. videos/main/
  141. manifest.json the scene timeline: scenes, clips, text, narration, music tracks, captions
  142. index.html optional designed page for text and motion
  143. ```
  144. Scene order is playback order. Start times and the total length are computed from the scenes
  145. and never stored, so moving a scene can't leave the timing inconsistent. A price lives in
  146. `product.json` once, and every scene that shows it reads it from there. For parallel variants,
  147. such as other aspect ratios, languages or A/B cuts, the agent adds more video ids that share
  148. the same assets. See the [timeline contract](packages/skills/video-studio/references/timeline.md).
  149. A typical run:
  150. ```text
  151. ovs timeline import --production lamp-ad --inputs '["/path/to/lamp.jpg"]'
  152. ovs timeline prepare --production lamp-ad --video-id main
  153. ovs timeline check --production lamp-ad --video-id main
  154. ovs timeline snapshot --production lamp-ad --video-id main --out lamp-ad/preview.png
  155. # the agent inspects every sampled frame and fixes confirmed problems in one batch
  156. ovs timeline render --production lamp-ad --video-id main --out lamp-ad/render/main.mp4
  157. ovs timeline ship --production lamp-ad --video-id main --input lamp-ad/render/main.mp4
  158. ```
  159. `ship` measures the final file before recording it: duration, canvas, audio, loudness and
  160. narration coverage. Caption warnings are flagged for visual confirmation, and frames from the
  161. actual MP4 are returned. Every delivery becomes an immutable version. A render made before
  162. the latest change is rejected as stale, and earlier deliveries are never overwritten.
  163. Passing these checks doesn't certify visual quality. Visual review counts as `not_checked`
  164. until someone actually looks at the frames.
  165. When you explicitly accept a specific remaining finding, pass its exact code with
  166. `--accept-findings '["CODE"]' --accept-reason '<your decision>'`. The version records that
  167. decision, and every other error still blocks delivery. Writes are serialized with
  168. `.ovs-timeline.lock`; if a crash leaves it behind, confirm the owning process has stopped
  169. before removing it. The [timeline contract](packages/skills/video-studio/references/timeline.md)
  170. covers both.
  171. **Revisions stay cheap and local.** A changed word, cut, order, music bed or caption is
  172. edited in place. Only a changed spoken line gets re-voiced, and only a wrong shot gets
  173. regenerated, within the spending already approved. Editing caption text doesn't change the
  174. spoken audio. HyperFrames renders the full video each time; this portable build doesn't
  175. cache rendered scenes.
  176. ---
  177. ## Browser video canvas
  178. When `timeline import`, `timeline prepare`, `timeline render` or `timeline ship` succeeds
  179. (from the CLI or MCP), OVS opens that production's canvas in your default browser. Later
  180. commands reuse the same tab instead of opening new ones. The canvas edits the same files as
  181. the CLI and MCP, so changes flow both ways. It shows a view-only state while the agent is
  182. working.
  183. In the canvas you can:
  184. - **Watch and export.** Play the video, switch between delivered versions and download the
  185. one you want.
  186. - **Arrange material.** Upload, drop or paste footage, then move and connect cards on the
  187. board.
  188. - **Edit scenes.** Change words, order and pictures, and add, remove or put back scenes.
  189. - **Generate and redo shots.** Make a new image or video shot from a card, or generate an
  190. existing shot again. You choose references or first and last frames, plus the model,
  191. resolution and sound; options a model can't support are disabled. Step through earlier
  192. results and pick the one to use. It asks before every paid request.
  193. - **Update the video.** Ordinary scene edits are rendered and delivered locally, with
  194. progress shown on the video card. Changing a product fact, a narration line or the voice
  195. for the whole video produces a request for your agent, because those edits need its
  196. judgment.
  197. - **Tell the Agent.** Write a short request about a scene, shot, footage card or video. It
  198. is sent with that card's context.
  199. The canvas opens in Chinese and remembers the language you pick from 19 options.
  200. ### Sending requests back to your agent
  201. **Send** only delivers to the conversation that made the production. If that conversation
  202. can't receive the request, the draft stays in the canvas. Nothing is copied to the
  203. clipboard, replayed automatically or sent to a new session. Editing, updating and exporting
  204. keep working without a connected agent.
  205. - **Codex.** When `ovs` runs inside a Codex thread, the request is queued into that same
  206. thread. This needs Codex CLI 0.160.1 or newer with its local app server running. A closed
  207. or unloaded thread shows as unavailable.
  208. - **Claude Code.** Requests arrive through an MCP channel, which is a Claude Code research
  209. preview, and an ordinary MCP connection is not enough. Register the server with
  210. `--claude-channel`, then start Claude Code with the channel enabled:
  211. ```bash
  212. claude mcp add ovs -- node /path/to/Orkas-VideoStudio/packages/mcp/dist/index.js --claude-channel
  213. claude --dangerously-load-development-channels server:ovs
  214. ```
  215. Make the video through the `ovs` MCP tools so the canvas opens bound to that channel. A
  216. canvas opened from the shell CLI can't reach Claude Code. Claude Code shows a
  217. local-development warning at startup. Channels need a claude.ai login or a Console API key,
  218. and on Team and Enterprise plans an admin must enable them first. See
  219. [Claude Code channels](https://code.claude.com/docs/en/channels).
  220. ### Open a production yourself
  221. ```bash
  222. ovs studio --production ./lamp-ad # canvas only
  223. ovs studio --production ./lamp-ad --agent codex # canvas with its own Codex session
  224. ovs studio --production ./lamp-ad --agent claude # canvas with its own Claude Code session
  225. ```
  226. Keep the command running while you use the canvas. With `--agent`, the canvas runs a native
  227. session in the production folder that uses your CLI's own sign-in, model and permission
  228. settings. That session needs Codex 0.160.1+ or Claude Code 2.1.148+. Its permission prompts
  229. and questions appear in the canvas. It restores the saved session for the folder, unless you
  230. pass `--resume <session-id>` to hand over a specific session or `--new-session` to start
  231. fresh. Other options:
  232. - `--no-open` prints the access link without opening a browser.
  233. - `--port` picks the loopback port.
  234. - `--recover` reclaims a canvas whose previous owner has exited.
  235. To turn off automatic opening during production work, set `OVS_STUDIO_AUTO_OPEN=0`. It is
  236. already off in CI.
  237. ---
  238. ## BYO generation providers
  239. Configure providers in `~/.config/orkas-video-studio/config.json` (or `$OVS_CONFIG_DIR/config.json`)
  240. or with environment variables. Environment variables override the file.
  241. ```json
  242. {
  243. "tts": { "provider": "openai", "api_key": "…", "model": "gpt-4o-mini-tts", "voice": "…" },
  244. "image": { "provider": "gemini", "api_key": "…" },
  245. "video": { "provider": "kling", "api_key": "…", "model": "…" }
  246. }
  247. ```
  248. | Capability | `provider` values | Environment |
  249. |---|---|---|
  250. | Speech (`ovs speak`) | `openai`, `openai-compatible`, `doubao`, `minimax`, `aliyun` (Qwen / CosyVoice), `google`, `elevenlabs` | `OVS_TTS_PROVIDER` · `_BASE_URL` · `_API_KEY` · `_MODEL` · `_VOICE` · `_FORMAT` · `_PROXY_URL` |
  251. | Image (`ovs image`) | `openai` (any OpenAI-compatible endpoint, including Seedream), `gemini` | `OVS_IMAGE_PROVIDER` · `_BASE_URL` · `_API_KEY` · `_MODEL` |
  252. | Video (`ovs video`) | `doubao` (Seedance), `minimax`, `vidu`, `kling`, `google` (Veo), `google-cloud` (Veo), `runway`, `aliyun` (Wan), `atlas`, `muapi` | `OVS_VIDEO_PROVIDER` · `_BASE_URL` · `_API_KEY` · `_MODEL` |
  253. You can inspect a configuration without making any paid calls:
  254. ```bash
  255. ovs speech-capabilities # resolved voice/model/language profile, no secrets printed
  256. ovs video-models # what the configured video model supports
  257. ovs video-params --request '{"duration":5,"ratio":"9:16"}' # what that request would actually send
  258. ```
  259. Run `ovs narration fit` before and after synthesis so each narration line stays inside its
  260. scene or plan window. Video generation takes explicit reference images, ratio, duration,
  261. resolution and audio flags, so the provider call matches the approved plan. For `plan.json`
  262. projects, `ovs plan validate` also checks each generate segment's ratio, duration and
  263. operation against the configured `video.provider` before anything is generated.
  264. Some providers need a few more settings:
  265. - **Google Cloud Veo** uses `video.workspace_id`, `video.region`, and an API token or
  266. service-account JSON in `video.api_key`.
  267. - **Alibaba** speech uses its workspace endpoint in `tts.base_url`. Wan video needs
  268. `video.workspace_id` and `video.region`.
  269. - **Clone-only voices** need the voice id you enrolled with the provider.
  270. - **WebSocket speech** goes through `tts.proxy_url` only when you configure it.
  271. - **Video references** are passed as public image or video URLs. Supported counts and
  272. first/last-frame support vary by model.
  273. - **[MuAPI](https://muapi.ai)** must be selected explicitly with `video.provider: "muapi"`.
  274. When it is selected, `MUAPI_API_KEY` takes precedence over `OVS_VIDEO_API_KEY`; the key
  275. never selects MuAPI by itself. `video.model` / `OVS_VIDEO_MODEL` supports the validated
  276. Kling v2.1 endpoints `kling-v2.1-master-t2v`, `kling-v2.1-master-i2v`,
  277. `kling-v2.1-standard-i2v` and `kling-v2.1-pro-i2v`. Other slugs are rejected rather than
  278. sent with a mismatched body. Text-to-video defaults to `kling-v2.1-master-t2v`, and a
  279. first-frame `image_url` defaults to `kling-v2.1-master-i2v`. Duration is 5 or 10 seconds
  280. and ratio is `16:9`, `9:16` or `1:1`. Provider-neutral `resolution`, `generate_audio` and
  281. `quality` inputs stay compatible with signed plans: Kling ignores resolution and audio,
  282. and quality is validated but not sent. Edit and additional-reference controls are
  283. rejected until a matching MuAPI schema is supported. The default base URL includes
  284. `/api/v1`, and a custom one must include it too. See the
  285. [MuAPI API reference](https://muapi.ai/docs/api-reference) for the submit-and-poll
  286. contract and model-specific parameters.
  287. Provider model catalogs describe each provider's API contract. They don't guarantee live
  288. availability or pricing.
  289. ---
  290. ## What keeps generation bounded
  291. The agent uses your existing material wherever it serves the shot, and generates only what
  292. is missing. Having credentials configured doesn't count as approval to spend. Before any paid
  293. work, the agent confirms the provider, model, purpose, number of requests including retries,
  294. and estimated cost. It then sticks to that scope. Declining stops the paid calls for that
  295. request, and a bad shot gets at most two revised takes before the agent asks you to change
  296. the approach.
  297. Each paid request keeps a receipt next to its output. A video task whose outcome is unknown
  298. blocks another submission to the same output until you inspect it, and it is never replayed
  299. automatically. See [generation authority](packages/skills/video-studio/references/generation.md).
  300. `ovs speak` writes a request and audio receipt beside its output. It reuses only an exact
  301. matching request whose audio bytes are intact, so pass the approved `--language`, voice,
  302. model, speed and format; changing any of them invalidates reuse. It also claims the output
  303. before dispatch, which prevents concurrent duplicate calls.
  304. There is no hosted music service. Music comes from licensed files you supply, and the agent
  305. records each file's source and license.
  306. ---
  307. ## Command reference
  308. Run `ovs <command> --help` for each command's typed input. MCP tools use the same names with
  309. underscores, for example `timeline_prepare` and `edit_trim_silence`.
  310. | Area | Commands |
  311. |---|---|
  312. | Setup | `doctor`, `skills [--install]`, `skill <name>` |
  313. | Production | `timeline import · prepare · status · check · snapshot · render · ship`, `studio` |
  314. | Edit (ffmpeg) | `edit probe · trim · concat · reframe · burnsubs · overlay · extract-frame · loudness · normalize-loudness · mix · select · trim-silence · remove-fillers` |
  315. | Analyze | `transcribe`, `phrases`, `silence`, `scenes`, `quality`, `beats`, `activity` |
  316. | Narration | `narration timing · fit`, `speech-capabilities`, `speak` |
  317. | Generation | `image`, `image-prepare`, `video`, `video-models`, `video-params` |
  318. | Earlier projects | `composition prepare · reconcile`, `plan validate · summarize · promise-check · rank-takes`, `draft`, `render`, `lint`, `check`, `snapshot`, `gate transition`, `inspect` (alias of `check`) |
  319. Projects built with the earlier `plan.json` EDL and `composition-manifest.json` formats still
  320. work through the "Earlier projects" commands. New work uses the scene timeline. For an
  321. assembled `plan.json`, verify the finished file as well as its component footage:
  322. ```bash
  323. ovs plan promise-check project/plan.json --probe-produced --video project/render/video.mp4
  324. ```
  325. The equivalent MCP tool `plan_promise_check` accepts `probe_produced` and `video`. It
  326. measures duration, canvas, audio, integrated loudness and per-line voiced spans. Missing
  327. narration evidence fails the check, and caption warnings need a visual check when subtitles
  328. were burned in.
  329. ---
  330. ## How it compares
  331. HyperFrames, ffmpeg and whisper.cpp are **dependencies** here, not competitors.
  332. OrkasVideoStudio is the agent-facing layer on top of them: the knowledge, the delivery checks,
  333. the editable production and the canvas.
  334. | | OrkasVideoStudio | Programmatic frameworks (Remotion, Revideo) | AI SaaS editors (Descript, Opus Clip, Runway) | Thin MCP / ffmpeg wrappers |
  335. |---|---|---|---|---|
  336. | **Driver** | any coding agent, in natural language (CLI + MCP) | you hand-write React/TS | GUI / hosted | an agent, but tools only |
  337. | **Artifact** | editable scene timeline in a local folder, plus a browser canvas | code (re-run to render) | black-box timeline / hosted project | none |
  338. | **Scope** | footage editing + designed motion + narration + generation in one timeline | composition (programmatic) | mostly edit *or* generate, per product | whatever the tool exposes |
  339. | **Guidance** | ships "what makes a good video" as skills, plus deterministic delivery checks | none, you decide | product-opinionated | none |
  340. | **Keys / hosting** | zero-key core; **your own** keys for generation; local-first | your own infra | vendor keys + hosted, lock-in | varies |
  341. | **License** | MIT | may require a company license for teams | proprietary | varies |
  342. Reach for a **framework** when you want to hand-code every frame, or a **SaaS editor** when
  343. a GUI and hosting are the point. Reach for **OrkasVideoStudio** when you want your *agent*
  344. to make the video, keep the result as files you can inspect, edit and re-render, and stay
  345. local with your own keys.
  346. ---
  347. ## Relationship to Orkas
  348. OrkasVideoStudio began as the built-in **video agent in [Orkas](https://orkas.ai?source=gh-orkas-vs)**,
  349. the AI-team desktop app. It was proven end to end there, then extracted into this
  350. agent-agnostic, MIT-licensed toolkit.
  351. - **Inside Orkas**, it ships as a [built-in agent](https://orkas.ai/agents/video-studio/?source=gh-orkas-vs)
  352. with no separate install.
  353. - **Everywhere else**, you install it into your own coding agent as described above and get
  354. the same core capabilities through the `ovs` CLI, the MCP server and the canvas. Orkas
  355. account features, such as hosted providers, credits and chat publishing, are not part of
  356. this repository.
  357. Links: **[orkas.ai](https://orkas.ai?source=gh-orkas-vs)** · **[github.com/Orkas-AI](https://github.com/Orkas-AI)** ·
  358. **[this repo](https://github.com/Orkas-AI/Orkas-VideoStudio)**
  359. ---
  360. ## Packages
  361. | Package | What |
  362. |---|---|
  363. | `@orkas/video-studio-core` | scene timeline and legacy EDL schemas, delivery checks, decision helpers, narration timing, runtime and config |
  364. | `@orkas/video-studio-tools` | backends for timeline, render, edit, analyze, speech, image and video, plus the browser canvas |
  365. | `@orkas/video-studio` | the `ovs` CLI |
  366. | `@orkas/video-studio-mcp` | the MCP server (`ovs-mcp`), mirroring the CLI |
  367. | `@orkas/video-studio-skills` | the host-neutral `SKILL.md` knowledge pack |
  368. The technical plan and its history live in [`PLAN.md`](./PLAN.md). Notes for coding agents
  369. working on this repository are in [`AGENTS.md`](./AGENTS.md).
  370. ---
  371. ## Development
  372. ```bash
  373. pnpm install
  374. pnpm build # tsc per package (core → tools → cli / mcp)
  375. pnpm typecheck
  376. pnpm test # vitest
  377. pnpm benchmark # zero-key core correctness + throughput floors
  378. pnpm test:video # mock provider round-trip → real playable MP4 → ffprobe
  379. pnpm test:video:e2e # real three-scene production through the built CLI, plus CLI/MCP smoke
  380. pnpm verify # everything above; also the CI entry point
  381. ```
  382. `pnpm install` applies the versioned HyperFrames patch in [`patches/`](./patches/), which
  383. makes SDR H.264/H.265 output use the BT.709 matrix its metadata declares. An external
  384. `OVS_HYPERFRAMES_BIN` or the `npx` compatibility fallback doesn't get this patch, so that
  385. runtime must include an equivalent color fix.
  386. `test:video` never spends provider credits. A local fake Seedance endpoint returns a real
  387. H.264 fixture, which OVS downloads and verifies with `ffprobe`.
  388. `test:video:e2e` covers both production paths through the built CLI:
  389. - **The earlier composition path.** It makes a nine-second, three-scene 1080p production
  390. with composition prepare/reconcile, snapshot, the full draft gate, subtitle burning and
  391. final-file promise checks. It decodes the entire MP4 and checks scene order, visible
  392. motion, audible audio in every scene and burned subtitle pixels, and that a wrong
  393. delivery duration is rejected.
  394. - **The current scene timeline.** It renders a three-scene timeline through the real
  395. HyperFrames check and snapshot path. It checks scene colors, authored motion, decoded
  396. source-video motion, caption pixels, audio, immutable delivery and stale-render rejection.
  397. It also exercises the built CLI and MCP surfaces. Both video commands fail with an
  398. actionable error when a required runtime is missing. The ordinary test suite may skip
  399. runtime-heavy cases on machines without ffmpeg or a browser.
  400. `pnpm verify` must pass on the final candidate before any Git commit or PR. It includes the
  401. real production case and is also the CI entry point, and test-only changes follow the same
  402. rule. For sync or release review, keep and inspect the produced video, previews, final
  403. frames and reports:
  404. ```bash
  405. OVS_VIDEO_EVIDENCE_DIR=../Orkas-VideoStudio-artifacts pnpm test:video:e2e
  406. ```
  407. The evidence directory is opt-in, and each run uses its own child directory. Ordinary CI
  408. runs clean up their temporary media. Fixtures use original HTML/SVG and locally generated
  409. instrumental audio. They don't call paid providers or claim coverage of TTS or model quality.
  410. `pnpm benchmark` is zero-key and deterministic. It builds the core package, verifies the
  411. benchmark fixtures, then measures gate transitions, EDL validation and delivery summaries,
  412. composition-manifest validation and narration estimation. Each suite has a deliberately
  413. conservative throughput floor, so large regressions fail and normal machine variance does
  414. not.
  415. ## Versions
  416. All packages share one calendar version, `YYYY.M.D` (Asia/Shanghai date, no zero padding).
  417. Tagged releases use `v<version>` and are published as
  418. [GitHub Releases](https://github.com/Orkas-AI/Orkas-VideoStudio/releases); a published date
  419. version is never overwritten. Changes are listed in [CHANGELOG.md](CHANGELOG.md). This
  420. version is independent of the Orkas desktop app and its marketplace agent versions.
  421. ## License
  422. MIT — see [`LICENSE`](./LICENSE). Rendering uses the Apache-2.0 licensed
  423. [HyperFrames](https://github.com/heygen-com/hyperframes) `0.7.60` dependency. Editing and
  424. media checks use your system `ffmpeg`, and transcription is delegated to
  425. HyperFrames / whisper.cpp. [`PLAN.md`](./PLAN.md) explains how third-party runtimes are
  426. located, along with the licensing notes.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.