# OpenScreen Zoom Depth Levels and Scale Factors: Complete Developer Guide

> Explore OpenScreen's six zoom depth levels and scale factors from 1.25x to 5.0x. This developer guide details available zoom options for your OpenScreen projects.

- Repository: [Sid/openscreen](https://github.com/siddharthvaddem/openscreen)
- Tags: developer-guide
- Published: 2026-04-03

---

**OpenScreen provides six discrete zoom depth levels (1 through 6) that map to scale factors ranging from 1.25× to 5.0×, defaulting to depth 3 (1.8×) for all newly created zoom regions.**

OpenScreen is an open-source video editor that enables cinematic zoom effects on video segments through a type-safe magnification system. Understanding the available **OpenScreen zoom depth levels** is essential for configuring precise camera movements and magnification effects. The zoom system is implemented in TypeScript and leverages Pixi.js for rendering, with strict type definitions ensuring only valid depth values are accepted throughout the application pipeline.

## OpenScreen Zoom Depth Levels and Scale Factors Overview

The zoom system is built around six discrete integer depths defined in [`src/components/video-editor/types.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/types.ts). Each depth maps to a specific magnification factor used to scale the video canvas during playback.

| Zoom Depth | Scale Factor | UI Label |
|------------|--------------|----------|
| 1 | 1.25× | "1.25×" |
| 2 | 1.5× | "1.5×" |
| 3 | 1.8× | "1.8×" |
| 4 | 2.2× | "2.2×" |
| 5 | 3.5× | "3.5×" |
| 6 | 5.0× | "5×" |

When users create a new zoom region via the timeline or settings panel, the system assigns **depth 3 (1.8×)** by default via the `DEFAULT_ZOOM_DEPTH` constant. This default provides moderate magnification suitable for most focus-pulling effects while maintaining video clarity.

## Type System Architecture in types.ts

The core definitions governing zoom behavior reside in [`src/components/video-editor/types.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/types.ts). This file establishes the contract between the UI, state management, and rendering engine.

### The ZoomDepth Union Type

The `ZoomDepth` type restricts zoom values to the six valid integers, preventing invalid depths from being assigned to regions:

```typescript
// src/components/video-editor/types.ts
type ZoomDepth = 1 | 2 | 3 | 4 | 5 | 6;

```

This union type is used across the editor in [`VideoEditor.tsx`](https://github.com/siddharthvaddem/openscreen/blob/main/VideoEditor.tsx), `VideoPlayback` components, and the `SettingsPanel` to ensure type safety.

### The ZOOM_DEPTH_SCALES Mapping

The actual magnification values are stored in the `ZOOM_DEPTH_SCALES` record, which maps each `ZoomDepth` to its corresponding numeric scale factor:

```typescript
// src/components/video-editor/types.ts
const ZOOM_DEPTH_SCALES: Record<ZoomDepth, number> = {
  1: 1.25,
  2: 1.5,
  3: 1.8,
  4: 2.2,
  5: 3.5,
  6: 5.0
};

```

The rendering pipeline references this map to calculate camera transforms. Files such as [`videoPlayback/zoomTransform.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/videoPlayback/zoomTransform.ts), [`videoPlayback/zoomRegionUtils.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/videoPlayback/zoomRegionUtils.ts), and [`videoPlayback/focusUtils.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/videoPlayback/focusUtils.ts) all import this mapping to compute positioning, transitions, and overlay alignment relative to the active zoom scale.

## Creating Zoom Regions Programmatically

To create a zoom region with a specific depth, use the `ZoomRegion` interface and specify a depth value from the `ZoomDepth` union. The following example demonstrates adding a region with depth 5 (3.5× magnification):

```tsx
import { DEFAULT_ZOOM_DEPTH } from "@/components/video-editor/types";

function addZoomRegion(startMs: number, endMs: number, depth: 1 | 2 | 3 | 4 | 5 | 6) {
  const newRegion = {
    id: `zoom-${Date.now()}`,
    startMs,
    endMs,
    depth,               // ← choose 1‑6
    focus: { cx: 0.5, cy: 0.5 }, // centered by default
  };
  // pushState is the editor’s internal reducer; see VideoEditor.tsx
  pushState(prev => ({
    ...prev,
    zoomRegions: [...prev.zoomRegions, newRegion],
  }));
}

// Example: add a deep zoom (depth 5 → 3.5×)
addZoomRegion(3000, 5000, 5);

```

This logic reflects the region creation implementation found in [`src/components/video-editor/VideoEditor.tsx`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/VideoEditor.tsx), where the state reducer manages the `zoomRegions` array.

## Applying Zoom Transforms in the Playback Pipeline

During video playback, the active zoom region's depth is translated into a scale factor through the `ZOOM_DEPTH_SCALES` map. The `applyZoomTransform` function in [`src/components/video-editor/videoPlayback/zoomTransform.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/videoPlayback/zoomTransform.ts) consumes this value to manipulate the Pixi.js camera container:

```typescript
import { ZOOM_DEPTH_SCALES } from "@/components/video-editor/types";

function getZoomScale(depth: ZoomDepth): number {
  return ZOOM_DEPTH_SCALES[depth];
}

// Inside the render loop (VideoPlayback)
const scale = getZoomScale(activeZoomRegion.depth);
// applyZoomTransform will use this scale to position the camera
applyZoomTransform({
  cameraContainer,
  blurFilter,
  motionBlurFilter,
  stageSize,
  baseMask,
  zoomScale: scale,
  focusX: activeZoomRegion.focus.cx,
  focusY: activeZoomRegion.focus.cy,
  isPlaying,
});

```

The `zoomScale` parameter directly determines the magnification applied to the video stage, while the focus coordinates (cx, cy) dictate the center point of the zoom within the normalized 0–1 coordinate space.

## Rendering Zoom Labels in the Timeline

The timeline interface displays human-readable magnification labels using the `ZOOM_LABELS` mapping defined in [`src/components/video-editor/timeline/Item.tsx`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/timeline/Item.tsx). This map mirrors the `ZOOM_DEPTH_SCALES` structure for UI consistency:

```tsx
// Inside src/components/video-editor/timeline/Item.tsx
<span className="text-[11px] font-semibold">
  {ZOOM_LABELS[zoomDepth] || `${zoomDepth}×`}
</span>

```

The [`SettingsPanel.tsx`](https://github.com/siddharthvaddem/openscreen/blob/main/SettingsPanel.tsx) component also utilizes these labels to populate selection dropdowns, allowing users to choose from the six available magnification levels when configuring an existing zoom region.

## Summary

- **Six discrete levels**: OpenScreen defines zoom depths 1–6, mapping to scale factors of 1.25×, 1.5×, 1.8×, 2.2×, 3.5×, and 5.0× respectively.
- **Default configuration**: New zoom regions initialize at depth 3 (1.8×) via `DEFAULT_ZOOM_DEPTH` in [`types.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/types.ts).
- **Type safety**: The `ZoomDepth` union type and `ZOOM_DEPTH_SCALES` record enforce valid values throughout the application.
- **Render pipeline**: The `applyZoomTransform` function in [`zoomTransform.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/zoomTransform.ts) applies the scale factor to the Pixi.js camera container during playback.
- **UI representation**: `ZOOM_LABELS` in [`timeline/Item.tsx`](https://github.com/siddharthvaddem/openscreen/blob/main/timeline/Item.tsx) provides human-readable formatting for the timeline and settings interfaces.

## Frequently Asked Questions

### What are the available zoom depth levels in OpenScreen?

OpenScreen provides six zoom depth levels ranging from 1 to 6. Depth 1 provides 1.25× magnification, depth 2 provides 1.5×, depth 3 provides 1.8×, depth 4 provides 2.2×, depth 5 provides 3.5×, and depth 6 provides 5.0× magnification. These values are defined in the `ZOOM_DEPTH_SCALES` record located in [`src/components/video-editor/types.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/types.ts).

### What is the default zoom depth when creating a new region?

The default zoom depth is **3**, which corresponds to a **1.8×** scale factor. This is defined by the `DEFAULT_ZOOM_DEPTH` constant in [`src/components/video-editor/types.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/types.ts). When users create a zoom region through the timeline or settings panel, the editor automatically assigns this default depth unless explicitly changed.

### How does OpenScreen calculate the zoom scale factor during playback?

The application calculates the scale factor by indexing into the `ZOOM_DEPTH_SCALES` mapping using the active region's depth as the key. The `applyZoomTransform` function in [`src/components/video-editor/videoPlayback/zoomTransform.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/videoPlayback/zoomTransform.ts) retrieves the numeric value and applies it to the Pixi.js camera container, effectively magnifying the video canvas by the corresponding factor.

### Where are the zoom depth definitions located in the source code?

The primary definitions reside in [`src/components/video-editor/types.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/types.ts), which exports the `ZoomDepth` type, `ZOOM_DEPTH_SCALES` mapping, and `DEFAULT_ZOOM_DEPTH` constant. The UI labels for these depths are maintained in [`src/components/video-editor/timeline/Item.tsx`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/timeline/Item.tsx) as `ZOOM_LABELS`, while the transformation logic implementing the zoom effect is handled in [`src/components/video-editor/videoPlayback/zoomTransform.ts`](https://github.com/siddharthvaddem/openscreen/blob/main/src/components/video-editor/videoPlayback/zoomTransform.ts).