setZoom
Move, resize, or restyle an existing zoom by ID in OpenScreen, changing only supplied timing, depth, focus, cursor, or rotation fields.
Instructions
Move, resize, or restyle an existing zoom by id (virtual-timeline seconds). Only the fields you pass are changed. depth selects from the same table (1=1.25×, 2=1.50×, 3=1.80×, 4=2.20×, 5=3.50×, 6=5.00×); if the zoom carries a customScale (getCurrentDocument shows it as depthIsOverridden), that custom value is what renders, and passing depth clears it so the depth takes effect — the result says so. The result reports the resulting renderedScale, and — when the footage under the span has readable pointer telemetry — the same cursorAnchor addZoom reports, measured against the zoom's EFFECTIVE focus, so a call that moved only the span still learns what its unchanged focus is now looking at. The zoom pane's other settings: focusMode "manual" holds focus, "auto" follows the recorded pointer instead (getCurrentDocument reports the effective mode, auto everywhere while autoFocusAll is on); hideCursor hides the pointer while the zoom is on screen; customScale is a free level in place of depth, a factor from 1 to 5 rounded to the hundredth. A level the depth table has is stored as that depth, and one deeper than the clip takes before its recording blurs is refused with the limit, as the editor refuses it. Pass depth or customScale, not both. rotationPreset is the zoom's 3D camera: left or right turns the screen in 3D to that side, orbit moves the camera around the screen while the zoom holds, none (the default) keeps it flat. It is a strong effect: keep it for a reveal or a key moment, not every zoom. getCurrentDocument reports it as rotationPreset, absent when flat. A zoom HOLDS over its span: it animates in during the window just before startSec and out during the window just after endSec. Each move lasts 0.6 s + 0.55 s × ln(renderedScale) of SCREEN time (0.72 s at 1.25×, 0.82 s at 1.50×, 0.92 s at 1.80×, 1.03 s at 2.20×, 1.29 s at 3.50×, 1.49 s at 5.00×), so a speed region scales the timeline it covers by its speed: longer above 1×, shorter below. getCurrentDocument gives each zoom's zoomInFromSec and zoomOutUntilSec, in virtual seconds like the zoom. A trim inside either window cuts that move and the export jumps at the cut: leave the windows untrimmed. Two zooms at most 1.5 s apart on screen, on the same clip with no trim between them, are chained: the camera pans from one to the next over 1 s of screen time from the first one's end (panUntilSec), with no zoom-out or zoom-in between them. When the result cuts a zoom's move in or out, it carries cutTransitions: which zoom, which side, cutSec, the timeline seconds of the move lost, and by: trim, or junction when the move runs past its clip's edge into the next clip. It is a warning, nothing is refused: move the cut or the zoom unless a hard cut is what you want.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| focus | No | ||
| endSec | No | ||
| zoomId | Yes | ||
| startSec | No | ||
| focusMode | No | ||
| projectId | No | The project to act on, from listProjects. Omit it only for the project open in the OpenScreen editor, which works only while the app runs. | |
| hideCursor | No | ||
| customScale | No | A free zoom level, as a factor (1–5, e.g. 2 for 2×), in place of depth. Refused past the clip's own limit, the deepest its recording takes before it blurs; the refusal names it. | |
| rotationPreset | No |