The verbs

Declares a scene — the primary narrative macro. Compiles into atomic verb actions: camera movement, layer toggles, caption display, audio narration, media insets, basemap switches, and pauses.

scene_id * string

Scene ID to execute

document * object

The full GeoStoryDocument (needed to resolve references)

Animate camera to target coordinates with zoom, bearing, pitch, and easing.

center * array

[longitude, latitude]

zoom number

Target zoom level

bearing number

Target bearing in degrees

pitch number

Target pitch in degrees

duration number

Animation duration in milliseconds

easing string

Easing function

Instantly set camera position without animation.

center * array

[longitude, latitude]

zoom number

Zoom level

bearing number

Bearing in degrees

pitch number

Pitch in degrees

Fit camera to a bounding box or feature extent. Preferred over fly_to for anything larger than a city — bounds survive aspect-ratio changes, a zoom number does not.

bounds * array

[[west, south], [east, north]]

padding number

Padding as fraction of extent (0–1)

duration number

Animation duration in milliseconds

easing string

Easing function

Place a camera pose at a specific time on the document-absolute timeline. Used within camera tracks for sub-scene animation.

at * number

Time in seconds (document-absolute)

center array

[longitude, latitude]

zoom number

Zoom level

bearing number

Bearing in degrees

pitch number

Pitch in degrees

easing string

Easing to this keyframe

locked boolean

If true, preserved during rescaling

Make a data layer visible, optionally with style overrides.

id * string

Layer ID from the layers registry

style object

Optional style overrides

Hide a data layer.

id * string

Layer ID from the layers registry

Display an annotation (circle, polygon, line, or marker) from the annotations registry.

id * string

Annotation ID from the registry

Animate motion along an annotation's line: particles travelling the path, optionally drawn in progressively. The still line says a route exists; this says which way it runs and how fast.

id * string

Annotation ID from the registry. Its geometry supplies the path.

direction string

forward | reverse | both. Default forward.

speed number

Particle speed in pixels per second at 1080p, scaled to the output size.

reveal number

Seconds spent drawing the line in before it is fully visible.

fade_out number

Seconds spent fading out at the end of the window.

particles number

How many markers travel the path at once.

particle string

arrow | dot | none. Default arrow.

glow boolean

A soft halo around the line.

Hide an annotation.

id * string

Annotation ID to hide

Display a text caption on screen.

text * string

Caption text

position string

Screen position

duration number

Display duration in seconds (omit for indefinite)

style string

Style preset name

Hide the active caption.

Place one audio clip at a time on the timeline. The fundamental audio verb — narrate and music are sugar over this.

id * string

Audio clip ID from the audio registry

src * string

Audio source URL or path

at * number

Start time (document-absolute seconds)

duration * number

Clip duration in seconds

gain_db number

Gain adjustment in dB

duck boolean

Whether to duck under narration

Play a narration audio clip. Sugar over audio.clip with kind=narration semantics.

clip_id * string

Audio clip ID from the audio registry

Set background music. Sugar over audio.clip with ducking enabled by default.

clip_id * string

Audio clip ID from the audio registry

Display an image or video as an inset over the map. The map continues moving underneath.

id * string

Media item ID from the media registry

placement string

Screen placement

Remove a media inset.

id * string

Media item ID to hide

Switch the basemap tile layer.

id * string

Basemap identifier (e.g. 'carto-dark', 'arcgis-satellite', 'osm')

Insert a timed pause. The map holds its current state.

duration * number

Pause duration in seconds

Geocode a place name and write the result into the document's places registry. An AUTHORING verb — never called during playback. Geocoding is an authoring step whose output is committed to the file.

as_written * string

The place name as written in narration

context object

Geographic context for disambiguation (e.g. primary country, scope)

provider string

Geocoding provider to use

Rescale the timeline to measured narration durations. Applies the rescaling rules: unlocked keyframes scale proportionally, locked keyframes are preserved. An AUTHORING verb.

scene_id string

Scene ID to rescale, or omit for all scenes

Render the story to a video file.

format string

Output format

resolution string

Output resolution

fps number

Frames per second

output string

Output file path

Publish the rendered story to a platform.

platform * string

Target platform

title string

Publication title

description string

Publication description

Produce publishing artifacts — thumbnail, description with chapters and attribution, tags — without connecting an account. Separates artifact production from OAuth-gated publishing.

include_thumbnail boolean

Generate a thumbnail image

include_chapters boolean

Generate chapter markers from scene titles

include_attribution boolean

Include full attribution text

include_tags boolean

Generate suggested tags from story content