pup-recorder 0.4.7 → 0.4.9

package/README.md

@@ -1,55 +1,74 @@
-# PUP-RECORDER(1)
+![pup-recorder](assets/logo.png)
 
-## NAME
+Render a web page to video. Loads a URL, local file, or `data:` document in headless Electron and captures it to `.mp4` / `.webm`, with hardware HEVC-alpha encoding, optional audio, and a deterministic mode for reproducible output.
 
-pup-recorder — record web pages as video
+## Features
 
-## SYNOPSIS
+- Headless offscreen rendering — no display server.
+- Two modes: real-time recording, or deterministic frame-by-frame (same input, same bytes).
+- Hardware HEVC-alpha encode via NVENC or VideoToolbox, software fallback.
+- Alpha preserved end to end.
+- Optional audio, AAC.
 
-    pup source [-W width] [-H height] [-f fps] [-t duration] [-o file] [-a] [-d]
-               [--disable-gpu] [--disable-hw-codec] [--window-tolerant]
-               [--use-inner-proxy]
+## Install
 
-## OPTIONS
-
-    source                    file://, http(s)://, or data: URI
-    -W, --width <number>      default: 1920
-    -H, --height <number>     default: 1080
-    -f, --fps <number>        default: 30
-    -t, --duration <number>   default: 5 (seconds)
-    -o, --out-file <path>     default: output.mp4
-    -a, --with-audio
-    -d, --deterministic       frame-by-frame via CDP virtual time
-    --use-inner-proxy         Bilibili inner proxy
-    --disable-gpu             force SwiftShader software rendering
-    --disable-hw-codec        software x265 instead of NVENC/VideoToolbox
-    --window-tolerant         accept dom-ready when did-stop-loading hangs
-
-## ENVIRONMENT
+```sh
+bun add pup-recorder
+```
 
-    PUP_LOG_LEVEL          0=error 1=warn 2=info 3=debug (default: 2)
-    PUP_USE_INNER_PROXY    1=on
-    PUP_DISABLE_GPU        1=on
-    PUP_DISABLE_HW_CODEC   1=on
-    PUP_DETERMINISTIC      1=on
-    PUP_WINDOW_TOLERANT    1=on
+Bundles Electron and a prebuilt `node-av` (FFmpeg) — no system FFmpeg or Chrome.
 
-CLI flags override environment variables.
+Runs on macOS, Linux, and Windows (x64 + arm64). Hardware encode uses VideoToolbox on macOS and NVENC on Linux/Windows with an NVIDIA GPU; a software encoder covers everything else.
 
 ## API
 
 ```ts
 import { pup } from "pup-recorder";
 
-const result = await pup(source, {
-  width, height, fps, duration, outFile,
-  withAudio, deterministic, useInnerProxy,
-  disableGpu, disableHwCodec, windowTolerant,
-  signal, onProgress,
+const result = await pup("https://example.com", {
+  fps: 30,
+  duration: 10,
+  deterministic: true,
+  outFiles: ["out/demo.mp4", "out/demo.webm"],
+  onProgress: (pct) => console.log(pct),
+  signal: AbortSignal.timeout(120_000),
 });
-// => { written, jank, outFile, options }
+
+result.outFiles;    // video paths
+result.written;     // frames encoded
+result.blank;       // blank-frame ratio
+result.screenshots; // PNG paths
 ```
 
-## SEE ALSO
+All options default; pass only overrides. `signal` cancels a run; `onProgress` streams 0–100.
+
+## CLI
+
+```sh
+pup https://example.com -o out/demo.mp4            # real-time
+pup https://example.com -t 10 -d -o out/demo.mp4   # deterministic, 10s
+```
+
+`<source>` is an `http(s)://`, `file://`, `data:` URI, or path. Outputs are comma-separated; the extension picks the encoder (`.mp4` → HEVC+AAC, `.webm` → VP9). Key flags: `-W`/`-H` size, `-f` fps, `-t` duration, `-d` deterministic, `-a` audio, `-S` screenshot marks. Full list: `pup --help`.
+
+## How it works
+
+pup-recorder runs as two processes: a parent owning the CLI/API and lifecycle, and an Electron subprocess doing offscreen render + encode, over IPC.
+
+Electron loads the page into a headless offscreen `BrowserWindow`; each frame arrives as a BGRA bitmap and feeds the encoder: BGRA → HEVC-with-alpha (NVENC / VideoToolbox, or software x265) → `.mp4`; VP9 for `.webm`.
+
+The two modes differ in *when* a frame is captured.
+
+**Real-time (default).** The page runs on the real clock; `paint` events are muxed at wall-clock speed. For content whose timing you don't control (`<video>`, live WebGL). Drops frames if the machine can't keep up.
+
+**Deterministic (`-d`).** Fakes time and advances it one frame at a time. Hooks `requestAnimationFrame`, `setTimeout`/`setInterval`, `Date`, `performance.now`, `getAnimations`, and steps the compositor clock by `1/fps` (`advanceVirtualTime`). Frame N is computed at exactly `N/fps` regardless of CPU time — reproducible, no dropped frames, cache-keyable by input hash.
+
+**Frame sync.** A 1-pixel row at the bottom of each frame encodes the intended timestamp; the capturer decodes it off the bitmap and rejects any frame that doesn't match, defeating compositor coalescing and off-by-one capture.
+
+## Production
+
+pup-recorder is the core rendering engine of [花生AI](https://www.huasheng.cn/), driving ~1.7M video exports a day at five-nines (99.999%) reliability. Its direction is driven solely by production needs [at bilibili](https://jobs.bilibili.com/), reasoned from first principles — not by backward compatibility. Expect breaking changes; pin a version.
+
+## License
 
-pup-server(1), pup-recorder-mcp(1), pup(7)
+MIT © 2026 Autokaka

package/build.ts

@@ -42,7 +42,8 @@ await build({
   entry: [
     "src/app.ts", //
     "src/runtime/audio_preload.ts",
-    "src/runtime/iframe_preload.ts",
+    "src/runtime/render_preload.ts",
+    "src/runtime/shoot_preload.ts",
   ],
   format: "cjs",
   outDir: "dist",