@hyperframes/producer 0.8.186 → 0.8.189

package/README.md

@@ -18,18 +18,13 @@ npm install @hyperframes/producer
 import { createRenderJob, executeRenderJob } from "@hyperframes/producer";
 
 const job = createRenderJob({
-  inputPath: "./my-composition.html",
-  outputPath: "./output.mp4",
-  width: 1920,
-  height: 1080,
   fps: 30,
+  quality: "standard",
 });
 
-const result = await executeRenderJob(job, (progress) => {
-  console.log(`${Math.round(progress.percent * 100)}%`);
+await executeRenderJob(job, "./my-project", "./output.mp4", (currentJob) => {
+  console.log(`${Math.round(currentJob.progress)}%`);
 });
-
-console.log(result.outputPath); // ./output.mp4
 ```
 
 ### Run as an HTTP server
@@ -40,24 +35,27 @@ The producer can also run as a render server, accepting render requests over HTT
 import { startServer } from "@hyperframes/producer";
 
 await startServer({ port: 8080 });
-// POST /render with a RenderConfig body
+// POST /render or /render/stream with projectDir, html, or previewUrl and render options
 ```
 
+Both HTTP routes accept optional `pageMotionBlur: "off"` to disable authored page
+motion blur. Omit it to preserve the composition's behavior. Other explicit values
+are rejected before a render starts. This is separate from engine sub-frame
+`motionBlur` sampling.
+
 ### Configuration
 
 `RenderConfig` controls the render pipeline:
 
-| Option              | Default      | Description                                                                                                                                                                          |
-| ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `inputPath`         | —            | Path to the HTML composition                                                                                                                                                         |
-| `outputPath`        | —            | Output video file path (or directory, for `format: "png-sequence"` and `format: "hls"`)                                                                                              |
-| `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"`, `"gif"`, `"png-sequence"`, or `"hls"`. See [Transparent Video Output](#transparent-video-output) and [HLS Output](#hls-output) below. |
-| `hlsSegmentSeconds` | `4`          | HLS target segment length in whole seconds. Ignored for every other format.                                                                                                          |
-| `videoFrameFormat`  | `"auto"`     | Source video frame extraction format — `"auto"`, `"jpg"`, or `"png"`. Use `"png"` for UI recordings, screen captures, and color-sensitive source videos.                             |
+| Option              | Default          | Description                                                                                                                                                                          |
+| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `entryFile`         | `index.html`     | Entry composition inside the project directory. Its authored dimensions set the canvas size.                                                                                         |
+| `fps`               | required         | Frame rate as an integer or exact `{ num, den }` rational.                                                                                                                           |
+| `quality`           | required         | Encoder preset (`"draft"`, `"standard"`, `"high"`).                                                                                                                                  |
+| `pageMotionBlur`    | authored setting | Set `"off"` to disable page motion blur; omit to preserve authored behavior.                                                                                                         |
+| `format`            | `"mp4"`          | Output container — `"mp4"`, `"webm"`, `"mov"`, `"gif"`, `"png-sequence"`, or `"hls"`. See [Transparent Video Output](#transparent-video-output) and [HLS Output](#hls-output) below. |
+| `hlsSegmentSeconds` | `4`              | HLS target segment length in whole seconds. Ignored for every other format.                                                                                                          |
+| `videoFrameFormat`  | `"auto"`         | Source video frame extraction format — `"auto"`, `"jpg"`, or `"png"`. Use `"png"` for UI recordings, screen captures, and color-sensitive source videos.                             |
 
 ## Transparent Video Output
 
@@ -68,7 +66,7 @@ The producer can render HTML compositions to formats that carry a **true alpha c
 | `"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    |
+| `"png-sequence"`  | Numbered RGBA PNGs in a directory | **Lossless alpha**      | Sidecar `audio.m4a` | After Effects / Nuke / Fusion, or pipelines that post-process frames before encoding    |
 | `"hls"`           | H.264 (yuv420p) in MPEG-TS        | No                      | AAC rendition       | VOD streaming — see [HLS Output](#hls-output)                                           |
 
 ### Example
@@ -77,15 +75,12 @@ The producer can render HTML compositions to formats that carry a **true alpha c
 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,
+  quality: "standard",
   format: "webm", // "mp4" | "webm" | "mov" | "png-sequence"
 });
 
-await executeRenderJob(job);
+await executeRenderJob(job, "./my-project", "./output.webm");
 ```
 
 ### What "transparent background" means here
@@ -102,7 +97,7 @@ This is not chroma keying. There is no green/blue background to remove and no "k
 
 - **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`.
+- **`png-sequence` does not produce a single muxed file.** When the composition contains audio elements, an `audio.m4a` 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
@@ -124,11 +119,12 @@ audio_00000.ts
 
 ```typescript
 const job = createRenderJob({
-  inputPath: "./my-composition.html",
-  outputPath: "./renders/stream",
+  fps: 30,
+  quality: "standard",
   format: "hls",
   hlsSegmentSeconds: 4,
 });
+await executeRenderJob(job, "./my-project", "./renders/stream");
 ```
 
 Segments are exactly `hlsSegmentSeconds` long except the last: the encoder's GOP
@@ -181,7 +177,7 @@ The activity functions plus their result types are also re-exported from `@hyper
 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` (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.
+4. **Mix** — extracts `<audio>` elements and mixes them into the final video. For `png-sequence`, audio is written as an `audio.m4a` sidecar.
 5. **Finalize** — applies faststart for streaming-friendly MP4 (no-op for WebM, MOV, and `png-sequence`). For `hls`, stream-copies the encode into playlists and MPEG-TS segments instead.
 
 ### Where each step lives