presio

Attach speaker notes and embedded media (GIF / MP4 / WebM) 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.

Install

#import "@preview/presio:0.2.3": 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)

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

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

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

{
  "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
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.