Skip to content

Scripted tours and sounds

A tour plays a deck by itself, like a video. A slide can describe what the tour does on it: a virtual cursor glides to a real element and clicks, drags or types, and the slide reacts exactly as it does for a viewer. A slide can also ask for sounds. Both are plain frontmatter, no per-slide JavaScript.

---
layout: default
tour: 8                              # the longest the slide stays, in seconds
tourScript:
  - { at: 1.2, hover: B, caption: "Which file holds the deck?" }
  - { at: 2.6, click: C }
sounds:
  - { at: 2.75, src: success, volume: 0.8 }
---

nimbledeck check validates every key below and the files of public/.

Tour steps

Each step has at (seconds from the slide's entry) and exactly one action.

Action Value Extra keys What happens
click target pointer and mouse events, then click
hover target pointer over and move events
drag target from, to (0 to 1 along the target, default 0.1 and 0.9), over (seconds, default 1.2) pointer down, moves, up; on <input type=range> it sets the value and fires input and change
key key name, such as "3" or "ArrowRight" keydown and keyup on the focused element
type text into (target, default the first editor), speed (ms per character) focuses the editor and types, CodeMirror included
wait seconds nothing, keeps the slide
any caption a small bubble beside the cursor, at most 48 characters

Targets: a capital letter is a quiz choice (B), text:Some words is the smallest element holding that text (its button or link if it has one), anything else is a CSS selector searched inside the slide. Targets are found when the step runs, never by fixed coordinates, so scale and layout do not matter. A missing, hidden or inert target (a recording stands in for a live editor, an offline panel) skips the step silently and the script keeps its time.

Pacing

A slide stays until its entrance has settled (nothing finite still animating, typing or counting), plus a reading hold of 1.2 to 2.5 seconds. Bounds: at least 3 seconds, at most 6 unless tour: <seconds> says more. A script keeps the slide at least until its last step ends. tour is therefore a maximum, and the clock's total is an estimate that corrects itself.

Events and stopping

The tour's events are synthetic (isTrusted is false) and never stop it. A real key, click, wheel turn or touch does. While a tour runs, setPointerCapture is a no-op for the tour's own pointer, so Compare and three.js controls work. Reduced motion: the cursor jumps without gliding.

Sound

Off until the viewer opts in; the browser needs a gesture, so the AudioContext is created by a click on a sound control (the speaker button, or starting the tour from the big button marked "with sound"). The choice is kept in localStorage. The speaker says what it does: "Sound: music, plus effects when you click or when the tour plays".

There are three kinds of sound.

  1. Music: ndSound: uplift in the headmatter is a bed that plays while sound is on, in both modes, and ducks under cues.
  2. Effects, driven by what happens on the page, so they are aligned by construction and sound for a real viewer too: the quiz answer (success, or a soft tick when wrong), a click on a look or motion card or a Looks chip (a pop whose pitch follows the card), typing in Typewriter, Terminal and Livedeck (a key sound per character typed), a Stat landing (a soft pop), the Compare divider crossing each tenth (a tick), a Kinetic title starting (a pluck), a Livedeck slide appearing and a LiveCode run finishing. The tour's synthetic events trigger the same sounds, so the video is aligned too. Every one goes through sfx(name, { volume, pitch }) of useSound, costs nothing when sound is off, is rate limited, and every component has a quiet prop to turn its effects off.
  3. Soundtrack of the tour: frontmatter cues for the video only. They play while the tour plays and stop when the viewer takes over.
Key Where Meaning
sound: whoosh slide one soundtrack cue on entry; a name or a file of public/ such as /audio/theme.mp3
sounds: [{ at, src, volume, when }] slide soundtrack cues at offsets; volume above 0 and at most 1; when: always plays the cue outside the tour too (default tour)
ndSound: uplift headmatter the music bed
ndSlideSound: whoosh headmatter a soundtrack cue on every slide change in the tour

Write a soundtrack cue only for something no component makes a sound for (a whoosh between slides, a swell, the finale). A cue that repeats a click or a typed character drifts out of step; let the component's own sound do it.

Built-in sounds, synthesised with the Web Audio API (no files, offline): click, tick, pop, whoosh, riser, chime, success, soft-boom, pluck, typing, swell, finale, pad, uplift. Everything passes through a limiter and a master gain, so stacked cues stay quiet. <SoundToggle /> is the speaker button and <Equalizer /> draws the real output.

The site bar: any deck gets it

The bar (wordmark, links, slide arrows, "Play the tour" with a clock such as 0:13 / 2:25, the big "Watch the tour" button on the first slide, a progress hairline) is the addon's SiteBar component, mounted by the addon's global-top.vue. A deck needs no code for it. It renders only when the page defines window.__ND_SITE__ ({ docs, playground, github, science? }) and adds the class nd-site-bar to <html>: website/build.mjs writes both into the built pages of the showcase, /demos/how-it-works/ and /demos/science/ (dressDeck in website/home.mjs). The dev server, the PDF export and any other build define neither, so nothing shows and nothing takes room. /?tour starts the tour by itself, a real key, click, wheel turn or touch takes over, and a shield keeps the real pointer off the slide while it plays. The speaker button and the "with sound" switch appear only for a deck with ndSound or ndSlideSound, so a quiet deck shows neither. To give another hosted deck the bar, call dressDeck on its folder after the build and give its slides a tour: time.

Ending a deck

<NextSteps /> on a closing slide shows link cards read from window.__ND_SITE__: docs, playground, the science deck when the site has one, GitHub, and "Replay the tour" (it sends nd-tour-replay, which the site bar answers by going to slide 1 and playing). Without __ND_SITE__ only the GitHub card shows. :skip="['science']" leaves cards out (keys: docs, playground, science, github, replay), for a deck that should not link to itself. A tour script may hover a card but never clicks a link.

Tips for agents

  • Start steps at 1 second or later: the glide takes up to 0.8 s before at.
  • Put one cue per sounds entry; chain typing cues for long typing.
  • Test with examples/showcase/e2e-tour.mjs (add --full for the per-slide timing table), and with measure-sound.mjs after touching a sound.

Music from a file

ndSound: /audio/some-track.mp3 plays a file of public/ as the bed, looped, much lower than the built-in beds and ducked under effects (FILE_BED in soundManager.mjs). The showcase uses "Origami" by Scott Buckley (CC-BY 4.0, credit required: see THIRD_PARTY.md). Only use music whose licence lets you ship it with the deck, and keep the credit on a slide. A bed is looped, so cut it to loop cleanly: a whole number of phrases on the beat, with the end cross-faded into the music that precedes the start (the showcase's loop was made this way, see public/audio/CREDITS.md), and avoid a track's slow ending.