OpenScreen Zoom Depth Levels and Scale Factors: Complete Developer Guide

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. 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. 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:

// 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, 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:

// 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, videoPlayback/zoomRegionUtils.ts, and 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):

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, 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 consumes this value to manipulate the Pixi.js camera container:

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. This map mirrors the ZOOM_DEPTH_SCALES structure for UI consistency:

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

The 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.
• 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 applies the scale factor to the Pixi.js camera container during playback.
• UI representation: ZOOM_LABELS in 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.

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. 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 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, 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 as ZOOM_LABELS, while the transformation logic implementing the zoom effect is handled in src/components/video-editor/videoPlayback/zoomTransform.ts.

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