addZoom
Add a zoom-in over a span of the edited timeline, with configurable focus, magnification, and cursor visibility for highlighting key moments.
Instructions
Add a zoom-in over a span of the edited timeline (virtual seconds). depth is an ORDINAL 1–6, not a factor: it selects a magnification from a fixed table (1=1.25×, 2=1.50×, 3=1.80×, 4=2.20×, 5=3.50×, 6=5.00×), so the default depth 3 renders at 1.80×. The result reports renderedScale — quote that, never the depth, when telling the user how strong the zoom is. focus is the zoom centre in 0–1 fractions of the frame (default centre). When the recording's pointer telemetry can be read for the footage under the span, the result also carries cursorAnchor: focus echoes the value this call used (including the default, if you left it out), cursor is where the pointer ACTUALLY was over the span the zoom landed on — the median of the recorded samples, spread being how far the farthest one strays from it — and offset is the distance between the two, in frame fractions. It is a measurement, not a correction: nothing is moved and no call is refused over it, and a zoom framing a slide, a face, or a region the pointer never enters is a legitimate choice. available:false names what it found instead (no-samples, trimmed-out). Its ABSENCE means no telemetry was read for that footage — never that the recording has none; assets[].hasCursorTelemetry and getCursorTrack are what answer that. Use for 'zoom in on …' and the smart-zoom pass. 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 | Yes | ||
| startSec | Yes | ||
| focusMode | No | manual | |
| 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 | none |