multiplane 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.en.md

@@ -0,0 +1,322 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/LBEILC/Multiplane/main/app/design/icons/readme-dark.svg">
+  <img src="https://raw.githubusercontent.com/LBEILC/Multiplane/main/app/design/icons/readme-light.svg" width="72" height="72" alt="">
+</picture>
+
+# Multiplane
+
+English · [简体中文](README.md)
+
+A local, headless HTML video renderer for AI agents. **A shot is an ordinary web page**: the page implements `render(t)`, and the image depends only on time `t`. Multiplane captures frames with headless Chromium, applies post-processing such as supersampling, motion blur, and film grain, encodes video with FFmpeg, and checks whether a shot is deterministic.
+
+<img src="https://raw.githubusercontent.com/LBEILC/Multiplane/main/docs/images/hero.webp" width="720" alt="3D cards rendered by Multiplane, with depth of field and motion blur">
+
+> Version `0.3.0`. The full test suite passes in CI on Windows, macOS and Linux; Windows has also been verified on a real machine. Interfaces may still change before 1.0.
+
+The name comes from Disney's multiplane camera: flat artwork placed at different depths, photographed frame by frame with real depth of field. Here, this corresponds to layered web content, a 3D card layer, and accumulated depth of field.
+
+## Features
+
+- **No new framework to learn**. Shots use HTML, CSS, and JavaScript, which agents are well suited to write.
+- **Lint before rendering**. `lint` runs without a browser in under a second. It flags wall-clock time, random numbers, CSS animations, remote resources, and other patterns that break determinism, with file, line, and column locations. Rendering commands run it automatically before starting.
+- **Verifiable**. `verify` renders the same frames out of order, after page reloads, and with single and multiple processes, then compares them pixel by pixel. Mismatches include the affected times, regions, and diff images.
+- **Motion blur respects hard cuts**. Each frame uses multiple time samples within the shutter interval, blended in linear light. Images on opposite sides of the shot's declared hard cut times, `cuts`, are never blurred together.
+- **3D layer and accumulated depth of field** (optional, `multiplane/three`): place image cards in 3D space and accumulate multiple samples for real out-of-focus blur, combined with motion blur.
+- **Machine-readable**. All commands support `--json` and emit an event stream with stable error codes. Each run has its own job directory, supports progress queries, and can be cancelled.
+- **Stills too**. `stills` writes PNG frames at the times you choose, with the same supersampling, motion blur, depth of field and alpha as video. Use it to check frames, or to produce final images such as covers, posters and illustrations.
+- **Deterministic**. The renderer itself introduces no wall-clock time or unseeded random numbers. The same input in the same environment produces identical pixels, backed by tests.
+
+## What it looks like
+
+**Motion blur.** Left: no motion blur. Middle: a fixed 8 samples, so fast spinning spokes break into separate copies. Right: samples added automatically according to how far things move, giving a smooth streak. The bottom row is a close-up.
+
+<img src="https://raw.githubusercontent.com/LBEILC/Multiplane/main/docs/images/motion-blur.png" width="800" alt="Motion blur: none, fixed 8 samples, samples added automatically">
+
+**Cuts stay clean.** The first frame after a cut. Left: the cut is not declared, and motion blur mixes in the colour and the circle from the shot before it. Right: the shot declares `cuts`, and the cut is clean.
+
+<img src="https://raw.githubusercontent.com/LBEILC/Multiplane/main/docs/images/hard-cut.png" width="800" alt="Cut: not declared and declared with cuts">
+
+**3D depth of field.** The same cards, focused on the foreground and on the background. The defocus is accumulated from many samples rather than blurred afterwards from a depth map, so foreground edges do not bleed and the background does not leak into foreground outlines. The bottom row is a close-up of the foreground card.
+
+<img src="https://raw.githubusercontent.com/LBEILC/Multiplane/main/docs/images/depth-of-field.png" width="800" alt="Depth of field: focused on the foreground and on the background">
+
+## Quick start
+
+Requires Node.js 24 or later and FFmpeg with libx264 support.
+
+```sh
+npm install multiplane
+npx playwright install chromium
+npx multiplane doctor
+npx multiplane render node_modules/multiplane/examples/animation.html
+```
+
+Recent npm versions do not run install scripts of dependencies, so the second command downloads the Chromium build that Playwright uses. To work from a clone of this repository instead, run `npm install` in it and render `examples/animation.html` directly.
+
+Give your agent the usage skill with `npx multiplane skill install --host all` (Claude Code: `~/.claude/skills/multiplane`, Codex: `~/.agents/skills/multiplane`), or let the desktop app install it. Start a new agent session afterwards.
+
+In a clone of this repository, `npm install` downloads that Chromium build itself, reusing it if already installed; in an offline environment, set `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` to skip the download, then run `npx playwright install chromium` later. On Linux, Chromium also needs system libraries: run `npx playwright install-deps chromium` once (`doctor` tells you when they are missing).
+
+### FFmpeg
+
+Multiplane does not bundle FFmpeg. Install one that supports libx264:
+
+| System | One way to get it |
+|---|---|
+| Windows | a build from the [official FFmpeg download page](https://ffmpeg.org/download.html) |
+| macOS | `brew install ffmpeg` |
+| Linux | your distribution's package, for example `sudo apt-get install ffmpeg` |
+
+The licence of FFmpeg depends on the build you install. Then tell Multiplane where to find it using one of these methods, in priority order:
+
+1. The command-line option `--ffmpeg <path>`;
+2. The environment variable `MULTIPLANE_FFMPEG`;
+3. `ffmpeg` in the user config file (see "User config and job index" below);
+4. The system PATH.
+
+To save the path once for every project, run `npx multiplane config set ffmpeg <path>`; it also checks the file and reports whether it is usable.
+
+The default is software encoding with `x264`. With an NVIDIA GPU, use `--encoder nvenc-h264` or `--encoder nvenc-hevc`. `doctor` checks whether FFmpeg can run and supports the required encoders.
+
+## Write a shot
+
+```html
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>Example</title>
+<link rel="stylesheet" href="/multiplane/runtime/shot.css">
+<style>
+  #stage { width: 1920px; height: 1080px; background: #111; }
+  #box { position: absolute; left: 0; top: 490px; width: 100px; height: 100px; background: #eee; }
+</style>
+<div id="stage"><div id="box"></div></div>
+<script src="/multiplane/runtime/shot.js"></script>
+<script>
+const box = document.querySelector('#box');
+Shot.define({
+  duration: 4,
+  fps: 30,
+  render(t) {
+    box.style.transform = `translateX(${Math.min(t / 3, 1) * 1820}px)`;
+  },
+});
+</script></html>
+```
+
+There are only three requirements:
+
+- Draw everything inside `#stage`, with fixed CSS width and height defining the frame dimensions;
+- Make `render(t)` synchronous. The same `t` must always produce the same image;
+- Use local files for fonts, images, and other assets, and finish loading them in `setup()` / `ready`.
+
+For the full contract, patterns that break determinism, and 3D layer usage, see the agent instructions in [`skills/multiplane/SKILL.md`](skills/multiplane/SKILL.md). This file is also a skill that agents can load.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `multiplane lint <shot>` | Static code checks without a browser |
+| `multiplane render <shot>` | Render to MP4 |
+| `multiplane stills <shot>` | Write PNG stills at given times plus a contact sheet; for checking frames or for final high-quality images |
+| `multiplane verify <shot>` | Run a determinism check |
+| `multiplane inspect <shot>` | Print a shot's duration, frame count, stage size, cuts and `meta` without rendering |
+| `multiplane serve` | Serve shots on 127.0.0.1 for opening in a browser while writing them |
+| `multiplane benchmark` | Measure rendering speed at different worker counts on this machine; later renders use the fastest |
+| `multiplane doctor` | Check Node, the browser, GPU rasterization, FFmpeg, and optional three.js |
+| `multiplane status <job>` | View job status |
+| `multiplane cancel <job>` | Stop a job |
+| `multiplane wait <job>` | Wait for a job to finish and print its events, for example after an agent session restarts |
+| `multiplane config get\|set\|unset` | Read or change the user config |
+| `multiplane skill status\|install\|remove` | Install, update or remove the agent skill for Claude Code and Codex |
+
+Shot paths are relative to the resource root `--root` (the current directory by default). Each run has its own job directory, `out/jobs/<jobId>/`. Without `--out`, artifacts are written there (video, `stills/`, `verify/`), so runs do not overwrite each other. See `artifacts` in the result for the final paths. `--out` sets the output location. An existing target is rejected unless `--overwrite` is given. `render`, `stills`, and `verify` automatically run `lint` before starting and stop on errors. Use `--no-lint` to skip it. `npx multiplane <command> --help` lists all options for that command.
+
+Common `render` options:
+
+| Option | Meaning |
+|---|---|
+| `--from` / `--to` | Render a range only (seconds, end time excluded) |
+| `--fps` | Override the shot's frame rate |
+| `--scale` | Output scale; for example, `2` outputs a 1920×1080 shot at 3840×2160 |
+| `--draft` | Fast preview preset: capture at a scale of at most 0.5 and upscale, no motion blur, no grain. Lower quality by design; explicit options override it. Also available for `stills` |
+| `--render-scale`, `--upscale` | Capture at a lower scale, then upscale (`lanczos` / `neighbor`); the capture scale must not exceed `--scale` |
+| `--motion-blur`, `--shutter`, `--adaptive-blur` | Time samples per frame, shutter fraction, adaptive sampling |
+| `--quality` | Quality preset: `draft` (same as `--draft`), `standard` (default), `high` (rarely needed; see below). When the shot has motion blur, samples are added according to how far things move locally, up to 64 for `standard` and 256 for `high`; see below |
+| `--max-motion-blur` | Custom limit for adding samples, overriding the preset; set it equal to `--motion-blur` for a fixed count |
+| `--grain` | Film grain intensity |
+| `--no-post` | Disable all post-processing |
+| `--workers` | Number of parallel browser processes; by default the count measured by `multiplane benchmark`, or an estimate from CPU, memory and resolution; see "Parallel workers" below |
+| `--raster` | `gpu` (default) or `software` |
+| `--format`, `--alpha` | Output format `mp4` (default), `webm` (VP9) or `mov` (ProRes 4444); `--alpha` keeps transparency (WebM and MOV only, also for `stills` and `verify`). See "Transparent video" below |
+| `--encoder`, `--max-bitrate` | Encoder, bitrate limit (Mbps) |
+| `--audio`, `--audio-offset` | Mix in one audio track with an offset (seconds) |
+
+The shot's `post` values are defaults. Command-line options override them.
+
+## Machine-readable output
+
+With `--json`, stdout contains one JSON event per line (NDJSON). The last line is always the final result:
+
+```json
+{"schema":"multiplane/1","type":"result","command":"render","ts":"2026-10-11T09:30:09.120Z","ok":true,"code":null,"message":null,"artifacts":[{"path":"/abs/out/jobs/20261011-093000-animation-3f2a/animation.mp4","kind":"video","bytes":81234}],"elapsedMs":3120,"jobId":"20261011-093000-animation-3f2a","data":{"frames":24}}
+```
+
+- On failure, `ok` is `false`, `code` is a stable error code, and `hint` suggests a fix. Human-readable messages go to stderr.
+- Exit codes: `0` success, `1` shot or check failure, `2` invalid arguments, `3` environment problem, `4` renderer internal error, `130` cancelled.
+- Each run writes `events.jsonl` (the same event stream) and `status.json` (the latest snapshot) under `out/jobs/<jobId>/`, allowing other programs to show progress. Rendering also maintains a preview thumbnail, `preview.png`.
+
+See [`docs/protocol.md`](https://github.com/LBEILC/Multiplane/blob/main/docs/protocol.md) for event types, fields, and all error codes.
+
+## User config and job index
+
+The renderer reads config and registers jobs in a user directory: `%USERPROFILE%\.multiplane` on Windows (`%APPDATA%\multiplane` up to 0.2.0; files there are copied over on first use), `~/Library/Application Support/multiplane` on macOS, and `~/.config/multiplane` on Linux. Override it with the environment variable `MULTIPLANE_HOME`.
+
+- `config.json`: user defaults, with optional fields `ffmpeg`, `raster`, `encoder`, `workers`, and `jobsDir`. Priority: command-line options > environment variables > `config.json` > built-in defaults. Rendering never writes this file; `multiplane config` and the desktop app do. `doctor` and `config get` report its location and which fields take effect.
+- `jobs.jsonl`: one line appended at the start and end of each job, allowing other programs to discover jobs across projects. The job directory's `status.json` is the authority for job status. Set `MULTIPLANE_NO_INDEX=1` to disable registration.
+
+Read or write failures in this directory do not affect rendering; they only produce a warning. See section 8 of [`docs/protocol.md`](https://github.com/LBEILC/Multiplane/blob/main/docs/protocol.md) for the format.
+
+## JS API
+
+```js
+import { inspectShot, lintShot, renderShot, stillsShot, verifyShot } from 'multiplane';
+
+const result = await renderShot('examples/animation.html', {
+  workers: 2,
+  out: 'out/demo.mp4',
+  onEvent: event => { if (event.type === 'progress') console.error(event.done, event.total); },
+});
+```
+
+The return value has the same structure as the `result` event, without `schema`, `type` and `ts`. Failures throw a `MultiplaneError` with a `code`.
+
+## Transparent video
+
+Render a shot with a transparent background to lay it over other footage:
+
+```sh
+npx multiplane render examples/alpha.html --format webm --alpha
+npx multiplane render examples/alpha.html --format mov --alpha
+npx multiplane stills examples/alpha.html --alpha --at 0,1
+```
+
+The page background becomes transparent; anything the shot paints itself, including a background colour on `#stage`, stays opaque, so leave `#stage` without a background for a fully transparent layer. A shot can make transparency its default with `post: { alpha: true }`.
+
+- `webm` uses VP9 with alpha. Many players ignore VP9 alpha; to check it with FFmpeg, decode with `-c:v libvpx-vp9`, since the default VP9 decoder drops alpha.
+- `mov` uses ProRes 4444, which most video editors read with alpha.
+- Motion blur and scaling are computed on premultiplied colour, so moving edges do not pick up dark or coloured fringes. Before publishing, the renderer decodes the first and middle frames and checks that alpha survived encoding (at most 2/255 off per pixel).
+- Your FFmpeg build needs `libvpx-vp9` for WebM and `prores_ks` for MOV; `doctor` reports both.
+
+## Quality and motion blur
+
+Motion blur averages several captures taken during the shutter time of each frame. With too few samples, fast-moving things break into separate copies; with many samples everywhere, rendering is slow. Multiplane picks the number of samples for each frame from how far things move locally:
+
+- The shot decides **whether** there is motion blur: `post.motionBlur` above 1 turns it on and is the starting number of samples. The shot also sets `shutter` and grain.
+- `--quality` decides **how good** it is: frames are captured at the starting count, the image is compared block by block between adjacent samples, and wherever something moved more than about 2 pixels (`standard`) or 1 pixel (`high`), the count doubles, up to 64 or 256. Static frames use 1 sample and slow frames keep the starting count, so only fast frames take longer.
+- The default `standard` is enough for iterating and for final videos. `high` takes several times longer on real shots for a gain you only see when zooming in; use it for stills that will be viewed up close or for extremely fast, thin motion. Use `--draft` to check composition.
+- For full control, `--max-motion-blur` changes the limit, and setting it equal to `--motion-blur` gives a fixed count. A shot with `blurAt(t)` uses its own counts and is never raised.
+- `blurSamples` in the result lists how many samples frames actually used.
+
+## Parallel workers
+
+`render` and `verify` split frames across several browser processes (`--workers`). More processes are not always faster: with GPU rasterization they all share one graphics card, and too many slow things down.
+
+- **Measure once on your machine**: `multiplane benchmark` (about 2–3 minutes) renders an ordinary web page, a Canvas shot and a 3D shot with 1, 2, 4, 6, 8, 12, 16 and 24 processes, and keeps, for each kind, the smallest count within 95% of the fastest. Renders then use that count for the kind of shot whenever `--workers` and the config leave it unset.
+- If memory runs out during the measurement, it stops at the largest count that fits and recommends from the counts measured; `doctor` notes the memory limit.
+- Without a measurement, the count is estimated from CPU cores, free memory and output size, at most 12.
+- After a change of computer, graphics card, browser or Multiplane version, `doctor` reports the measurement as outdated; run it again. The result is stored as `benchmark.json` in the user directory.
+- `resources.workersSource` in the result says where the count came from: `option` (command line), `config`, `benchmark` or `estimate`.
+- The worker count changes speed only, never pixels: a shot renders identically with any number of processes.
+
+## Stills
+
+`stills` is not only for checking frames. Each PNG goes through the same post-processing as the same frame of a video, so it can be the final deliverable: a cover, a poster, an illustration, an image for social media.
+
+```sh
+# One still each at 0, 1.5 and 3 seconds
+npx multiplane stills shot.html --at 0,1.5,3 --out out/stills
+
+# A cover: 2x supersampling (a 1920×1080 shot becomes 3840×2160), with motion blur
+npx multiplane stills shot.html --at 2.4 --scale 2 --motion-blur 16 --out out/cover
+
+# A PNG with a transparent background, for laying over other footage
+npx multiplane stills shot.html --at 1 --alpha --out out/overlay
+
+# One still every 0.5 seconds, to skim through the whole shot
+npx multiplane stills shot.html --every 0.5
+```
+
+- Files are named `t-<seconds>.png` (for example `t-2.40.png`), next to a contact sheet of all of them, `_sheet.png`.
+- `--quality`, `--scale`, `--motion-blur`, `--max-motion-blur`, `--shutter`, `--grain` and `--alpha` work as they do for `render`, and so does depth of field in the 3D layer. Defaults the shot declares in `post` apply too.
+- For visible motion blur in a still, pick a time during motion; at static times the sample count drops to 1 automatically and the image is as sharp as without blur.
+- Add `--quality high` for stills that will be viewed up close; `--draft` is for checking composition only.
+
+## 3D layer
+
+```sh
+npm install three@0.180.0
+```
+
+`multiplane/three` adds a transparent WebGL canvas to the stage, providing image cards, surface annotations, and accumulated depth of field. It can be layered with ordinary HTML elements. Shots that do not use 3D do not load it. See [`examples/three-cards.html`](examples/three-cards.html) for an example and the skill's "3D layer" section for usage.
+
+## Desktop app
+
+`app/` contains the companion Multiplane desktop app (Electron), intended for people rather than agents:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/LBEILC/Multiplane/main/docs/images/app-jobs-en-dark.png">
+  <img src="https://raw.githubusercontent.com/LBEILC/Multiplane/main/docs/images/app-jobs-en-light.png" width="800" alt="The Jobs page of the Multiplane desktop app: a running job, a queued job and a live preview frame">
+</picture>
+
+
+- **Jobs**: list render, stills, and check jobs across projects, show progress and preview frames in real time, view finished videos, contact sheets, and diff images from failed checks, and stop running jobs.
+- **Environment**: check whether the browser, GPU rasterization, FFmpeg, and other requirements are ready. Install and update the Multiplane skill for Claude Code (`~/.claude/skills/`) and Codex (`~/.agents/skills/`), without directly overwriting user modifications.
+- **Settings**: write the user config `config.json` described above.
+- **Hosted renders** (off by default): when turned on in Settings, renders started by an agent are run by the app instead of the agent's session, so they keep going when the session ends. One hosted render runs at a time and the rest wait in a queue. The agent's command and output stay the same, and `multiplane wait <job>` picks a job up again after a session restarts. With hosting on, closing the window keeps the app in the system tray. See section 11 of the protocol.
+- **Updates**: the app checks GitHub for a new release at startup and once a day (can be turned off). On Windows it downloads and installs the update in the app; on macOS and Linux it links to the download page.
+- The interface is in English and Simplified Chinese. It follows the system language and can be switched in Settings.
+
+It communicates with the renderer only through the files and commands in [`docs/protocol.md`](https://github.com/LBEILC/Multiplane/blob/main/docs/protocol.md). It is not required for rendering: agents can render from the command line without it.
+
+Download an installer from the [Releases page](https://github.com/LBEILC/Multiplane/releases). The installers bundle a renderer of the same version, so the app works without a separate Node.js install. That renderer is also available as a command: `multiplane.cmd` in the install directory on Windows, `Multiplane.app/Contents/Resources/bin/multiplane` on macOS, and `Multiplane-<version>-x86_64.AppImage --multiplane-cli` on Linux. The Environment page shows the exact path when `multiplane` is not on PATH. FFmpeg is not bundled (see above), and Chromium is downloaded on first use from the Environment page.
+
+| System | Package | First launch (the packages are not code-signed) |
+|---|---|---|
+| Windows | NSIS installer (`.exe`) | SmartScreen shows a warning: choose "More info", then "Run anyway". |
+| macOS | `.dmg`, one for Apple silicon and one for Intel | Gatekeeper blocks the first launch: right-click the app and choose "Open", or allow it under System Settings → Privacy & Security. |
+| Linux | AppImage | Make it executable (`chmod +x`), then run it. It needs FUSE. Without FUSE, extract it once with `--appimage-extract` and run `squashfs-root/AppRun` from then on (do not open two copies with `--appimage-extract-and-run`: the one that exits deletes the shared temporary directory and breaks the other). On systems where unprivileged user namespaces are unavailable, the AppImage launcher starts the app with the Chromium sandbox turned off. |
+
+To build a package for the system you are on, or to run the app during development:
+
+```sh
+npm --prefix app install
+npm --prefix app run dist
+npm --prefix app start
+```
+
+`dist` writes the package to `app/release/`. `npm --prefix app start` uses separate development directories for the renderer config, job index and app data; add `-- --use-user-home` to use your real ones.
+
+## Examples
+
+| File | Content |
+|---|---|
+| [`examples/animation.html`](examples/animation.html) | 2D geometric animation with one hard cut in the middle, demonstrating motion blur that respects cuts |
+| [`examples/typography.html`](examples/typography.html) | Typography with a local font (Roboto, OFL) |
+| [`examples/three-cards.html`](examples/three-cards.html) | 3D cards and accumulated depth of field |
+
+## Determinism and limitations
+
+- Pixel equality is guaranteed only on **the same machine, with the same browser version, fonts, and assets**. Different GPUs, drivers, or browser versions may produce small differences.
+- `lint` is a static check. It cannot detect indirect calls (such as `const now = Date.now; now()`) or accumulated state. `verify` is the final check.
+- `verify` uses sampling: by default, it checks frames near 0%, 25%, 50%, and 75% of the duration, plus consecutive frames from the first second. Passing does not mean every time has been checked.
+- Adaptive motion blur estimates the sample count from image changes. It is an approximation.
+- With GPU rasterization (the default), a frame captured after a reload or in another process can differ in a few scattered pixels by a level or two (caused by the graphics card, invisible). `verify` reports it as a `gpu_raster_jitter` warning, not a failure; with `--raster software` it still requires identical pixels.
+- Frames where nothing changes are reused instead of captured again, with periodic pixel checks; output is identical with `--no-static-reuse`. Shots with video, iframes or running CSS animations are always captured frame by frame. See section 12 of the protocol.
+- The renderer and desktop app pass the same test suite in CI on Windows, macOS (Apple silicon) and Linux (x64, X11 under Xvfb). Windows 10/11 has also been verified on a real machine; macOS and Linux have not yet been tried on real machines, and Wayland has not been tested. CI on Linux has no GPU, so it covers software rasterization there; GPU rasterization on Linux is untested.
+
+## Related projects
+
+Multiplane did not invent the combination of HTML, a time function, a headless browser, and FFmpeg. Related projects include [HyperFrames](https://github.com/heygen-com/hyperframes), [Remotion](https://www.remotion.dev/), [Revideo](https://github.com/redotvideo/revideo), and [Motion Canvas](https://motioncanvas.io/), each with its own focus. Multiplane focuses on shots written as ordinary web pages without a framework dependency, verifiable determinism, motion blur that respects hard cuts, and accumulated depth of field in the 3D layer.
+
+## License
+
+[Apache-2.0](LICENSE). See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for third-party component and example font licenses. FFmpeg is not distributed with this package; its license depends on the build you use.