Universe

Attach speaker notes, embedded media (GIF / MP4 / WebM, YouTube / Vimeo) and HTML animations to PDF slides so they can be presented with the presio.xyz viewer.

presio is framework-agnostic — it works with polylux, touying, or plain Typst pages. It only contributes two functions; layout and slide flow are up to your existing template.

Present the Touying demo Present the polylux demo Present the HTML animation demo Present the workshop demo Present the plain demo

Install

#import "@preview/presio:0.3.0": media, speaker-notes

Requires Typst 0.15 or newer (for the file path type). Users on Typst 0.13–0.14 can pin to @preview/presio:0.1.0, which has a slightly more verbose bytes-based API.

Usage

Speaker notes

= Introduction

Hello world.

#speaker-notes[
  Remember to mention the funding agency before the next slide.
]

A JSON sidecar notes-slide-<N>.json is attached to the PDF. Multiple speaker-notes[…] calls on the same slide are concatenated into a single attachment, in source order.

Embedded media (local file)

#media(path("figures/demo.gif"), width: 60%)

path("…") is Typst 0.15’s file-path type — it resolves relative to the file that constructed it, so the package can read() and image() the target on the caller’s behalf. The bytes are embedded in the PDF via pdf.attach and a placement descriptor JSON is written alongside it.

By default the in-slide preview is image(source). For MP4 / WebM (which Typst can’t render directly) pass an explicit placeholder: image("poster.png"), or placeholder: none to get a dark block.

Embedded media (URL)

#media(
  "https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif",
  width: 40%,
  aspect-ratio: 1,
)

Nothing is attached to the PDF; the viewer fetches the URL at presentation time.

YouTube / Vimeo

URLs from YouTube (youtube.com/watch?v=…, youtu.be/…, youtube.com/embed/…, youtube.com/shorts/…, youtube.com/live/…, youtube-nocookie.com/embed/…, and any subdomain such as m.youtube.com) and Vimeo (vimeo.com/<id>, vimeo.com/video/<id>, player.vimeo.com/video/<id>, vimeo.com/channels/<channel>/<id>, vimeo.com/groups/<group>/videos/<id>) are detected automatically and emitted with kind: "youtube" / kind: "vimeo" plus an extracted video_id the viewer can use to build an iframe embed.

#media("https://www.youtube.com/watch?v=dQw4w9WgXcQ", width: 60%, aspect-ratio: 16/9)
#media("https://vimeo.com/76979871", width: 60%, aspect-ratio: 16/9)

HTML animations

Point media at an .html file and it’s played as an animation: presio runs the page in a sandboxed frame, on a clock it plays, pauses, seeks and keeps in time on every screen — requestAnimationFrame, timers, CSS and Web Animations, SVG animations and <video> all follow it. List the files the page loads in assets; each is attached to the PDF and reached by the page at its path relative to the page.

#media(
  path("orbit/index.html"),
  assets: (path("orbit/js/main.js"), path("orbit/js/planets.js"), path("orbit/css/style.css")),
  width: 70%,
  aspect-ratio: 16/9,
)

Relative URLs work wherever the page uses them: in src / href, in CSS url() and @import, in ES module imports, and in fetch, XHR and src set from script. Absolute URLs (a library from a CDN) load from the network as usual. To give an asset a different URL than its path, pass a dictionary: assets: ("lib/d3.js": path("vendor/d3.v7.min.js")).

By default viewers follow the presenter. sync: "independent" hands the animation to each viewer instead, with its own controls (play / pause, restart, a scrubber when the length is known) and its own clicks and drags. The presenter can switch between the two at any time from the animation’s controls.

#media(path("explorer.html"), sync: "independent", duration: 12, width: 80%)

What the presenter changes on the page reaches viewers following them, and every viewer when the presenter presses Sync. Form fields (sliders, checkboxes, selects, text) come along by themselves. Anything else, the page hands over with presio.sync. get returns JSON-able data, and Presio asks for it a few times a second. set receives a copy of the presenter’s data:

if (window.presio) presio.sync({
  get: () => ({ points }),
  set: (s) => { points = s.points; },
});

Keep it small (it has to fit in 15 KB). The state also survives seeking back, but not a restart.

Presio previews the animation where it can’t run it: slide thumbnails, the next-slide view, and PDFs downloaded from Presio show a frame from near its end (2 s in when it has no set length). Pick another with poster-at: seconds. The PDF Typst writes shows placeholder, as for other media.

The page is sandboxed: its scripts run, but on an opaque origin, with no access to presio, the deck or the viewer’s storage (so localStorage and cookies are unavailable inside it).

HTML export

Compiled with Typst’s (experimental) HTML export, typst compile --features html --format html deck.typ, media puts the real thing on the page: an HTML animation in a sandboxed <iframe> — the same runtime as in presio, so it plays the same, with its controls unless controls: false — a <video>, an image, or a YouTube / Vimeo embed. Local video files are inlined as base64, which takes the compiler about two seconds per megabyte. Note that Typst’s HTML export leaves out anything inside align, so wrap media in align only for PDF output.

media parameters

Parameter Default Notes
source — Either a path (from path("…")) or a http(s):// URL string
name none Override for the attachment filename / MIME sniff. Auto-derived from the path’s filename when omitted.
placeholder auto auto → image(source) for files, dark block for URLs. none → force dark block. Any content → use it.
width auto Length, ratio of the container width, or auto (natural width of placeholder, else container width)
height auto Length, ratio, or auto (derived from placeholder / aspect-ratio / 16:9)
aspect-ratio none Width/height ratio, e.g. 16/9
autoplay true Forwarded to the viewer
loop true Forwarded to the viewer
assets () HTML animations: the files the page loads. An array of paths, or a dictionary from the URL the page uses to a path.
sync "presenter" HTML animations: "presenter" (viewers follow) or "independent" (each viewer plays it). Switchable live.
controls true HTML animations: controls for viewers playing it themselves, and in HTML export. The presenter always has them.
interactive true HTML animations: clicks, drags and hovers reach the page.
duration none HTML animations: length in seconds, for the scrubber and looping. Measured from CSS animations when omitted and those are all it runs.
poster-at none HTML animations: the moment (seconds) Presio uses as its preview in thumbnails, the next-slide view and PDFs downloaded from Presio. Defaults to near the end, or 2 s in when open-ended.

Supported media types

The MIME is sniffed from the extension of the source path’s filename (file mode) or the URL (URL mode):

Extension MIME
.gif image/gif
.mp4 video/mp4
.webm video/webm
.html text/html (an HTML animation)

Sidecar JSON schemas

notes-slide-<N>.json — notes is always an array (one entry per speaker-notes call on that slide, in source order):

{ "slide": "3", "notes": [ "<typst content>", "<typst content>" ] }

media-slide-<N>-<id>.json

Common fields: kind, slide, id, mime, x_pt, y_pt, w_pt, h_pt, autoplay, loop. The remaining fields depend on kind:

kind Extra fields
file filename (PDF attachment name)
url url (direct media URL)
youtube url, video_id
vimeo url, video_id
html filename (the page), sync, controls, interactive, and when given assets ([{ "path", "filename" }], one attachment each), duration and poster_at
{
  "kind": "file",
  "slide": 3,
  "id": "demo_gif",
  "mime": "image/gif",
  "x_pt": 72.0, "y_pt": 120.0, "w_pt": 432.0, "h_pt": 243.0,
  "autoplay": true,
  "loop": true,
  "filename": "media-demo_gif.gif"
}

Examples

A complete deck for each supported workflow lives under examples/. Each folder is self-contained (its own demo.gif) and is compiled to PDF alongside the source.

Framework Source Compiled PDF
Plain Typst examples/plain/example.typ example.pdf
polylux examples/polylux/example.typ example.pdf
HTML animations examples/html-animation/example.typ example.pdf
Workshop (touying, viewers drive) examples/workshop/example.typ example.pdf
touying examples/touying/example.typ example.pdf

Rebuild with typst compile --root . examples/<framework>/example.typ examples/<framework>/example.pdf from the repo root. The --root . flag is required so the file-path sandbox can resolve demo.gif.

License

MIT — see LICENSE.