The Nightmap

Planetarium Tour Manual

The reference for the Tour DSL: the small plain-text language that directs a Planetarium show. This manual defines the language and documents every command. For using the Planetarium itself, see the Planetarium guide.

Applies to The Nightmap Planetarium Revision 19 October 2026 Audience anyone writing or reading a script

1Introduction

1.1 Purpose

The live tour decides for itself, moment to moment. The Tour DSL (domain-specific language) is the opposite: a short, plain-text script that says exactly what happens and when, so you can direct a specific show rather than let the sky decide. It is built to be readable and writable by someone who has never programmed: one instruction per line, plain words, and very little punctuation.

It is also the single mechanism behind every scripted show the Nightmap makes for you. What's On Tonight, What's Up This Month and Captured Cosmos are all generated Tour DSL, written for you and then run the ordinary way (see section 9).

1.2 How a script works, in brief

A script is a list of scenes. Each scene points the camera at a target (a planet, a galaxy, a fixed patch of sky) and may then change the framing, run the clock, or apply an effect. Between scenes you can move the clock and the observer's location. Anything you leave unsaid, such as how wide to frame a planet or how long to linger, is filled in with the same sensible answer the live tour would use (see section 6).

1.3 Notation used in this manual

Command syntax follows the conventions of POSIX utility synopses:

Notation	Meaning
`GOTO`	A literal word, typed as shown. Commands are case-insensitive; this manual writes them in capitals.
`<target>`	A placeholder for a value you supply. Its type is defined in section 3.2.
`[ ... ]`	Optional.
`a \| b`	Choose one of the alternatives.
`...`	The preceding item may repeat.
`key=<value>`	A named option. Options may appear in any order after the command's positional arguments.

2Quick start

Sign in, open the Planetarium, open the Tours menu in the time bar and choose Script editor. It opens the script editor with a short example already in it.
Replace the text with your own script, for example the three-line program below.
Press Run. The editor slides away and the show plays. Pause, Next and Stop tour work exactly as they do in the live tour.
To keep it, give it a name and press Save. Copy link gives you an address anyone can open to watch it.

# The Moon at dusk on the night of the 2028 total solar eclipse
DATE 2028-07-22
JUMP dusk
GOTO Moon

That is a complete program. It selects a night, moves the clock to dusk on that night, and flies to the Moon, framed and held for as long as the live tour would.

3The language

3.1 Source text

Lines. A script is plain text. Each line holds at most one command. A command never continues onto the next line.
Case. Command words, option names and target names are case-insensitive. goto jupiter and GOTO Jupiter are the same.
Comments. # starts a comment that runs to the end of the line. It works anywhere on a line, including inside quotes, so a # can never be part of a caption. Blank lines are ignored.
Words and strings. Arguments are separated by spaces. Put text that contains spaces in double quotes: "Belt of Venus". There is no escape sequence, so a caption cannot contain a double quote.
Options. An argument of the form name=value is an option, for example fov=6 or hold=20s. Option names are letters only. A quoted argument is never read as an option.
Leniency. An unrecognised command word, and an unrecognised option, are ignored rather than reported. A typo does not sink the whole show, and it also means a misspelt command silently does nothing. See section 11.

3.2 Data types

Type	Form	Notes
`<duration>`	`20s`, `10m`, `2h`, `90`	A number with an optional unit: `s` (seconds), `m` (minutes) or `h` (hours); the long forms `sec`, `min`, `hr` also work. A bare number is seconds. Decimals are allowed (`1.5m`).
`<degrees>`	`45`, `0.75`	A decimal number of degrees. Used for field of view, azimuth and altitude.
`<azimuth>`	`az=90`	Compass bearing on the horizon: 0 north, 90 east, 180 south, 270 west.
`<altitude>`	`alt=8`	Degrees above the horizon: 0 on the horizon, 90 overhead.
`<fov>`	`fov=12`	Field of view, in degrees across the screen. A smaller number is a closer view.
`<fraction>`	`up=0.15`	A decimal between -0.5 and 0.5.
`<rate>`	`speed=600`, `0.1`	A multiple of real time. 600 means ten minutes of sky pass per real second.
`<date>`	`2028-07-22`	A calendar date, `YYYY-MM-DD`, year 0100 to 9999. An impossible date is ignored.
`<time-expr>`	`dusk`, `02:00`, `+30m`	A moment on the clock. Defined in full in JUMP.
`<latitude> <longitude>`	`-33.8688 151.2093`	Decimal degrees: south and west are negative. Not a place-name search.
`<target>`	`Jupiter`, `M31`, `iss`	Anything the search box understands. Listed in Appendix A.
`<string>`	`"Nearly at the ridge"`	Text, in double quotes when it contains spaces.

3.3 Program model

A script builds a list of scenes. Each scene is made of one or more stages, played in order. The commands fall into four classes:

Class	Commands	What they do
Scene starters	`GOTO`, `FOLLOW`	Begin a new scene and its first stage.
Stage adders	`ZOOM`, `EFFECT`, `TIMELAPSE`	Add another stage to the current scene, on the same target. They do nothing if there is no scene yet.
Modifiers	`HOLD`	Change the stage just added (look backwards).
Attachers	`NOTE`, `DATE`, `JUMP`, `LOCATION`	Attach to the next stage that is added, of any kind (look forwards). They must be written before the command they apply to.
Global	`SETTINGS`	Apply to the whole script, wherever they appear.
Endings	`REPEAT`, `TOUR`, `STOP`	Say what happens when the script runs out. The last one wins.

Read forwards or backwards? This is the one rule worth memorising. NOTE, JUMP, DATE and LOCATION prepare the next stage, so write them just before the line they belong to. HOLD adjusts the stage already written, so write it just after.

3.4 Order of evaluation

When a stage begins, its attached commands apply in a fixed order, whatever order you wrote them in:

LOCATION: the observer moves. This comes first because dusk, dawn and what is above the horizon all depend on where you are.
DATE, then JUMP: the clock is set (optionally with a glide, see section 7).
The target is looked up, at the new place and time. A name that is not up, or not recognised, ends the stage here: it is skipped and the script moves on.
Framing (fov, hold, up) is settled, borrowing the target's sensible defaults for anything you left out.
The camera flies to the target. When it arrives, the hold timer, clock rate and any effect start.

Targets are therefore resolved late, at the moment each stage begins and not when you write the script. JUMP dusk followed by GOTO Jupiter finds Jupiter where it really is at dusk.

4Formal grammar

The syntax in extended Backus-Naur form. Terminal words are case-insensitive and shown in capitals; { x } means zero or more, [ x ] zero or one.

script       = { line } ;
line         = [ statement ] [ comment ] , newline ;
comment      = "#" , { any character except newline } ;

statement    = motion | timing | clock | caption | settings | ending ;

motion       = ( "GOTO" | "FOLLOW" ) , ( target | [ title ] , "az=" degrees , "alt=" degrees ) , { option }
             | "ZOOM" , ( degrees | "photo" ) , { option } ;

timing       = "HOLD" , duration
             | "EFFECT" , ( "spin" | "librate" | "slowmo" , [ rate ] )
             | "TIMELAPSE" , ( duration | time-expr ) , { option }
             | "KEY" , "at=" , datetime , { option } ;

clock        = "DATE" , date
             | "JUMP" , time-expr , [ "glide" ] , { option }
             | "LOCATION" , latitude , longitude , [ string ] ;

caption      = "NOTE" , string ;
settings     = "SETTINGS" , { option } ;
ending       = "REPEAT" , [ integer ] | "TOUR" | "STOP" ;

option       = name , "=" , value ;
target       = word , { word } | string ;
title        = string | word ;
string       = '"' , { any character except '"' and '#' } , '"' | word ;

time-expr    = base , [ offset ] | offset ;
base         = "now" | "dusk" | "dawn" | "sunset" | "sunrise" | hh-mm ;
offset       = ( "+" | "-" ) , integer , ( "s" | "m" | "h" ) ;
hh-mm        = digit , [ digit ] , ":" , digit , digit ;
duration     = number , [ "s" | "sec" | "secs" | "m" | "min" | "mins" | "h" | "hr" | "hrs" ] ;
date         = digit , digit , digit , digit , "-" , digit , digit , "-" , digit , digit ;

The grammar describes well-formed input. The interpreter is deliberately more forgiving than the grammar: input that does not match a rule is ignored (section 3.1), not rejected.

5Command reference

Each entry gives the synopsis, a description, the options it accepts, examples and related commands.

GOTO

Begin a scene: fly to a target, or to a fixed patch of sky, and hold there.

Synopsis

GOTO <target> [fov=<degrees>] [hold=<duration>] [up=<fraction>]
GOTO ["<title>"] az=<degrees> alt=<degrees> [fov=<degrees>] [hold=<duration>] [up=<fraction>]

Description

The first form flies to a named target and tracks it as the sky turns. The second form aims at a fixed direction with nothing to track, which is how you frame a glow, a horizon feature or an empty patch of sky. The optional title names that sky point in the caption; without one it is called "Sky point". A quoted or plain word given together with az=/alt= is always a title, never a target lookup.

If the target is not up at the moment the stage begins, or the name is not recognised, the whole scene is skipped and the script carries on (section 3.4).

The Sun. A stage whose target is the Sun turns the whole view, with an ease in and out, until the Sun's own north pole points straight up the screen, so the sunspot bands read as above and below a horizontal equator. The next stage on anything else turns the view back to the usual horizon-up orientation, and so does the end of the script.

Options

fov=<degrees>: Field of view. Default: the target's own sensible framing (section 6).
hold=<duration>: How long to stay once arrived. Default: the target's own recommended dwell.
up=<fraction>: Aims lower by that fraction of the field of view, so the subject sits higher on screen and clear of the timeline bar. Range -0.5 to 0.5. Turns tracking off for the stage.
az=<degrees> alt=<degrees>: The fixed direction for the second form. Either one present selects that form.

Examples

GOTO Jupiter
GOTO M31 fov=12 hold=20s
GOTO "Belt of Venus" az=90 alt=8 fov=70
GOTO iss sun transit

See also: FOLLOW, ZOOM, NOTE, JUMP. Targets: Appendix A.

FOLLOW

Identical to GOTO, kept as a separate word for readability.

Synopsis

FOLLOW <target> [fov=<degrees>] [hold=<duration>] [up=<fraction>]

Description

Behaves exactly like GOTO. Use it when a script is specifically about tracking something that moves, such as a satellite pass, so the intent reads clearly.

FOLLOW iss

ZOOM

Add a stage on the same target at a different field of view.

Synopsis

ZOOM <degrees> [hold=<duration>]
ZOOM photo [hold=<duration>]

Description

Adds a stage to the current scene, keeping the same target. It is the way to push in for a close-up or pull back out again. A ZOOM straight after a GOTO on the same object is a plain, direct zoom, not a fly-round (section 6). It is ignored if there is no scene yet.

ZOOM photo shows the signed-in user's own solved, active photo of the scene's object (or the photo owner's, on a share page) clean: the view rolls until the photo's own top edge is the top of the screen (not the ground), zooms to fit the whole photo in the window, centres on it, and hides every other layer, so only the photo is drawn. A TIMELAPSE straight after keeps the clean view, with the roll tracking the turning sky so the photo stays upright. The next GOTO brings everything back. If there is no such photo it is an ordinary zoom to the given field of view. Captured Cosmos uses this.

Options

hold=<duration>: How long to stay at the new framing. Default: the target's recommended dwell for this stage.

GOTO Jupiter
ZOOM 15 hold=8s        # pull back to see it among its moons

HOLD

Set how long the current stage lasts.

Synopsis

HOLD <duration>

Description

Changes the real-time length of the stage that was just added. Write it directly after the GOTO, ZOOM or EFFECT it adjusts. It is ignored if no stage exists yet. An explicit hold= option on the command itself is equivalent.

GOTO pole
EFFECT spin
HOLD 45s

TIMELAPSE

Fast-forward the clock for a stretch, with the camera holding on the current target.

Synopsis

TIMELAPSE <duration> [speed=<rate>] [meteors=<shower>]
TIMELAPSE <time-expr> [duration=<duration>] [speed=<rate>]

Description

Adds a stage in which the clock runs at speed times real time while the camera stays on the current target, so the sky wheels past a fixed view. In the first form the duration is simulated time, and the stage lasts that time divided by the speed: TIMELAPSE 78m speed=600 covers 78 minutes of sky in about 7.8 real seconds. The duration must be whole numbers with a unit s, m or h.

The second form (anything that is not a whole-number duration, such as dusk or +30m) first jumps the clock like JUMP, then time-lapses for duration.

A time-lapse keeps whatever framing is already on screen. It does not choose a new default field of view, and it does not fly anywhere.

Options

speed=<rate>: Multiple of real time. Default 600.
duration=<duration>: Simulated time to cover, in the second form. Default 20 seconds of simulated time, which is very short at normal speeds, so give one.
meteors=<shower>: Animate that meteor shower during the stage: streaks run away from its radiant at a rate that follows the shower's strength, the radiant's height and the clock speed. Use an underscore for a space, for example meteors=Southern_Taurids. Starlink and bright-satellite layers are switched off for the stage and restored after.

GOTO M31
TIMELAPSE 50m speed=500           # about 6 seconds
TIMELAPSE 120m speed=600 meteors=Orionids

Note: a time-lapse runs the clock, so the clock is wherever it finished when the next stage begins. The next stage's flight always starts at normal speed, so a time-lapse never runs on into it.

KEY

A marker in a directed time-lapse: the clock and the camera travel to it together, then hold.

Synopsis

KEY at=<YYYY-MM-DDTHH:MM[:SS]> [az=<deg>] [alt=<deg>] [fov=<deg>] [walk=<east>,<north>] [height=<metres>] [speed=<rate> | over=<duration>] [hold=<duration>]
    [ease=smooth|linear] [shape=dome|straight] [name=<words_with_underscores>] [target=<name> aim=go|follow] [photo=<file> photohold=<duration> photosolved=1] [trails=on] [sattrails=on|night|off] [sattally=on] [layers=<name>,-<name>,...] [frame=off | frame=on f=<mm> sensor=<id> or=landscape|portrait roll=<deg> cam=<id> lens=<id> mx=<n>]

Description

Each KEY is one marker. From the second on, the clock runs from where it is to at while the view moves from where it is to az, alt and fov, and both arrive together. The first KEY of a script is a cut: it sets the time and view at once. The camera field of view is not tied to a target, so nothing is looked up: this is the one command that does not follow an object.

at is the observer's local time, in the zone given by SETTINGS tz= and for the place set by the last LOCATION. A LOCATION line before a KEY moves the observer for that marker. Director mode in the Planetarium writes these lines for you from the markers you place.

Options

walk=<east>,<north>: Where the observer stands, in metres east and north of the place (the Walk pad; up to 200 m, and only where a 1 m LiDAR ground is loaded). The observer glides there during the travel to this marker, so a show can walk along a creek bed or through a bridge. Director mode records it with every marker and writes it when it changes. Leave it out and the walk stays where the last marker put it; walk=0,0 goes back to the place. A LOCATION line resets it. When the show ends the observer is put back where it was.
height=<metres>: The tripod height: how high the camera is above the ground, 0.10 to 1.80 m (a Leofoto Poseidon LP-364CEX alone covers 0.115 to 1.58 m; the default is 1.5 m). It glides to this value during the travel, like walk, and the ground, the skyline and the reflections are seen from there. Director mode records it with every marker. Leave it out and it stays where the last marker put it; the viewer's own setting comes back when the show ends.
speed=<rate>: Simulated seconds per real second while travelling to this marker. The stretch lasts the time covered divided by this. Default 600.
over=<duration>: The real length of the stretch instead. Needed when the time does not change (a camera-only move, which otherwise takes 4 seconds).
hold=<duration>: Stay at the marker this long with the clock still. Default none.
ease=: smooth (default) eases the camera in and out of each stretch; linear moves it at a steady rate. The clock is always steady.
shape=: dome or straight: the sky shape (the Layers tab's Sky shape), applied as the stretch starts and put back when the script ends.
name=: A label for the marker, shown as the caption while it plays. Use underscores for spaces.
target=, aim=: Aim at a planet, the Sun or Moon, a deep-sky object, a comet or ISS/CSS/Hubble (underscores for spaces) instead of a fixed direction. aim=go flies the camera to it, and it arrives where the target is at the marker's own time (the camera tracks it while the clock runs); aim=follow also keeps it centred through the pause and on into the next stretch. az and alt are only the fallback if the target cannot be found.
trails=on: Star trails: the stars leave trails while the clock runs from the previous marker to this one, and the trails stay through the pause. The next marker clears them unless it also says trails=on. Director mode adds this with its star trail button.
sattrails=on|night|off: Sat trails: white trails behind the satellites (the ISS, CSS and Hubble, and the bright-satellite and Starlink layers when they are on). on is a comet tail that follows each satellite, as long as the clock speed makes it; night keeps every satellite's whole path while it is seen, like a long exposure, until the Sun comes up (the paths are cleared in daylight, when the time jumps back or far ahead, or when the place changes). The next marker clears it unless it also says sattrails=; a marker with no sattrails= falls back to the script's SETTINGS sattrails=, then to the Sat trails button. Trails are drawn only while the clock runs. Director mode has a Sat trails choice on each marker.
sattally=on: With Sat trails on, shows a running count of the different satellites seen (top left, and in an exported video): the space stations and telescope, bright satellites and Starlink, whichever layers are on. It restarts at night's end, when the time jumps, and when the place changes. The count is hidden during a script unless a KEY or SETTINGS line says sattally=on; outside a script it shows whenever Sat trails are on. Director mode has a Show count tick beside the Sat trails choice.
photo=, photohold=, photosolved=: Show a photo of the place over the sky when the marker arrives: photo is the file name of a location photo (Director mode picks it from the photos of the pins within 500 m), photohold how long it stays (default 5 seconds), and photosolved=1 draws its plate-solved stars, constellations and deep-sky names over it. It fades in, and fades out as the next marker starts to move, or after the hold on the last one. The photographer's credit is shown under it. With a TITLE on the same marker, the photo follows the title card.
layers=: Layer switches applied as the stretch starts, the same names as SETTINGS layers=. Restored when the script ends.
frame=: off hides the camera frame; on shows it with the given focal length, sensor, orientation and roll. Applied as the stretch starts.

SETTINGS tz=America/Denver
LOCATION 37.3162 -109.8575 "Valley of the Gods"
KEY at=2026-10-19T18:00:00 az=145 alt=20 fov=90
KEY at=2026-10-19T22:00:00 az=145 alt=20 fov=90 speed=3600 hold=2s    # 4 hours in 4 seconds
KEY at=2026-10-20T00:00:00 az=170 alt=27 fov=90 over=6s             # 2 hours in 6 seconds, turning the camera

See also: TIMELAPSE, LOCATION, SETTINGS.

TITLE

A title card (main heading, a line, a sub heading) over the next KEY marker's sky.

Synopsis

TITLE "<heading>" ["<sub heading>"] [hold=<duration>] [fade=<duration>]

Description

Like NOTE and JUMP, it attaches to the stage that follows, which must be a KEY. The card fades in over that marker's sky, stays for hold (default 4 seconds), and fades out; the show then carries on. The heading is set in the serif face, a thin line separates it from the sub heading, and either can be left empty. Director mode writes this line from its Title card fields, and it is drawn into an exported video too.

TITLE "Winter Milky Way" "Valley of the Gods, Utah" hold=5s
KEY at=2026-10-19T18:00:00 az=145 alt=20 fov=90

EFFECT

Add a stage that applies a special effect to the current target.

Synopsis

EFFECT spin
EFFECT librate
EFFECT slowmo [<rate>]

Description

spin: A star-trail time-lapse: three turns of the sky in the stage's hold time, drawing trails behind the stars. Sun, Moon, planets and satellites are hidden meanwhile. Best on GOTO pole, which supplies a wide, terrain-aware field. The camera cuts straight into a spin rather than flying slowly.
librate: A Moon-libration time-lapse: one lunar month, showing the Moon's face rocking.
slowmo [<rate>]: Runs the clock at a fraction of real time. Default 0.1. Useful for very brief events.

GOTO Moon
EFFECT slowmo 0.2
HOLD 10s

DATE

Select an observing night.

Synopsis

DATE <YYYY-MM-DD>

Description

Attaches to the next stage. It sets the clock to noon on that date in the observer's time zone, which marks the start of an observing night. A following JUMP then resolves against that night, so DATE 2028-07-22 then JUMP dusk means dusk on 22 July 2028, and JUMP 02:00 means 2 a.m. the following morning. Without a JUMP the stage starts at noon.

DATE applies before JUMP whichever order you write them in, and after LOCATION. Years 0100 to 9999 are accepted; an invalid date is ignored. A later DATE selects another night.

DATE 2028-07-22
JUMP dusk
GOTO Moon

JUMP

Move the clock before the next stage begins.

Synopsis

JUMP <time-expr> [glide[=<duration>]]

Description

Attaches to the next stage and sets the clock to a moment described by a time expression: a base, an offset, or both.

Base	Meaning
`now`	The current simulated time (so after `DATE` it stays on that date).
`dusk`	The next time the Sun falls to 8 degrees below the horizon.
`dawn`	The next time the Sun rises to 8 degrees below the horizon.
`sunset`, `sunrise`	The Sun crossing the horizon.
`HH:MM`	A clock time in 24-hour form, read against the current observing night (noon to noon). `22:30` is that evening; `02:00` is the early morning after it.
`+<duration>`	A later time, relative to the current one: `+30m`, `+2h`, `+45s`.

An offset can follow any base: dusk -10m is ten minutes before dusk, now +37200s is 37,200 seconds after the start of the selected night. The offset is a whole number followed by s, m or h. Two JUMP lines with no stage between them do not add: the second replaces the first.

Options

glide[=<duration>]: Make the change gentle instead of a cut. A change of up to 3 hours is an eased sweep of the clock (glide=5s sets how long it takes; the length is otherwise chosen from the size of the jump). A longer change dips to black, changes the clock while dark, and fades back in with the camera already on the next target. See section 7.

JUMP dusk
JUMP dusk -10m
JUMP 02:15 glide
JUMP +20m glide=3s

LOCATION

Move the observer before the next stage begins.

Synopsis

LOCATION <latitude> <longitude> ["<name>"]

Description

Attaches to the next stage and moves the observer to those coordinates. It applies before that stage's DATE/JUMP, because dusk, dawn and what is up all depend on where you stand. The name is only a label. Coordinates only: it does not search for a place by name.

The observer is put back to where the viewer really was when the script ends. A script that moves the observer and then ends with TOUR keeps that place for the live tour (section 5, TOUR).

LOCATION -33.8688 151.2093 "Sydney"

NOTE

Caption the next stage.

Synopsis

NOTE "<text>"

Description

Sets the caption shown while the next stage plays, under the target's title. It always captions the stage that follows, never the one before, so write it directly ahead of the GOTO, ZOOM or EFFECT it describes. The text cannot contain a double quote or a # (which starts a comment).

NOTE "The pink glow opposite the sunset"
GOTO "Belt of Venus" az=90 alt=8

SETTINGS

Show-wide defaults and layer switches.

Synopsis

SETTINGS [dwell=<duration>] [fov=<degrees>] [layers=<name>[,<name>...]] [tz=<zone>] [shape=dome|straight] [sattrails=on|night|off] [sattally=on]

Description

Applies to the whole script wherever it appears. A script may contain several; later ones add to, and can override, earlier ones.

Options

dwell=<duration>: The fallback hold time, used only when nothing more specific applies. It never overrides a target's own recommended dwell or an explicit hold=.
fov=<degrees>: The same idea for field of view.
layers=<list>: Layers to switch on for the run of the script. A name switches it on; a - prefix switches it off, for example layers=starlink,-atmosphere. They are restored when the script ends and are never saved to the viewer's own preferences. Names: Appendix B. An unknown name is ignored.
shape=<dome|straight>: The sky shape for the run: dome is the true sky with a curved horizon, straight keeps the horizon level at every tilt (a panorama-style view that stretches the sky sideways the higher you look, and stops at 80 degrees up). Like layers= it is restored when the script ends and never saved to the viewer's own setting. Camera view, snapshots and a rolled view such as the Sun's keep their own projection whatever this says.
sattrails=<on|night|off>: Sat trails for the run of the script, as for KEY sattrails=: on comet trails, night the whole path all night, off none. A KEY can override it for its own stretch. Restored when the script ends.
sattally=<on|off>: Show the running satellite count for the run of the script (needs Sat trails on): see KEY sattally=.
tz=<zone>: The time zone that DATE and JUMP HH:MM are read in and the clock is shown in, as an IANA name such as Australia/Brisbane. Normally the zone is looked up from the observer's position, but that lookup is coarse near borders (a lookout just inside Queensland can come out as New South Wales, which changes at daylight saving). Restored when the script ends. An unknown name is ignored.

SETTINGS dwell=20s layers=starlink,curatedImages tz=Australia/Brisbane

REPEAT

At the end of the script, play it again.

Synopsis

REPEAT [<times>]

Description

When the script runs out of stages it starts again from the top. With a number, it plays that many more times (REPEAT 2 plays three times in all, at most 100 more); without one, it loops until the viewer presses Stop tour. Each pass starts from the top, so begin the script with LOCATION, DATE and JUMP and every pass starts in the same place and at the same time. If nothing played in a pass because every target was below the horizon, the script stops instead of spinning.

TOUR

At the end of the script, carry on into the live sky tour.

Synopsis

TOUR

Description

When the script ends, the live tour starts, in real time, from wherever the script's LOCATION left the observer. The clock returns to the present.

STOP

At the end of the script, stop.

Synopsis

STOP

Description

The default, so it is only needed to be explicit. If a script contains more than one of REPEAT, TOUR and STOP, the last one wins. Write the ending as the final line.

6Defaults and framing

6.1 Smart defaults

Leaving out fov= or hold= does not mean "40 degrees for 15 seconds". It means use the sensible default for this kind of target, the same numbers the live tour computes:

A star-trail spin at the pole gets a wide field, sized to keep the terrain and the whole turning sky in frame.
A planet gets a tight close-up.
A deep-sky object with a curated or user photograph gets a field sized to that photograph.
A comet, satellite pass, the Milky Way arch and everything else get their own tuned defaults.

The lookup order for an unspecified fov or hold is: the value on the line; the target's own recommendation; the script's SETTINGS fov=/dwell=; and last of all a flat 40° and 15 s. A fixed sky point has no target to borrow from, so it falls back to a wide 70° and 15 s unless SETTINGS says otherwise.

In practice: write GOTO Jupiter and trust it to frame Jupiter properly. Add fov=/hold= only when you want something different, such as a deliberately wide establishing shot before a ZOOM.

6.2 Flights

Every flight, whether a GOTO to a new target or a ZOOM/EFFECT/TIMELAPSE on the current one, uses the cinematic move the live tour uses: zoom out, pan across, zoom in. A long pan at high zoom would otherwise blur past everything between. There is no command for this; plain GOTO lines already get it.

The zoom-out and pan are skipped when the destination barely moves, so a ZOOM straight after a GOTO on the same object is a plain, direct zoom. The one exception is the hop straight into EFFECT spin or librate, which is a fast cut.

Budget time for flights. A flight across a wide stretch of sky can take several real seconds, and the flight is part of the show. If a hold feels short, that is usually why.

7Time, place and transitions

7.1 Cuts and glides

By default a JUMP or DATE is a cut: the clock changes and the view arrives at the new sky. For anything the viewer should follow, add glide:

Change of time	What the viewer sees
Up to 3 hours	A smooth, eased sweep of the clock over roughly 2 to 4 seconds (or the length you give with `glide=<duration>`): the sky wheels gently.
More than 3 hours	The picture fades to black, the clock changes once while dark, and the picture fades back in, with the camera already settled on the next target so the flight is a gentle push-in and not a swing across the sky.

Long jumps are never swept because running days or months of sky past at once flashes between day and night and spins the stars, which is uncomfortable to watch. Any click or drag finishes a glide immediately, and pausing the tour pauses it.

7.2 Observing nights

Times such as HH:MM, dusk and dawn are read against an observing night: the stretch from one local noon to the next. That is why JUMP 02:00 lands in the early morning after the selected evening, and why DATE puts the clock at noon first. dusk and dawn use a Sun altitude of -8 degrees, a little into civil twilight and past the point it is worth arriving early.

7.3 Moving the observer

LOCATION changes the observer's place, time zone and horizon. Combine it with DATE, JUMP and glide for a show that travels: the place is changed first, then the time, then the target is looked up.

8Running, saving and sharing

8.1 The script editor

Script editor in the time bar's Tours menu opens the editor. It is shown to signed-in users. The editor has a text box, Run, New, Save, Copy link and a list of your saved tours.

Run plays whatever is in the box, saved or not. The editor slides away while the show plays and returns when it ends.
Save stores the script as a named Tour on your account, listed with Load, Run, Copy link and Delete. Saving again after loading a tour overwrites that same tour. New clears the box so the next Save asks for a fresh name. Saving a new script under a name you already use replaces the old one.
Copy link gives an address that plays the script for anyone (section 8.2).
Opening the editor during a show fills it with exactly the script that is playing, however you started it, so you can change it and press Run to restart.

While a show plays, Pause, Next (skip to the next scene) and Stop tour work as in the live tour. Pause freezes the whole show, the clock included: a time-lapse stops mid-sweep and Resume carries on at the same speed, so you never need to pause the timeline separately. Dragging, zooming or pressing Escape also ends the show.

8.2 Links

Link	Plays
`/planetarium?dsltour=<slug>`	A saved Tour, from its slug. Works for anyone with the link, signed in or not, and starts at the tour's saved location.
`/planetarium?script=<text>`	A script carried in the link itself, at the location in the link. This is how the generated shows share.
`/planetarium/<your-name>?play=1`	Your first shared tour, from your shared Planetarium page. `?play=cosmos` plays Captured Cosmos; `?play=Tour name` a named tour. See the guide.

Warp: the speed of a show

Any of these links can carry a warp, a number from 0 to 10 that sets how fast the show moves: &warp=10. 0 is normal speed (the default, so leave it out) and 10 is the fastest, the busy pace once called kids. Decimals work (&warp=3.5) and values outside 0 to 10 are held at the nearest end.

Warp does two things at every stage, whether the script is a live tour, a generated show or one you wrote. It shortens the time the show stays at each stop (hold, or the stage's own length), and it shortens each camera flight. It is geometric: at warp w the time at each stop is 0.35^w/10 of normal and a flight is 0.6^w/10 of normal, so each step is the same proportional change and warp 10 lands on 35% and 60%. A TIMELAPSE stage is shortened with the stop, so a higher warp covers less of the night before it moves on. Explicit durations in a script are scaled too: write the script for normal speed and let the warp speed it up.

Warp	Time at each stop	Flights
`0`	100%	100%
`2`	81%	90%
`5`	59%	77%
`8`	43%	66%
`10`	35%	60%

The viewer's own warp is the Warp slider in Settings > Tour (saved in that browser). A warp in a link applies for that visit only and never overwrites it. Copy link, Share and the profile's autoplay links add your current warp automatically.

For a mix that the warp scale cannot make, give the two figures as percentages instead: &hold=35&flight=60, the time at each stop (20 to 200) and the flight duration (40 to 150). They win over warp if both are present, and the Settings sliders for them fine-tune the warp.

Older links. The earlier &pace= name still works and is read as a warp: standard is 0, quick is 5 and kids is 10. &pace=relaxed (150% at each stop, normal flights) is slower than normal, which warp does not go below, so it keeps its own values. If a link has both, warp wins. New links should use warp.

Your saved Tours also appear on your Profile under Planetarium Tours, and sync across devices.

9Generated scripts

Three guided shows are written by the Planetarium as ordinary Tour DSL and then run like any other script. Studying one is a good way to learn the language.

Show	Where	What it writes
What's On Tonight	Guided shows menu, `?event=tonight`	The Belt of Venus at dusk, a polar star-trail spin, then the night's best targets in the order they happen, plus any conjunction or Jupiter-moon event.
What's Up This Month	Guided shows menu, `?event=month`	The month's events in date order, each as `DATE`/`JUMP`/`NOTE`/`GOTO`: Milky Way windows, oppositions, conjunctions, satellite passes, comets, meteor showers, eclipses and deep-sky compositions.
Captured Cosmos	Guided shows menu (with your own photos)	A cinematic scene per photo: the object wide in the real sky, a push in to your photograph, a short time-lapse, then a pull all the way out to the whole sky (170 degrees, with the horizon in view; a `GOTO ... fov=170 up=...` scene) from which the next scene flies back in. Uses `glide` between scenes, `SETTINGS layers=ground,terrain` to anchor the whole-sky view, and ends with `REPEAT`.

To read or change one, open the Script editor while it plays, or (for Captured Cosmos) choose Captured Cosmos: edit script to have it written into the editor without playing. A generated script that you save is a fixed copy: it does not update itself as the sky, or your photos, change.

10Worked examples

10.1 An evening tour with a spin and slow motion

Uses SETTINGS, a wide opener, a literal sky point, a star-trail spin, and a slow-motion Moon.

# A short example show - copy this as a starting point.
# Nothing here specifies fov/hold except where it's deliberately overriding
# a sensible default, or framing a literal sky point that has none of its own.

SETTINGS dwell=20s layers=starlink,curatedImages

# A wide look at everything up right now, to open the show
NOTE "Tonight's sky, wide open"
GOTO overview

# Jump to dusk and frame the Belt of Venus - a fixed sky point, nothing to track
JUMP dusk
NOTE "The pink glow opposite the sunset"
GOTO "Belt of Venus" az=90 alt=8

# A star-trail spin at the pole - wide by default, no fov needed
JUMP +10m
NOTE "Polar alignment: the point the whole sky turns around"
GOTO pole
EFFECT spin
HOLD 45s

# A planet, tight by default; then pull back to see it in context
JUMP +20m
GOTO Jupiter
ZOOM 15

# The Moon in slow motion, then a deep-sky object with its own photograph
JUMP +15m
GOTO Moon
EFFECT slowmo 0.2
HOLD 10s

JUMP +20m
NOTE "The Lagoon Nebula"
GOTO M8

10.2 One object from rising to setting, and looping

The Andromeda Galaxy over one night from a named place: a wide fixed frame while it is too low to follow, a time-lapse up to its highest point, a close-up and pull-back, and a second time-lapse that stops just short of the ridge. It ends with REPEAT, so it loops.

# M31 from Jack Ferris Lookout: rising, highest point, then sinking toward the ridge.
# 10 Oct 2026 is a new Moon, so the sky stays dark all night.

LOCATION -26.938 152.9366 "Jack Ferris Lookout"
DATE 2026-10-10

# M31 clears the north-eastern horizon at about 18:58. Too low to follow as a
# named target, so frame that patch of sky itself and let the clock run.
JUMP 18:50
NOTE "M31 is about to rise over the north-eastern horizon"
GOTO "M31 rising" az=45 alt=14 fov=60 hold=8s

NOTE "Time-lapse: the Andromeda Galaxy climbs the northern sky"
TIMELAPSE 110m speed=600

# High enough to follow now. Run on to its highest point (transit 23:14).
NOTE "M31 keeps climbing"
GOTO M31 fov=30 hold=5s
TIMELAPSE 154m speed=1000

NOTE "M31 at its highest, 22 degrees up"
ZOOM 4.8 hold=16s
NOTE "Zooming back out to see it in the sky"
ZOOM 30 hold=5s

# Now sliding into the north-west: stop while it is still clear of the terrain.
NOTE "M31 sinks toward the north-western ridge"
TIMELAPSE 205m speed=1200
NOTE "Nearly at the ridge"
ZOOM 4.8 hold=20s

REPEAT

Points worth noting: GOTO "M31 rising" az= alt= is used first because a named target has to be well up to be offered, whereas a fixed sky point can frame the horizon; the durations are simulated time, so 154m at speed=1000 is under ten real seconds; and because REPEAT restarts from the top, the leading LOCATION, DATE and JUMP 18:50 return every pass to the same evening.

10.3 A show that travels

Two places in one script. glide makes each change of night a fade, and the second LOCATION comes before its DATE.

LOCATION -31.273 149.064 "Siding Spring, Australia"
DATE 2026-10-10
JUMP 23:00
NOTE "The Small Magellanic Cloud from the southern hemisphere"
GOTO "Small Magellanic Cloud" fov=16 hold=10s

LOCATION 28.76 -17.89 "La Palma, Canary Islands"
DATE 2026-12-07
JUMP 05:35 glide
NOTE "Bode's Galaxy, circumpolar from the north"
GOTO M81 hold=10s

STOP

10.4 Ending in the live tour

JUMP dusk
GOTO Venus
ZOOM 3
TOUR                       # after the close-up, hand over to the live tour

11Diagnostics and limits

The interpreter never stops a script with an error message. It follows the rules below, so when something does not play, look here first.

Situation	Behaviour
Unknown command word	The line is ignored. A misspelt `GOTOO` does nothing.
Unknown option (`colour=red`)	Ignored.
Target not up, too faint, or not recognised	That scene is skipped and the script carries on. Check the spelling if a scene "vanishes".
`ZOOM`, `EFFECT`, `TIMELAPSE` before any `GOTO`	Ignored: there is no scene to add a stage to.
`HOLD` before any stage	Ignored.
Invalid `DATE` (2027-02-30, year below 0100)	Ignored; the clock is not changed by it.
`LOCATION` without two numbers	Ignored.
Two `JUMP` lines, nothing between	The second replaces the first. They do not add.
`NOTE` placed after its `GOTO`	It captions the next stage instead. Move it above the line it belongs to.
`#` inside a caption	Starts a comment, so the caption is cut at that point. Avoid the character in text.
A double quote inside a caption	Not supported; there is no escape. Use an apostrophe.
More than one of `REPEAT`, `TOUR`, `STOP`	The last one wins.
`REPEAT` where no scene ever plays	The script stops instead of looping forever.
Click, drag, zoom or Escape during a show	Ends the show. A click during a `glide` finishes the glide.

Limits

Item	Limit
Length of a saved script	20,000 characters
Saved tours per account	100
Tour name	120 characters, unique within your account
`REPEAT <times>`	Up to 100 additional passes
Captured Cosmos	Up to 12 photos per show
Signing in	Writing, running and saving from the editor needs an account. Anyone can watch a shared link.

12Quick reference

Command	Syntax	Applies to
`GOTO`	`GOTO <target> [fov=] [hold=] [up=]` `GOTO ["title"] az= alt= [fov=] [hold=]`	Starts a scene
`FOLLOW`	as GOTO	Starts a scene
`ZOOM`	`ZOOM <fov> [hold=]`, `ZOOM photo [hold=]`	Adds a stage
`HOLD`	`HOLD <duration>`	The stage just written
`TITLE`	`TITLE "heading" ["sub heading"] [hold=] [fade=]`	A title card over the next KEY
`KEY`	`KEY at= [az=] [alt=] [fov=] [speed= \| over=] [hold=] [ease=] [shape=] [name=] [target= aim=] [photo= photohold= photosolved=] [trails=on] [sattrails=] [sattally=on] [layers=] [frame=]`	A director marker: clock and camera travel there together
`TIMELAPSE`	`TIMELAPSE <duration> [speed=] [meteors=]` `TIMELAPSE <time-expr> [duration=] [speed=]`	Adds a stage
`EFFECT`	`EFFECT spin \| librate \| slowmo [rate]`	Adds a stage
`NOTE`	`NOTE "text"`	The next stage
`DATE`	`DATE YYYY-MM-DD`	The next stage
`JUMP`	`JUMP <time-expr> [glide[=dur]]`	The next stage
`LOCATION`	`LOCATION <lat> <lon> ["name"]`	The next stage
`SETTINGS`	`SETTINGS [dwell=] [fov=] [layers=] [tz=] [shape=]`	Whole script
`REPEAT`	`REPEAT [times]`	End of script
`TOUR`	`TOUR`	End of script
`STOP`	`STOP`	End of script

Time expressions: now · dusk · dawn · sunset · sunrise · HH:MM · +30m · any of these followed by +/-N[smh].

ATargets

A target is any name the Planetarium's search box or a plain ?tour=<name> link understands. It is looked up when the stage begins.

Kind	Examples
Sun, Moon, planets	`Sun`, `Moon`, `Venus`, `Jupiter`, `Saturn`
Deep-sky objects	Messier and NGC numbers and common names: `M31`, `M42`, `NGC 3372`, `Large Magellanic Cloud`
Comets	Any catalogue comet by name
Constellations	`Crux`, `Scorpius`, `Orion`, `Sagittarius`, `Centaurus`, `Carina`, `Canis Major`, `Cygnus`, `Leo`, `Taurus`, `Gemini`, `Lyra`, `Ursa Major`, `Aquila`
Satellites	`iss`, `css`, `hubble`
Satellite transits	`iss sun transit`, `hubble moon transit` (a satellite must be named)
Special views	`pole` (the celestial pole nearest you), `milkyway`, `overview` (a wide look at everything up)
Fixed sky point	Not a name: `GOTO ["title"] az= alt=`

A planet or the Moon is offered once it is more than 3 degrees up, and a deep-sky object once it is more than 3 degrees up, which is lower than the live tour would offer it, so a script can follow a target down toward the horizon.

BLayer names

For SETTINGS layers=. They match the Layers panel.

`stars`	`constellations`	`dso`	`moonLabels`
`curatedImages`	`altazGrid`	`eqGrid`	`ground`
`terrain`	`lightPollution`	`brightSats`	`starlink`
`atmosphere`	`airglow`	`terrain3d`	`moonRelief`

CRevision history

Revision	Change
22 Oct 2026	Adds `sattally=on` to `KEY` and `SETTINGS`: a running count of the satellites seen.
22 Oct 2026	Adds `sattrails=on\|night\|off` to `KEY` and `SETTINGS`: white satellite trails, as a comet tail or kept all night.
20 Oct 2026	`KEY` gains `trails=on`: star trails while the clock runs into the marker.
19 Oct 2026	`KEY` gains `photo=`, `photohold=` and `photosolved=`: a location photo over the sky at a marker.
19 Oct 2026	Adds `TITLE`, a title card over the next `KEY`.
19 Oct 2026	Adds `KEY`, a directed time-lapse marker (clock and camera travel together). Director mode writes them.
8 Oct 2026	Adds `SETTINGS shape=dome\|straight`, the sky shape for the run (the Layers tab's Sky shape setting, also `proj=` in a link).
5 Oct 2026	Adds the `airglow` layer name for `SETTINGS layers=` (Appendix B). It is off unless a script or the viewer switches it on.
4 Oct 2026	Show speed is now warp, 0 (normal) to 10 (fastest), on a geometric scale: `&warp=` in a link and the Warp slider in Settings. `&pace=` names still work (`standard` 0, `quick` 5, `kids` 10). See section 8.
2 Oct 2026	`SETTINGS tz=` names the time zone a script's dates and times are read in.
2 Oct 2026	Adds `ZOOM photo`: a clean, upright view of the user's own photo.
30 Sep 2026	Manual split from the Planetarium guide. Documents `REPEAT`, `TOUR`, `STOP`, `JUMP ... glide` with the fade for long jumps, and the `GOTO ... up=` option. Corrects the sign-in requirement for the script editor.
Earlier	`DATE` and `LOCATION`; `TIMELAPSE ... meteors=`; `SETTINGS layers=`; targets resolved late; smart defaults; the initial command set (`GOTO`, `FOLLOW`, `HOLD`, `NOTE`, `ZOOM`, `EFFECT`, `TIMELAPSE`, `JUMP`, `SETTINGS`).

DCommand index

DATE · EFFECT · FOLLOW · GOTO · HOLD · JUMP · KEY · LOCATION · NOTE · REPEAT · SETTINGS · STOP · TIMELAPSE · TITLE · TOUR · ZOOM

Related: the Planetarium guide covers using the Planetarium, your own photos, Captured Cosmos and sharing.