The presentation standard: notes and keys for any HTML deck

An HTML presentation (a deck you open in a browser) can tell Laser Pointer its speaker notes and the keys the phone should offer, with no script of ours. The deck links one JSON file; the PC app reads it from the deck's own folder, on this computer or at an HTTP or HTTPS address.

What the phone gets:

  • the speaker notes of the slide showing, in the notes panel (the one PowerPoint's notes fill);
  • the slide's keys and the deck-wide keys in separate rows under the slide controls. Each row wraps onto more lines when needed; buttons keep their shape (the picked keys stay on a slide without its own or deck-wide keys). A tap presses that key on the computer, as if you pressed it on the keyboard, so it reaches whatever has focus, an embedded page included;
  • the guest holding the floor gets only keys marked with "guests": true, when the room's floor keys switch is on. Unmarked keys still appear on the presenter's phone.

Guest-marked keys replace the presenter's floor pick for that slide, with the slide's marked keys first, then the deck-wide marked keys, deduplicated and capped at 8 after filtering. If none are marked for that slide, the floor gets the presenter's pick, even while presenter-only declared keys are shown on the phone. A slide without its own or deck-wide keys keeps the picked row on the phone. Saving a non-empty pick turns Keys for the floor on; switch it off to keep those keys on your phone only.

Pick floor keys says when the presentation's own keys are in use, naming it when known. Your pick still saves. It appears on your phone on slides without declared keys, and goes to the floor when no keys are marked for guests.

In Pick floor keys, tap keys on the keyboard to pick up to eight combinations. Turn on Shift, Ctrl or Alt before tapping a key; the toggles turn off after adding it. Keys that cannot combine with those modifiers are disabled. Picked plain keys are marked; tap one again to remove it, or remove any combination with its chip. On the PC, turn on Press a key to pick using the hardware keyboard. Repeated combinations are refused; turn the toggle off to use keyboard navigation in the dialog again.

Screen pictures

When the guests' Screen pictures switch is on, the PC captures the presentation monitor after navigation from this app, and, for a deck whose title gives the slide, whenever the slide shown has no picture yet, only while the deck's browser is in front (and again when it goes to or leaves full screen). The phone gets the current picture (the next after it has been seen), and guests can zoom and look back. A known window-title position signals that navigation landed; without it, capture uses a short settle delay. Build steps count as positions; Back then Next reuses the stored picture. Pictures have a memory budget, oldest dropped first, and clear on a new deck or show end. The switch off captures and shares no screen pictures.

Use this app's slide controls: PC keys, clickers, mouse clicks and links can desynchronize the positions until Start. Screen capture includes other windows and notifications on the presentation monitor; turn on Focus / Do Not Disturb and keep that monitor clear. Windows supports capture, taking the picture from the presenting window when it fills the monitor (so the laser dot stays visible in a screen share) and from the monitor otherwise; other desktop platforms currently return no picture through the same capture contract.

Optional: a deck that opens on slide n at <address>#n (index.html#5 shows slide 5) gets a preview of every slide on the presenter's phone, also of slides not yet shown. On Windows the PC renders each declared slide in the app's own hidden web view (WebView2, with its own empty profile; no Edge or Chrome is started; macOS and Linux give no previews yet) when the deck is first used, opened again, or re-read with changed declared slides (titles, notes or count), at <address>#n:end: a deck that opens a slide fully built there gives its slide list fully built previews; one that reads only the number gives the slide as it opens. The screen's own picture replaces the render in the current and next previews. Renders go to the presenter's phone only: guests still see only slides already shown. A deck whose slides 1 and 2 render alike is taken as not following #n and gets no renders. A revisited declared slide is pictured again on arrival, keeping its old screen picture until the new one is ready.

Optional: a slide that builds in steps puts them after its position in the title, <index>/<total>:<step>/<steps> (13/60:2/4 · The answers), step 0 before the first build. The phone then shows the steps left as a program's animation clicks, and the screen picture is taken again after each step. A title without them still gives the slide.

Add the declaration

  1. Put a line in the deck's <head>:

    <link rel="presentation" href="presentation.json">
  2. Put presentation.json in the same folder as the deck's HTML file:

    {
      "version": 1,
      "keys": [
        {"keys": "Space", "label": "Play", "guests": true},
        {"keys": "t", "label": "Toggle theme"}
      ],
      "slides": [
        {"title": "Welcome", "notes": "Say hello.\nIntroduce the topic."},
        {"title": "The model", "notes": "Drag the slider.",
         "keys": [
           {"keys": "Alt+ArrowUp", "label": "Previous slider"},
           {"keys": "Alt+ArrowDown", "label": "Next slider"}
         ]}
      ]
    }
  3. Keep the slide's position in the window title, as <index>/<total> at its start: 3/12 · The model · Lab meeting. The PC reads the title to know which slide is showing. A deck whose title does not start that way gets the first slide's notes and the deck-wide keys only.

presentation.json is a complete example file to start from.

The file

FieldMeaning
version1. Any other value is refused.
jumpOptional. Exactly "number Enter": type the target slide number, then Enter. Other values invalidate the file.
keysOptional. Keys shown on every slide, after the slide's own.
slidesOptional. One entry per slide, in order: the first is slide 1, as in the window title.
slides[i].titleOptional. The slide's title on the phone, one line.
slides[i].notesOptional. Speaker notes; line breaks are kept. They cover the slide's first view (step 0) and the whole slide.
slides[i].step_notesOptional. One note per animation step: entry k (from 0) is the note for step k + 1, shown after the k + 1-th build. A list of strings, line breaks kept; an entry that is not a string, or a slide past the limits, invalidates the file (slides[2].step_notes[1]).
slides[i].keysOptional. This slide's keys.
a key's keysThe key chord, as below.
a key's labelOptional. The button's text; without it the button shows the chord.
a key's guestsOptional. Only the boolean true shares this key with the guest holding the floor. Missing, false, and every non-boolean value mean presenter-only.

Slides past the end of the list have no notes and only the deck-wide keys. Fields not in this table make the file invalid, so a misspelt note is reported instead of silently ignored.

Limits: the file is at most 512 KB of UTF-8, at most 500 slides, a title 200 characters, notes 8000 characters, a chord 40 characters, a label 24 characters, and at most 8 keys in each list. A slide's step_notes have at most 100 entries (the steps cap), and together at most 8000 characters: the same budget as its notes.

Key chords

Modifiers and one key joined by +, in any case: Alt+ArrowUp, shift+n, Ctrl+Shift+PageDown.

  • Modifiers: Ctrl, Alt, Shift.
  • Keys: the letters and digits; Up, Down, Left, Right (also ArrowUp and so on), Home, End, PageUp, PageDown, Space, Enter, Tab, Backspace, Escape. Names are the keyboard names with an underscore (page_up), written either that way or in camel case (PageUp).

Only a fixed list of keys is allowed: Shift with any key above; Alt only with the arrows, Home, End, Page Up and Page Down; Ctrl with those and with Enter (Ctrl+Enter, the usual submit chord). A slide shows at most 8 keys, its own first, then the deck-wide ones. A key outside the list, or past the 8, is left out, and the PC window names it; the rest of the file is still used.

How the PC finds the deck

  • Windows: when a slideshow starts with Chrome, Edge, Brave or Firefox in front (the browser goes full screen), or a browser window, in front or not, shows a title with a position, the PC reads the address in that window's address bar (UI Automation, read only) and reads the deck from its local file or HTTP or HTTPS address. Once a deck is in use, only a browser in front is read for another. It reads again at each slideshow start, so changes to the file or web declaration are picked up then. Position polls do not fetch it again. The deck stays in use, with its slide, while another window (the PC window) is in front; its title still moves the slide. A deck is found in full screen too: with no address bar, the address is the page's own URL, and a window whose address could not be read is read again when its title changes or it leaves full screen.
  • Every platform: Open presentation… in the PC window's Presenter tab picks the deck's HTML file, opens it in the default browser and uses it. Open it again to read changes. Stop using forgets it. On Windows, the verified browser window moves to the presentation screen chosen in PC Settings (the first non-primary screen by default) and enters browser full screen. The app keeps its window and opened address when the address bar disappears in full screen. A failed move or full-screen request leaves the deck open with one notice. On macOS and Linux, browser placement is not supported; move the browser and enter full screen yourself.
  • macOS reading the browser's address is planned; Linux uses Open presentation.

The PC window shows the deck in use and the slide showing, or why its file was not used.

What is read, and what is not

  • Local files (C:/talks/deck/index.html, file:///...) and HTTP or HTTPS addresses are read. Chrome and Edge show a web address without its scheme (127.0.0.1:8111/): such an address is read as HTTP on this computer (localhost, 127.0.0.1, [::1]) and HTTPS for any other host. Network file paths (\\server\share\...) are never read.
  • The declaration must fit within 512 KB of UTF-8, from a file or the web. Each web response has a 5-second whole-read deadline and a 5-second connection timeout. Only status 200 is used; all redirects are refused. Requests send no cookies or credentials and bypass proxies. Addresses containing a username or password are refused.
  • A web declaration resolves against the deck's URL and must stay on the same origin (scheme, host and port) and in the deck's folder or below. Other schemes and encoded traversal or separators are refused. The PC asks only for the address the browser shows and that site's declaration: two bounded GET requests with no credentials, to any host this computer can reach (local services included) when the browser shows one.
  • Only the first 1 MB of the HTML is searched for the link, outside comments. Two such links make the deck invalid.
  • For local files, href must name one plain .json file in the deck's own folder: no folders, no .., no drive or absolute path. The file must not be a link to somewhere else.
  • The file is all or nothing: if anything in it is invalid, no notes and no keys are used, and the PC window says where the problem is (slides[2].notes).
  • Nothing in the deck is run. Keys are pressed only from the list above.

Jump from the phone

When the deck's position is known, tap a slide in the phone's slide list to go there. If "jump": "number Enter" is declared, the PC presses the number's digits then Enter and waits up to 2 seconds for the title to confirm the target. Otherwise, or if that jump is not confirmed, it presses Right or Left one at a time, checking the title after each press. Builds may take extra presses even when the title stays unchanged. Those presses are paced by the title polling interval. Keep the intended browser window in front: these are real keyboard presses, through the same ordered input path as floor keys.

A new jump cancels the old one. Stepping stops after the deck's total plus 32 presses, or when presses leave the title unchanged for 2 seconds. A title that becomes unreadable or changes total also stops further presses. The phone explains the stop; use Next or Back to continue. Timings and the build margin are fixed in the app. Only digits, Enter, Left and Right are used. Stopping use of the deck or disconnecting the phone cancels a jump.

The web deck script still works and supplies live animation steps. A deck can use both: while the script is connected, its slides and notes are the ones shown, and the declared keys stay in the key row.