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

> Learn to configure 4K and high-resolution rendering in Hyperframes. Discover how supersampling and DPR achieve crisp output while preserving layout and aspect ratio.

- Repository: [HeyGen/hyperframes](https://github.com/heygen-com/hyperframes)
- Tags: how-to-guide
- Published: 2026-05-17

---

**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`](https://github.com/heygen-com/hyperframes/blob/main/packages/cli/src/commands/render.ts) (lines 58‑64), the input is processed through `normalizeResolutionFlag`:

```typescript
const resolution = normalizeResolutionFlag(flags.resolution);

```

Valid presets include `landscape-4k`, `portrait-4k`, `landscape`, and `portrait`, defined in [`packages/core/src/core.types.ts`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/packages/cli/src/commands/render.ts)). The producer receives this as `outputResolution` in [`packages/producer/src/services/renderOrchestrator.ts`](https://github.com/heygen-com/hyperframes/blob/main/packages/producer/src/services/renderOrchestrator.ts) (lines 278‑282):

```typescript
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`](https://github.com/heygen-com/hyperframes/blob/main/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)

```typescript
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`](https://github.com/heygen-com/hyperframes/blob/main/packages/producer/src/services/render/shared.ts)):

```typescript
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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/packages/producer/src/services/render/shared.ts) enforces up‑sampling only.

## Practical Configuration Examples

### Command Line Usage

Render at native 1080p (default behavior):

```bash
hyperframes render index.html -o out.mp4

```

Upsample to 4K using the preset alias:

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

```

### Programmatic Node.js API

```typescript
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`](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/core.types.ts).
- **Validation Chain**: `resolveDeviceScaleFactor` in [`packages/producer/src/services/render/shared.ts`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/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`](https://github.com/heygen-com/hyperframes/blob/main/packages/producer/src/services/render/shared.ts).