Kodecz

Kodecz is an open-source video rendering engine that turns a web page into an MP4. You write the video in HTML, CSS and JavaScript (React, WebGL, GSAP, Lottie or nothing at all), and Kodecz renders it frame by frame on an NVIDIA GPU with NVENC or on any CPU with x264, without taking a screenshot of every frame. It is an alternative to Remotion and HyperFrames, made to be driven by AI agents.

If Chromium can draw it, Kodecz can render it:

How it works

Two paths, one folder. Other tools take a screenshot of every frame and turn it into a PNG before encoding it; Kodecz never does, with or without a GPU.

Page is your index.html. Chromium draws frame N. On a GPU, that frame stays on the card as a texture; on the CPU, it is the raw frame Chromium just painted. Either way it goes straight to the encoder, NVENC on the card or x264 on the processor, and comes out as an MP4 with the audio mixed in. Frame N is always the same frame, in order, out of order or starting from the middle: same content, same timing.

Related MCP server: Agent Demo Studio

Numbers

Each square is one second. Rendering the same video on the same day, Kodecz keeps the processor busy for 19× less time (37.7 s → 2.0 s of CPU) and hands you the MP4 3.7× sooner (9.9 s → 2.7 s on the clock).

1080p · 150 frames · H.264 · RTX 5090 · how we measured

Against HyperFrames, measured on the same video and the same day: 11× less CPU (22.0 s → 2.0 s) and 2.4× sooner (6.4 s → 2.7 s) on the GPU. On a machine without a GPU, HyperFrames is slightly ahead on this video, which embeds a 1080p clip (26.3 s against 28.1 s of CPU); on a 27-second audiogram, Kodecz uses 2.4× less CPU (24.6 s against 59.9 s). All the numbers, and a script to reproduce them, are in docs/medidas.md.

Kodecz, Remotion and HyperFrames

Remotion and HyperFrames are good tools, and Kodecz learned from both. The capture methods come from their source code; the CPU numbers are ours, in docs/medidas.md.

Quick start

Status: early (0.1), Linux only, installed from a clone. It is the engine we render our own videos with. Parts of the code, the internal docs and some media attributes (data-inicio…) are still in Portuguese.

Requirements: Linux x86-64 with apt (installed from scratch on Ubuntu 24.04, Ubuntu 22.04 and Debian 12), Node 24 and about 5 GB of disk. You also need ffmpeg, weston, bubblewrap, a C/C++ toolchain (build-essential, cmake, ninja) and Rust 1.85+: the Chromium host is compiled on your machine, with or without a GPU. You do not have to install these by hand: the installer lists what is missing with the exact command for each, --sistema installs the apt packages, and Rust comes from rustup (no sudo). On a clean machine the whole install takes about 3 to 5 minutes with a fast connection (about 1 GB downloaded; compiling the host takes under a minute on 6 cores). For the GPU path, an NVIDIA GPU with NVENC (tested on an RTX 5090, driver 570+). Without one, the installer sets up the CPU path; HEVC and the transparent layer need the GPU. Other distributions: the installer still says what is missing, but the package names it prints are Debian's.

git clone https://github.com/konecz/kodecz && cd kodecz
./instalar.sh --sistema                    # checks the system, installs what is missing and renders a test video
npm link                                   # puts `kodecz` on your PATH (or use: node cli/kodecz.ts)
kodecz render my-video/ MyVideo out.mp4    # GPU when there is one, CPU when not (my-video/: see below)

./instalar.sh --verificar only says what is missing and installs nothing; ./instalar.sh without --sistema does everything that needs no sudo and prints the apt line for the rest. If Node 24 or Rust is missing, it stops and prints the command to install it; run it and then ./instalar.sh again. Each line starts with ✓ (done), ✗ (missing, with the command after →) or ! (a warning that does not block), and the last line is ready. Details (in Portuguese) in instalar/LEIAME.md.

kodecz render --help lists every option. The render prints one JSON line with the result on stdout. The original Portuguese names (--placa, --alfa, --de, --quadros, id="motor-video", qps…) still work for now.

Write a video

A video is a folder. index.html declares the size, frame rate and length; everything else is a normal web page.

<script type="application/json" id="kodecz">
{ "id": "MyVideo", "width": 1920, "height": 1080, "fps": 30, "frames": 150 }
</script>

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Schibsted+Grotesk:wght@800&display=block">
<style>
  :root { --fps: 30 }
  body { margin: 0; height: 100vh; display: grid; place-items: center; background: #0e0e10; color: #f4f4f5 }
  h1 {
    font: 800 120px/1 "Schibsted Grotesk", sans-serif;
    animation: in 0.6s cubic-bezier(.3, 0, .2, 1) both;
    animation-delay: calc(15 * 1s / var(--fps));    /* enters on frame 15 */
  }
  @keyframes in { from { opacity: 0; transform: translateY(40px) } }
</style>

<h1>Hello, frame 15.</h1>

Save it as my-video/index.html and it renders as is: kodecz render my-video/ MyVideo out.mp4. The page has no background of its own, so give body one (an empty page renders black). Google Fonts linked from the page are downloaded on the first render and cached. Your own video and audio files go next to index.html:

<video src="presenter.mp4" data-inicio="0" data-quadros="150"></video>
<audio src="music.wav" data-inicio="30" data-volume="0.6"></audio>

• The block: width and height are the size in pixels (even numbers, width at least 800, up to 8192), fps the frames per second and frames the length in frames. The id is the name you pass to the commands. The full format is in docs/formatos/linha-do-tempo.md.

• Animation: CSS @keyframes, element.animate(), GSAP and Lottie (bring your own copy). Kodecz pauses the page's timeline and puts every animation at N / fps seconds before drawing frame N.

• Canvas and WebGL: define window.kodecz_frame(n, ms); it runs before each frame and must depend only on n.

• Video and audio: <video> and <audio> with data-inicio (first frame), data-quadros (length in frames), data-recorte (frames cut from the start of the file), data-volume and data-velocidade (speed). Kodecz decodes them itself and mixes the audio in a single pass. On the GPU path, H.264 and HEVC video is decoded with NVDEC and composited under the page on the card, never inside the browser.

• Not allowed: requestAnimationFrame, timers and the wall clock. They do not follow frame N. The render's JSON line counts the animations that do not follow the page timeline (animacoesSoltas) and the CSS transitions it sent straight to their end (transicoesAoFim).

For AI agents

Kodecz is made for any agent to write video with: a coding agent in a terminal, an agent in your own pipeline, or a script calling a model. Nothing in it is tied to one vendor. The agent needs only what it already handles: files, shell commands, HTML and CSS, and JSON.

• The format is plain web. A video is an index.html and its files. Any model that writes web pages can write a video, and any tool that edits files can change one.

• Kodecz blocks (blocos/): each editing technique (one-line captions, zoom to the end of a sentence, text that avoids the face...) is a folder with a KODECZ.md in plain Markdown (what, when, parameters, where it came from), the CSS, a snippet to paste and a right and a wrong example. An index lists them all, so an agent can find the right one without reading everything.

• Automatic checks: kodecz check my-video/ MyVideo looks at every frame of the page without rendering the video (text over a face, captions on one line, the safe area of a declared destination, contrast over the real background, a zoom that ends with the sentence) and answers with one JSON line plus a picture of each problem, so the agent can fix it before a human looks. It needs a one-time node conferencia/preparar.ts.

• Previews in one to two seconds (kodecz preview), so the agent sees what it wrote instead of guessing.

Install the Kodecz skills

Three skills teach an agent the method: kodecz (make a video: write, preview, check, fix, render), remotion-to-kodecz and hyperframes-to-kodecz (port a project, with the API mapped one to one). They need Kodecz installed on the machine (quick start above).

The skills are plain Markdown in skills/, in the open Agent Skills format.

FAQ

Does Kodecz work without a GPU?

Yes. Without an NVIDIA GPU, Kodecz renders on the CPU: Chromium paints in software and the raw frame goes straight to x264. The same folder renders on both, frame for frame.

Is Kodecz an alternative to Remotion?

Yes. Both turn code into video. Remotion asks you to write React components; Kodecz takes any web page. On the same 1080p video with a presenter, Kodecz used 10 times less CPU and finished 3 times sooner on the GPU path.

Which AI agents can use Kodecz?

Any agent that can write files and run commands: Claude Code, Codex, Cursor, Gemini CLI or your own. The format is plain HTML, the editing blocks are Markdown and the checks answer in JSON. See AGENTS.md.

Is the output deterministic?

Frame N depends only on the page and on N: rendering in order, out of order or from the middle gives the same content at the same moment. In our test compositions the pixels are identical too. In real videos, Chromium can rasterize animated text slightly differently from one run to the next, by up to 2 color levels out of 255, which you cannot see. Timers and the wall clock are not allowed in a composition.

Which formats does it export?

MP4 with H.264 (default) or HEVC (GPU only), a transparent layer as raw HEVC with alpha (--alpha, GPU only, no audio), and AAC audio mixed from every <audio> and <video> on the page.

Why Node 24 and Rust, and why does the installer suggest curl | sh?

Node 24 runs the TypeScript sources directly (type stripping), so there is no build step and nothing to transpile. Rust compiles the Chromium host that captures the frames (CEF 156, on every machine) and, with an NVIDIA GPU, the native module that talks to Vulkan and NVENC; they are built on your machine because a prebuilt binary would have to match your glibc and driver. The curl … | bash (nvm) and curl … | sh (rustup) lines the installer prints are only suggestions, because both install without sudo. Install Node 24 and Rust 1.85+ any way you like (your distribution's packages, asdf, mise, a tarball): the installer only checks that node and cargo are there.

Why does Chromium run with --no-sandbox?

Chromium's sandbox on Linux needs a chrome-sandbox helper owned by root with the SUID bit (or unprivileged user namespaces, which Ubuntu 24.04+ restricts with AppArmor), and the install does nothing as root unless you pass --sistema. So today both the render host and the Electron used by kodecz check start Chromium with --no-sandbox. What it loads is your own composition, served from your folder over 127.0.0.1; every other request is blocked, except Google Fonts downloads for fonts missing from the local cache. Do not point Kodecz at pages you do not trust. The installer prints a warning with the first step, making chrome-sandbox root-owned with SUID (sudo chown root:root …/chrome-sandbox && sudo chmod 4755 …/chrome-sandbox); running with the sandbox on by default is still on our list.

Patents

Kodecz contains no video codec. It asks the NVENC encoder in your GPU (or the ffmpeg installed on your system) to encode H.264 or HEVC. Those formats are covered by patent pools; using them in a product you sell or distribute may need a license from those pools, as with any software that writes H.264 or HEVC. See docs/patentes.md.

License

Apache-2.0. Third-party notices in NOTICE and docs/licencas/. The Schibsted Grotesk and IBM Plex Mono fonts in marca/fontes/ are under the SIL Open Font License.

The Kodecz name and logo are brand assets of Konecz; see docs/marca.md.

Authors

Kodecz was created by Pedro Henrique Lahr and Vanessa Cristine at Konecz. See AUTHORS.