Architecture: the five layers#

Clipkit is not one product. It's five layers that stack, and they solve different jobs: a JSON protocol, a GPU runtime, an embeddable editor, agent tooling, and a hosted render service. People show up wanting one of them and accidentally read the docs for another, so this page says what each layer is, what it costs, what license it carries, and which one you actually want.

The short version, top to bottom:

  what authors videos                     what it is              license
  ─────────────────────────────────────────────────────────────────────────
  MCP server + CLI                        agent + terminal        Apache-2.0
  Editor (@clipkit/editor)                embeddable timeline UI  Apache-2.0
  ─────────────────────────────────────────────────────────────────────────
  Protocol (CKP/1.0)                      the JSON contract       Apache-2.0
  ─────────────────────────────────────────────────────────────────────────
  Runtime (@clipkit/runtime)              deterministic GPU       BSL 1.1
                                          compositor              (free tier)
  ─────────────────────────────────────────────────────────────────────────
  where pixels come out
  ├─ in the browser        free WebCodecs export, no server leg
  ├─ on your machine       @clipkit/renderer drives headless Chrome
  └─ hosted render         cloud GPU, ProRes / AV1 / alpha         paid

Everything above the protocol writes it. Everything below the protocol executes it. That's the whole trick: agents, editors, and pipelines all produce the same JSON document, and one engine renders it identically everywhere.

Layer 1: the protocol (CKP/1.0)#

The protocol is a versioned JSON schema that describes a video: elements, layers, timing, animations, audio. A document that validates against it is called a Source, and validation is the contract. npx clipkit validate video.json runs the same Zod schema the runtime, the MCP server, and the render service all consume. If it passes there, it renders.

This layer is Apache-2.0 and independently implementable. You could write your own renderer against the spec and never touch our code.

The design bet is that structured data beats code as an authoring target for machines. It's measurable: across a 13-brief corpus, the same videos take a median 1.63x fewer tokens as Clipkit JSON than as Remotion TSX, with no brief coming out worse. And because a schema can be validated before anything renders, an agent finds out its video is wrong in milliseconds, not after a failed render.

Read the spec at Protocol, or the field reference for what a Source can contain.

Layer 2: the runtime#

@clipkit/runtime is the GPU compositor that turns a Source into pixels. It runs on WebGL2 and WebGPU, and it's deterministic: the same Source produces byte-identical output wherever it runs. Determinism is what makes the rest of the stack trustworthy. The preview you scrub in the editor, the free export in the browser, and the file the render service hands back are the same pixels.

It runs in the browser today. The engine is portable by design, and the hosted service already runs the same protocol on server GPUs; treat "browser" as the current front door, not the boundary of the architecture.

The runtime is the one layer that isn't Apache-2.0. It ships under the Business Source License 1.1: source-available, free for dev, test, and non-commercial use without limits, and free in production up to 250 rendered output-minutes per month per organization. Past that you need a commercial license. Every release converts to Apache-2.0 four years after it ships. The BSL is why the editor above it can be genuinely open: the engine funds the stack, so nothing else has to.

Layer 3: the editor#

@clipkit/editor is a browser timeline editor built on the runtime, published Apache-2.0. It's a React component you embed, not a SaaS you link out to. Storage is an injected adapter (an AssetStore port you implement against your own backend), so the editor package contains zero database code and doesn't care whether assets live in S3, Supabase, or your own API.

Use it two ways. As a product surface: embed a video editor in your own app, themed to match, with your storage underneath. Or as a human touch-up pass at the end of a machine pipeline: an agent authors the Source, a person opens it on a timeline and nudges the details. The no-login editor on this site is the stock component running against a demo adapter, which makes it both the live demo and the reference integration.

The honest boundary: the editor previews and exports through the runtime, so the runtime's BSL free tier is what governs production rendering inside your embed. Embedding the BSL runtime this way is explicitly permitted.

Layer 4: agent tooling (MCP server + CLI)#

@clipkit/mcp-server exposes authoring, validation, preview, and editor hand-off as MCP tools, hosted at clipkit.dev/mcp with no auth required, or run locally over stdio. @clipkit/cli covers the terminal: validate, render, render --cloud.

This layer exists because agents author differently than humans. They don't read a docs site; they load an 8KB authoring card and call a validator in a loop. That loop is cheap and it converges: in a 60-cell benchmark across three model tiers, agents using Clipkit shipped a valid video in 15 of 15 attempts, the only tool in the comparison with zero failures (Remotion 13/15, HyperFrames 10/15). Switching a model from the full doc pack to the card-plus-validator loop cut one tier's authoring cost about 3.3x in our retest.

Everything here is Apache-2.0, and it's a thin layer: the MCP server writes protocol JSON like any other client. There's no agent-only capability hiding in it.

Layer 5: hosted rendering#

The layers above give you two free paths to an MP4: export in the browser (WebCodecs, no server involved, speed depends on the machine doing it: roughly 222 fps at 1080p on an Apple M4, 4 to 5 fps on an Intel i9 we also publish) or run @clipkit/renderer on your own hardware, which drives the runtime in headless Chrome.

The hosted service is for what those can't do: render from a server-side pipeline with no browser anywhere, guarantee speed independent of your user's laptop, and produce formats the browser can't encode, like ProRes, AV1, and transparent output. It's clipkit render --cloud, or POST a Source to the API and get a file back. This is the paid layer; pricing has the numbers.

Which layer do you want?#

What Clipkit is not#

Two boundaries worth stating plainly, because they decide whether this stack fits your problem.

Clipkit is not an AI video generator. There are no diffusion models here; nothing hallucinates pixels. It's deterministic composition and rendering that sits downstream of generative tools: an agent (or your code) decides what the video says, Clipkit turns that decision into frames, exactly, every time. If you want text-to-video footage synthesis, pair Clipkit with a generator and composite the result.

And Clipkit's expressive ceiling is the schema. If your video is really an arbitrary React app, custom CSS, or a specific npm package's rendering, Remotion is a better fit; that's a real tradeoff, not a knock. The schema covers the large majority of programmatic video, and it's what makes validation, determinism, and agent reliability possible in the first place.

FAQ#

Is Clipkit open source?#

Four of the five layers are Apache-2.0: the protocol, the editor, the renderer harness, and all the agent tooling. The runtime is source-available under BSL 1.1 with a free production tier (250 rendered output-minutes per month, unlimited dev/test and non-commercial use), and each runtime release converts to Apache-2.0 after four years. So: open protocol, open tooling, source-available engine with a scheduled path to open.

What's the difference between the editor and the runtime?#

The runtime is the engine: it takes a Source document and produces pixels, and it has no UI at all. The editor is a React timeline component that lets a human create and modify that document, using the runtime underneath for live preview. You can ship the runtime without the editor (headless pipelines do), but the editor always brings the runtime with it.

Can I embed the editor without using Clipkit's cloud?#

Yes, that's the intended shape. The editor is Apache-2.0, storage goes through an adapter you implement against your own backend, and export can run entirely in the user's browser with no Clipkit server in the loop. The only dependency that isn't yours is the BSL runtime underneath, which is free in production up to the 250 output-minutes-per-month tier.

Do I need React to use Clipkit?#

Only for the editor, which is a React component. The protocol is plain JSON you can produce from any language, the CLI and renderer are Node tools, and the MCP server works with any MCP-capable client. A Python service POSTing JSON to the render API never touches React.

Can I self-host rendering completely?#

Yes. @clipkit/renderer drives the runtime in headless Chrome on your own hardware and writes the MP4 locally; the CLI's clipkit render uses the same path. It needs a system Chrome or Chromium install because the export path uses WebCodecs. Production rendering above the runtime's free tier needs a commercial license, and hosted-only formats like ProRes and transparent output stay hosted-only.

Is the protocol stable enough to build on?#

The protocol is versioned (CKP/1.0), every document declares its version, and validation is a hard gate shared by every consumer: the same Zod schema runs in the CLI, the MCP server, the runtime, and the render service. Changes land as versioned revisions of the spec, not silent behavior shifts. It's Apache-2.0 and specified independently of our implementation, so building your own tooling against it is a supported outcome, not a loophole.

How do agents fit into this architecture?#

An agent is just another author of protocol JSON. It connects to the MCP server (hosted, no auth, or local stdio), loads the 8KB authoring card instead of reading docs, and loops on the validator until the Source is correct, which usually takes milliseconds per iteration. In our 60-cell benchmark that loop shipped a valid video on every single attempt, across every model tier we tested. The rest of the stack doesn't know or care that an agent was involved.

Why is the runtime BSL when everything else is Apache?#

Because someone has to fund the stack, and we'd rather it be the engine than the surfaces you build on. The BSL keeps the runtime source-available and free for dev, test, non-commercial, and modest production use, while reserving large-scale commercial rendering as the thing that pays for development. The four-year Apache conversion is the commitment device: every version you can read today has a date on which it becomes fully open.

What's the difference between browser export and hosted rendering?#

Same engine, same pixels, different machines. Browser export runs on your user's GPU via WebCodecs, costs nothing, and is fast exactly when the hardware is (222 fps at 1080p on an M4; single-digit fps on older Intel laptops). Hosted rendering runs the same protocol on server GPUs at predictable speed, works from headless pipelines, and unlocks ProRes, AV1, and alpha-channel output. Most products use both: free browser export as the default, hosted for the pro path.

Can I write my own renderer for the protocol?#

You can, and the license is built so you may: CKP/1.0 is Apache-2.0 and independently implementable. You'd reimplement the compositing semantics the spec defines and validate documents with the published schema. What you'd give up is byte-identical parity with our runtime and the shared conformance surface, which is why most integrations implement the protocol on the authoring side and keep our runtime on the rendering side.

Which npm package is which layer?#

@clipkit/protocol is the schema and types. @clipkit/runtime is the GPU engine. @clipkit/editor is the embeddable timeline UI. @clipkit/renderer is the local headless-render harness, and @clipkit/mcp-server plus @clipkit/cli are the agent and terminal tooling. There are more packages on npm (patterns, music analysis, importers), but those five plus the CLI are the load-bearing ones, and this page's diagram maps onto them one to one.