@hyperframes/producer 0.4.31 → 0.4.32

package/README.md

@@ -47,22 +47,72 @@ await startServer({ port: 8080 });
 
 `RenderConfig` controls the render pipeline:
 
-| Option       | Default      | Description                                        |
-| ------------ | ------------ | -------------------------------------------------- |
-| `inputPath`  | —            | Path to the HTML composition                       |
-| `outputPath` | —            | Output video file path                             |
-| `width`      | 1920         | Frame width in pixels                              |
-| `height`     | 1080         | Frame height in pixels                             |
-| `fps`        | 30           | Frames per second (24, 30, or 60)                  |
-| `quality`    | `"standard"` | Encoder preset (`"draft"`, `"standard"`, `"high"`) |
+| Option       | Default      | Description                                                                                                                          |
+| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `inputPath`  | —            | Path to the HTML composition                                                                                                         |
+| `outputPath` | —            | Output video file path (or directory, for `format: "png-sequence"`)                                                                  |
+| `width`      | 1920         | Frame width in pixels                                                                                                                |
+| `height`     | 1080         | Frame height in pixels                                                                                                               |
+| `fps`        | 30           | Frames per second (24, 30, or 60)                                                                                                    |
+| `quality`    | `"standard"` | Encoder preset (`"draft"`, `"standard"`, `"high"`)                                                                                   |
+| `format`     | `"mp4"`      | Output container — `"mp4"`, `"webm"`, `"mov"`, or `"png-sequence"`. See [Transparent Video Output](#transparent-video-output) below. |
+
+## Transparent Video Output
+
+The producer can render HTML compositions to formats that carry a **true alpha channel** — not chroma key. The same composition that renders an opaque MP4 renders a layerable overlay when you set `format`.
+
+| `format`          | Codec / pixel format              | Alpha                   | Audio               | Use case                                                                                |
+| ----------------- | --------------------------------- | ----------------------- | ------------------- | --------------------------------------------------------------------------------------- |
+| `"mp4"` (default) | H.264 (yuv420p) or H.265 + HDR10  | No                      | AAC                 | Streaming, social, default deliverable                                                  |
+| `"webm"`          | VP9 + yuva420p                    | **True alpha**          | Opus                | Web playback as overlay (`<video>` over background); supported in Chrome, Edge, Firefox |
+| `"mov"`           | ProRes 4444 + yuva444p10le        | **True alpha + 10-bit** | AAC                 | Editor ingest (Premiere, Final Cut Pro, DaVinci Resolve)                                |
+| `"png-sequence"`  | Numbered RGBA PNGs in a directory | **Lossless alpha**      | Sidecar `audio.aac` | After Effects / Nuke / Fusion, or pipelines that post-process frames before encoding    |
+
+### Example
+
+```typescript
+import { createRenderJob, executeRenderJob } from "@hyperframes/producer";
+
+const job = createRenderJob({
+  inputPath: "./my-composition.html",
+  outputPath: "./output.webm", // or a directory for "png-sequence"
+  width: 1080,
+  height: 1920,
+  fps: 30,
+  format: "webm", // "mp4" | "webm" | "mov" | "png-sequence"
+});
+
+await executeRenderJob(job);
+```
+
+### What "transparent background" means here
+
+The producer captures Chrome screenshots with the page background forced transparent (`html, body, [data-composition-id] { background: transparent !important }`) and the CDP default background override set to RGBA 0,0,0,0. The captured PNGs carry a real alpha channel and that channel is preserved end-to-end:
+
+- VP9 (`webm`) is encoded with `-pix_fmt yuva420p`, `-auto-alt-ref 0`, and `alpha_mode=1` metadata.
+- ProRes 4444 (`mov`) is encoded with `-pix_fmt yuva444p10le`.
+- PNG sequences are written without re-encoding (zero-padded `frame_NNNNNN.png`).
+
+This is not chroma keying. There is no green/blue background to remove and no "key" tolerance to tune — pixels that were transparent in the browser are transparent in the output.
+
+### Caveats
+
+- **Linux + alpha forces screenshot capture.** Chrome's BeginFrame compositor (the default deterministic capture path on Linux headless-shell) does not preserve alpha; the orchestrator falls back to `Page.captureScreenshot`, which is slower per frame. macOS and Windows already use screenshot mode by default, so they are unaffected.
+- **HDR + alpha is not supported.** Setting `hdr: true` together with an alpha-capable format logs a warning and falls back to SDR. Use `format: "mp4"` for HDR10 output.
+- **`png-sequence` does not produce a single muxed file.** When the composition contains audio elements, an `audio.aac` sidecar is written alongside the PNGs in `outputPath`.
+- **Safari + WebM alpha is incomplete.** For broad browser playback of an alpha video, ship `format: "mov"` to your editor and re-encode for the codec your distribution target supports.
+
+### Authoring transparent compositions
+
+Don't paint a fullscreen background in your HTML. The default body background is overridden to transparent automatically — any `body { background: ... }`, `#root { background: ... }`, or `[data-composition-id] { background: ... }` rule is force-overridden during alpha rendering. Backgrounds on inner elements (cards, scenes, components) are kept.
 
 ## How it works
 
 1. **Serve** — spins up a local file server for the HTML composition
-2. **Capture** — opens the page in headless Chrome, seeks frame-by-frame via `HeadlessExperimental.beginFrame`, captures screenshots
-3. **Encode** — pipes frames through FFmpeg (with GPU encoder detection and chunked concat)
-4. **Mix** — extracts `<audio>` elements and mixes them into the final video
-5. **Finalize** — applies faststart for streaming-friendly MP4
+2. **Capture** — opens the page in headless Chrome, seeks frame-by-frame via `HeadlessExperimental.beginFrame` (or `Page.captureScreenshot` for transparent / non-Linux renders), captures screenshots
+3. **Encode** — pipes frames through FFmpeg (with GPU encoder detection and chunked concat). Skipped for `format: "png-sequence"`.
+4. **Mix** — extracts `<audio>` elements and mixes them into the final video. For `png-sequence`, audio is written as an `audio.aac` sidecar.
+5. **Finalize** — applies faststart for streaming-friendly MP4 (no-op for WebM, MOV, and `png-sequence`)
 
 ## Documentation
 

package/dist/hyperframe.manifest.json

@@ -1,7 +1,7 @@
 {
   "version": "0.1.0",
   "buildId": "dev",
-  "sha256": "02ce520fe0364b7b393d65fa561bdeec3e5576646a4d01d97f8fad0f94433294",
+  "sha256": "088a29111ad766eb7230320826bda314a8cc8b87a7e667cac1ba4f479112a473",
   "artifacts": {
     "iife": "hyperframe.runtime.iife.js",
     "esm": "hyperframe.runtime.mjs"