How to Configure 4K and High‑Resolution Rendering in Hyperframes

Hyperframes achieves 4K output by supersampling compositions via Chrome's device scale factor (DPR), using integer‑based scaling to reach target resolutions while preserving the original layout and aspect ratio.

Configuring 4K and high‑resolution rendering in Hyperframes requires mapping resolution presets to Chrome's device pixel ratio for quality upsampling. The heygen-com/hyperframes repository implements this through a type‑safe pipeline that validates compositional constraints before launching the render job.

The Resolution Processing Pipeline

Hyperframes handles resolution requests through a strict validation chain that converts CLI flags into Chrome launch parameters.

CLI Flag Normalization

When you pass --resolution, the CLI parses and normalizes the value to a CanvasResolution preset. In packages/cli/src/commands/render.ts (lines 58‑64), the input is processed through normalizeResolutionFlag:

const resolution = normalizeResolutionFlag(flags.resolution);

Valid presets include landscape-4k, portrait-4k, landscape, and portrait, defined in packages/core/src/core.types.ts.

Render Job Propagation

The normalized resolution flows into the render job configuration via createRenderJob (lines 268‑277 in packages/cli/src/commands/render.ts). The producer receives this as outputResolution in packages/producer/src/services/renderOrchestrator.ts (lines 278‑282):

outputResolution?: CanvasResolution;

Device Scale Factor Implementation

Rather than resizing the composition DOM, Hyperframes increases Chrome's device scale factor to capture supersampled screenshots at the target pixel density.

DPR Calculation Logic

The resolveDeviceScaleFactor function in packages/producer/src/services/render/shared.ts (lines 71‑126) translates presets into integer DPR values. This function validates that:

• The target aspect ratio matches the composition dimensions
• The scale factor is a whole integer (e.g., 2× for 4K)
• The requested resolution exceeds the native size (up‑sampling only)

const dpr = resolveDeviceScaleFactor(compositionDimensions, outputResolution);

Chrome Launch Integration

The calculated DPR is passed to the headless Chrome process via --device-scale-factor (lines 60‑66 in packages/producer/src/services/render/shared.ts):

launchOptions.args.push(`--device-scale-factor=${dpr}`);

This captures screenshots at the target resolution (e.g., 3840×2160) while the underlying composition layout remains unchanged.

Resolution Constraints and Validation

The system enforces strict guards to prevent invalid render configurations.

• Aspect‑Ratio Matching — A landscape-4k preset (3840×2160) requires a 16:9 composition. resolveDeviceScaleFactor throws a validation error if ratios mismatch (lines 106‑112 in packages/producer/src/services/render/shared.ts).

• Integer DPR Only — Fractional device scale factors are rejected to prevent blurry output. The code explicitly validates whole numbers at lines 123‑130 in packages/producer/src/services/render/shared.ts.

• No HDR or Alpha Compositing — HDR modes and alpha channels are incompatible with supersampling. The CLI blocks these combinations early at lines 80‑91 in packages/cli/src/commands/render.ts.

• No Down‑Sampling — Selecting an output resolution smaller than the composition's native size is disallowed. The validation at lines 166‑170 in packages/producer/src/services/render/shared.ts enforces up‑sampling only.

Practical Configuration Examples

Command Line Usage

Render at native 1080p (default behavior):

hyperframes render index.html -o out.mp4

Upsample to 4K using the preset alias:

hyperframes render index.html \
  --resolution 4k \
  -o out-4k.mp4

Programmatic Node.js API

import { createProducer } from "@hyperframes/producer";

const producer = await createProducer();

const job = producer.createRenderJob({
  fps: 30,
  quality: "high",
  format: "mp4",
  outputResolution: "landscape-4k",
});

await producer.executeRenderJob(job, "./my-project", "out-4k.mp4");

Summary

• Supersampling Method: Hyperframes uses Chrome's device-scale-factor (DPR) to capture high‑resolution screenshots without altering CSS dimensions.
• Preset System: Use --resolution with values like landscape-4k, normalized through normalizeResolutionFlag in packages/core/src/core.types.ts.
• Validation Chain: resolveDeviceScaleFactor in packages/producer/src/services/render/shared.ts enforces aspect‑ratio matching, integer DPR, and prevents down‑sampling.
• Compatibility Limits: HDR rendering and alpha channels cannot be combined with high‑resolution presets.
• Docker Support: Resolution flags propagate through packages/cli/src/utils/dockerRunArgs.ts when running in containerized environments.

Frequently Asked Questions

What resolution presets are available in Hyperframes?

Hyperframes supports presets defined in the CanvasResolution type, including landscape, portrait, landscape-4k, and portrait-4k. Aliases like 4k map to landscape-4k through the normalizeResolutionFlag function in packages/core/src/core.types.ts.

Why does my render fail with an aspect ratio error?

The resolveDeviceScaleFactor function validates that your composition's native aspect ratio matches the target preset. For example, landscape-4k (3840×2160) requires a 16:9 source composition. Mismatched ratios trigger validation errors at lines 106‑112 of packages/producer/src/services/render/shared.ts.

Can I render 4K with HDR enabled?

No. HDR compositing runs at the composition's native size only, while 4K rendering requires supersampling via DPR. The CLI explicitly blocks this combination at lines 80‑91 in packages/cli/src/commands/render.ts to prevent incompatible output.

How does Hyperframes technically achieve 4K resolution without resizing the DOM?

Hyperframes passes an integer device scale factor (typically 2× for 4K) to Chrome's --device-scale-factor launch argument. This instructs the browser to render at higher pixel density while keeping the logical CSS dimensions unchanged, resulting in crisp supersampled captures as implemented in packages/producer/src/services/render/shared.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}