Skip to content
camaelonPublic

About

Presentation software

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

refract

refract

Turn a small, readable markdown slide deck into RemoteCompose slides you can play in the C++ desktop viewer or the TypeScript player.

slides.md ─► refract.py ─► component JSON (androidx format) ─► json2rc ─► .rc

refract emits the androidx component JSON format and lets the real remote-core library serialize it — Python never touches the wire format, and layout is done by the RemoteCompose engine via components, not pixel math.

Getting started

Nothing to build, and nothing to install into your system. The tools ship in prebuilt/ and run from the checkout.

git clone https://github.com/camaelon/refract          # clone, don't download a zip — see below
cd refract
python3 refract.py --check                             # what this machine has, and what it needs

--check is the whole answer in five lines:

  ok      python         3.13 at /opt/homebrew/opt/python@3.13/bin/python3.13
  ok      json2rc        …/prebuilt/json2rc/bin/json2rc  (6 jars)
  ok      java           21 at /usr/bin/java
  ok      refractplayer  …/prebuilt/refractplayer
  ok      graphviz       /opt/homebrew/bin/dot

Whatever it calls MISSING, it also tells you how to fix. absent marks something you can do without. Then:

python3 refract.py examples/deck               # writes examples/deck/out/*.rc
prebuilt/refractplayer examples/deck           # present it (→ steps, Tab jumps, H for keys)
prebuilt/refractplayer                         # or start from the deck picker

Hand the player a deck folder and it builds the deck if it must. Name nothing and it opens a start window listing the decks you opened before, beside a New deck… that writes you a starter slides.md.

Two tutorials, both building the same small talk — the one in examples/tutorial/, so you can open what you are reading about:

  • A deck from the command line — slides.md, refract.py, and the pieces a talk needs: sections, images, notes, code, panes, a theme.
  • Authoring in the player — the same talk written, reordered and presented in refractplayer's own windows, with screenshots of each.

Changing refract itself? Architecture below, and docs/architecture-editor.md for the slide editor, which is the largest piece.

What it needs

Two things, and only two, since the checkout holds the rest:

Python 3.11+ refract.py is Python, and it reads settings.toml with tomllib, which arrived in 3.11. macOS ships 3.9, so: brew install python. Put it ahead of /usr/bin on PATH — the player looks python3 up itself for its editing tools, and where that finds Apple's, refract works from the terminal and fails quietly inside the editor. --check reports both.
A JVM 21+ json2rc turns each slide's JSON into .rc, and it is a Java program: brew install openjdk@21. Only that one step wants it. --json-only stops before it, and playing a deck someone has already built never reaches it.

Optional: graphviz (brew install graphviz) for graph slides, and — only for turning a recorded narration into captions — the transcriber, which the player installs into its own environment on request: prebuilt/refractplayer --install-transcriber. Nothing else.

The prebuilt binaries

prebuilt/refractplayer the player, and the deck editor
prebuilt/json2rc JSON → .rc compiler (a JVM launcher, not a native binary)
prebuilt/rcviewer the standalone viewer, and refract's fallback exporter
prebuilt/rc2image headless .rc → PNG, used for freeze snapshots

The three native ones want arm64 and macOS 11 or newer, and they link nothing outside macOS's own frameworks: no Homebrew, no DYLD_*, nothing to install. Check for yourself with otool -L prebuilt/refractplayer — every line it prints starts /usr/lib or /System/Library. An Intel Mac needs them built again from source (player/README.md); Rosetta translates the other way and cannot help.

They can go on your PATH — a symlink is enough:

ln -s "$PWD/prebuilt/refractplayer" /usr/local/bin/refractplayer

The player follows the symlink back to the checkout to find its own Python tools, so editing, reordering and rebuilding go on working from anywhere. Copy the binary out of prebuilt/ rather than linking it and you lose them: it still plays a deck, but the deck view, the editor and the build panel have nothing left to call.

Clone it, don't download a zip. A file that arrives through a browser carries macOS's quarantine flag, and Gatekeeper then refuses to run these, which carry an ad-hoc signature rather than a notarized one. git clone sets no such flag. If you did download an archive:

xattr -dr com.apple.quarantine prebuilt

To update, git pull. The repository holds the binaries, so they come with it.

Rebuilding them

Only if you are changing the engine, or building for an Intel Mac:

player/build.sh                          # refractplayer, into prebuilt/
(cd json2rc && ./gradlew installDist)    # json2rc

# rcviewer and rc2image are upstream's, built from the players/cpp tree:
cmake -B build -S ../remotecompose-experiments/players/cpp \
      -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0
cmake --build build -j
cp build/apps/viewer/rcviewer build/tools/rc2image/rc2image prebuilt/
codesign -f -s - prebuilt/rcviewer prebuilt/rc2image

player/build.sh looks for the RemoteCompose players/cpp tree beside this repository, or takes RCX_DIR=/path/to/players/cpp. The first build fetches Skia, which is a large download. player/CMakeLists.txt sets the deployment target before project(); leave it alone unless you mean to raise the oldest macOS the result will run on.

refractplayer is the deck player, and it is where a deck is presented and edited:

presenter window P clock, timer, notes, the next slide, pace against a rehearsal or :: section duration=
navigator Tab the deck as a list, to jump somewhere
deck view V every slide at once; drag to reorder, fold sections, add and delete
slide editor E the markdown behind a slide, the whole deck, or settings.toml; < offers the deck's assets
build panel M refract's options, and a Rebuild button
captions C the recorded narration, word by word
assets I what is in includes/, which slides use it, and what nothing does

All seven are in the Window menu too (cmd+1…7), with a tick beside whatever is open.

The middle three write back to slides.md and re-run refract, so a deck can be rearranged and rewritten without leaving the player. It also records and replays a rehearsal, transcribes the narration, and exports to PDF (--pdf talk.pdf), PNGs (--images dir/), a movie with the narration as its soundtrack (--video talk.mp4) or a self-contained web page (--web dir/). See player/README.md.

Two players on two machines can be kept on the same slide, blank screen and laser dot: one hosts with --sync-serve, the others join with --sync host, either of them driving; --sync-key word on each keeps the rest of the room out.

rcviewer is the plain RemoteCompose viewer; it shares the same playback and export code, and adds --screenshot / --frames for single-file headless capture.

Deck layout on disk

<deck>/
  slides.md          # the deck
  settings.toml      # optional per-deck settings (colors, size, transitions, shader…)
  shader.sksl        # optional background shader referenced from settings.toml
  includes/          # images, sub-decks, .rc / .json resources
  out/               # generated .rc files           (created)
  out/deck.json      # deck outline + provenance      (created)
  out/.refract-cache.json  # what the last build produced (incremental builds)
  out/.refract-history.json # the last 30 edits, for undo in the deck view
  out/.refract-session.json # which panels were open, and where  (refractplayer)
  out/notes.md       # speaker notes                 (when the deck has any)
  out/timing.json    # rehearsal trace               (refractplayer --record)
  out/json/          # generated .json documents     (only with --json)
  voice/             # one NN.wav per slide          (refractplayer --record-audio)
  voice/index.json   # which wav belongs to which slide; moved by the tools that reorder
  voice/NN.txt       # its transcript                (refractplayer --transcribe)
  voice/NN.words.json# per-word caption timings      (refractplayer --transcribe)

Markdown grammar

:: title : Nico
# refract
*Markdown to RemoteCompose*
<logo.png>

---

:: content [2:3] : Nico
# Two panes
- a point
  - a sub-point
- another

+++

```dot
digraph G { rankdir=LR; A -> B -> C }

- `---` on its own line separates slides (one `.rc` each).
- `:: <type> [flags] [@author] [: <speaker>] [ratio] [key=value…]` right after the
  separator sets slide metadata:
  - `@author` attributes the slide to an author from `[authors]` — the slide takes
    that author's colour as its accent and shows their name in the chrome (unless
    `[chrome] author = false`, which keeps names off the slides; the presenter still
    colours its progress bar by speaker). On an
    `include` it attributes every slide it pulls in (a slide's own `@author` wins).
  - `<speaker>` (after `:`) selects an accent colour from `[speakers]`.
  - `[ratio]` sets pane widths (see Panes); `key=value` are per-slide overrides
    (`bg`, `accent`, `shader=none`, `transition=push`…); bare-word `flags` include
    `fragment` (see Fragments).
  - `duration=` on a **`:: section`** says how long that part of the talk should take
    (`12m`, `90s`, `1h30m`, or a bare `45` for minutes). On an **`:: include`** it plans the
    whole included sub-deck as one part — `:: include : capabilities duration=8m` — named
    after its first slide (or, if that slide is a section, simply that section's duration).
    The player adds them up for the talk clock and paces the run against them — see
    [Planning a talk](player/README.md#planning-a-talk-without-rehearsing-it).
- The first `# heading` is the title.
- An `*italic*` line right under the title is a **subtitle** (accent colour).
- Inline **`**bold**`**, *`*italic*`* and `` `code` `` work inside any text/bullet; a
  styled line wraps to the available width (word by word) and keeps a shared text
  **baseline** across mixed styles.
- Author names from `[authors]` are tinted with their colour wherever they appear in
  body text (e.g. the title-slide byline).
- A `???` line starts **speaker notes** — everything after it, to the slide's end, is
  presenter notes (`??? text` puts the first line on the marker itself). They're written to
  `out/notes.md` and to a per-slide `out/<slide>.rc.notes` sidecar, which the player shows in
  the presenter window and the PDF export lays out in a panel **below** the slide (the page
  grows taller so notes never overlap the slide).
- A `===` line **stacks** the slide — see [Stacked sections](#stacked-sections).
- Everything else is content **blocks**, in order.

### Slide types (`<type>`)

| Type      | Layout                                                        |
|-----------|---------------------------------------------------------------|
| `title`   | large title centered; an image renders above it (logo size)   |
| `section` | title centered, auto-numbered (the number is tinted with `[theme] primary`); section slides default to a slide-up transition |
| `content` | default — title at top, content below, left-aligned           |
| `split`   | two columns from `+++`, laid out row-first: the **right** column runs full-height (from the top, past the title) while the **title** is confined to the **left** column's width; `[ratio]` sets the split (default 1:1) |
| `max`     | near-fullscreen — small margin so the content is maximised, a smaller title (if any), chrome still shown; great for a full-bleed graph, image, video or web page |
| `include` | splice a sub-deck from `includes/<param>/slides.md` (or a `<section … will go there>` placeholder) |
| `outline` | replaced by a synthesized outline of the deck's `section` slides — numbers in the primary colour beside each section title |
| `agenda`  | like `outline` but a plainer numbered bullet list |

Mark a slide `skip` (`:: content skip`, or `skip=true`) to drop it from the deck entirely —
it's removed before numbering, so it consumes no section number, agenda entry, or page.
Use `skip=false` to keep one while leaving the flag in place.

### Content blocks

| Block         | Markdown                                                       |
|---------------|---------------------------------------------------------------|
| text          | plain paragraphs                                              |
| subtitle      | `*italic*` line directly under the title                     |
| bullet list   | `- item`, indent two spaces per sub-level; marker shape/fill/colour and per-sub-level font set by `[bullet]` (see settings) |
| table         | markdown pipe table `\| a \| b \|` (first row = header)      |
| code          | fenced ```` ``` ```` block — **syntax-highlighted** (kotlin, java, json) |
| graph         | fenced ```` ```dot ```` / `neato` / `fdp` / `circo` … — laid out by graphviz, drawn by refract (clusters, dashed/dotted/coloured edges, per-node colours, neon node glow) |
| chart         | fenced ```` ```chart-bar ```` / `chart-line` / `chart-pie` with `label: value` lines |
| image         | `<name.png>` (`.jpg/.gif/.webp`) — embedded **inline** in the `.rc`; an animated `.gif` plays in place (every frame is embedded, the viewer picks the frame by document time) |
| code file     | `<name.kt>` (`.java/.py/.ts`) — the file rendered as a highlighted code block |
| video         | `<name.mp4>` (`.mov/.m4v`) — **embedded** in the page (a native custom component the viewer plays in place); a lone video with no title fills the slide. `crop` trims the frame (e.g. black bars). |
| camera        | `<camera>` — the presenting machine's **camera feed**, drawn live into the box at playback (a native custom component, like video); `<camera:FaceTime>` names the device. Frames, crops, clips and captions like a video: `<camera \| ratio=1:1 clip=circle mirror>` is a speaker in a circle. Exports show a marked box. |
| json include  | `<name.json>` — a RemoteCompose JSON document embedded **live** as components |
| rc include    | `<name.rc>` — a prebuilt RemoteCompose doc embedded **live** in the slide: spliced flat if a sibling `.json` exists, else painted as a nested sub-document (its own id space, animates on its own, and receives mouse drags — e.g. rotate a 3D plot). A lone `.rc` (no title) is a whole-slide passthrough. Scaling via `[embed] fit`. The asset is copied to `out/media/` (not listed as a slide). |
| web link      | `<https://url>` (optional `\| label`) — an interactive web page **embedded in the page** (a native custom component, like video); the viewer places a live, clickable browser over its box. `<file://demos/app/index.html>` is a page **in the deck**: a relative path is looked for beside `slides.md`, then in `includes/` (and in the main deck's, for a sub-deck), so a demo travels with the deck instead of being nailed to one machine. `file:///…` is still an absolute path. |

Includes are resolved from `includes/`; the extension may be omitted (`<logo>`
finds `logo.png`). Speaker accent comes from `[speakers]` (below).

**Per-include options** go after a `|`: `<name | key=value …>` (space-separated). For video
and rc/json embeds:
- `crop=l,t,r,b` — a source rectangle as fractions 0–1 (default full); shows only that region,
  scaled to fill the box. Handy to remove black bars around a portrait recording, e.g.
  `<phone.mp4 | crop=0.28,0,0.72,1>`, or to zoom into part of an embedded doc.
- `fit=fit|fill|native` — override the `[embed] fit` for this embed (a camera fills by default).
- `clip=roundrect|circle|<px>|none` — the shape of the box: rounded corners (`roundrect`:
  `[image] roundrect_radius`, else `[image] corner_radius`, else 28 px), fully round (a circle,
  with `ratio=1:1`), a corner radius in pixels, or square corners. With no `clip` the box takes
  `[image] corner_radius` (0 — square — unless set, or 28 with `rounded = true`). Works on
  video, rc/json embeds, the camera and images.
- `mirror` — flip the camera left-right, the way a speaker expects to see themselves.
  `device=…` picks a camera by a substring of its name or by index (the same as `<camera:…>`).
- `width=` / `height=` — size the box outright in px, as for an image, instead of filling
  what is left; one of them with `ratio=` gives the other. `align=start|center|end` places a
  sized box in its row. So a portrait slot takes the camera as it took the photograph:
  `<camera | width=190.66 height=190.66 clip=circle zoom=1.6 mirror>`.
- `zoom=N` — show the middle 1/N of the frame: a face, closer, without moving the camera.
  `focus=x,y` (fractions 0–1, default the centre) says what to zoom on; a `crop` composes
  with it (the zoom happens inside the crop).

**A camera in the template.** A theme preset (`theme/<name>.toml`, used with `:: as: name`)
can carry the camera itself, so every slide on that template shows the speaker at the same
spot without a line of markdown each: a `[camera]` table with `x`/`y` (insets from the
`anchor` corner — `top-left` by default, or `top-right`, `bottom-left`, `bottom-right` —
in slide px), `width`/`height`, and any of `clip`, `zoom`, `focus`, `crop`, `mirror`,
`fit`, `device`. The badge is layered over the content, above the chrome, on every slide of
that template — title and section slides included. A slide can drop it with `camera=off`
in its metadata, or re-place it: `:: as: hero camera="x=40 y=40 width=240 anchor=bottom-right"`
(the same option grammar, quoted). A `[camera]` table in `settings.toml` does the same for
the whole deck. Exports draw the marked "camera" plate where the badge goes.

```toml
# theme/speaker_live.toml — the speaker card with the speaker live
type = "content"
bg_doc = "bg_hero.json"

[camera]
x = 957.55
y = 197.54
width = 505.59
clip = "circle"
zoom = 1.4
focus = "0.5,0.45"
mirror = true
  • title=… — a centred caption drawn below the embed (the embed shrinks to make room). Quote it for multiple words: <widget.rc | fit=fit title="Launcher Widget">. Works on video, rc/json embeds and images.
  • stagger — reveal this embed on its own step. A slide with N stagger embeds expands into N+1 generated slides: the first shows none of them, each later slide reveals one more (the newest fades in) while already-revealed embeds stay put and not-yet-revealed ones sit invisible so the layout never shifts. Great for building up a grid of demos one at a time.
  • start=T (video) — begin playback at T instead of the first frame, and loop back to T. Seconds or a timestamp: start=12.5, start=1:23.
  • still=T (video) — show the clip's frame at T, frozen; nothing plays.
  • once (or loop=0) (video) — play through once, from start, and hold on the last frame. Videos loop by default.
  • zooms="T@x,y,z; T@x,y,z…" (video) — zoom into the clip as it plays. Each keyframe is a clip time (seconds or m:ss), the centre x,y as fractions of the frame (of the crop, when one is set) and a zoom factor z. Before the first keyframe the whole frame shows; at each one the view eases, snappily, from wherever it is to the new centre and zoom (about half a second); z = 1 zooms back out, and the view never leaves the frame. A still/cue frame is framed as the playing clip is at that time. <demo.mov | zooms="0:05@0.7,0.3,2.5; 0:12@0.5,0.5,1">.
  • Zooming images and documents. zooms= and zoom=T@x,y,z work on images and embedded .rc/.json documents too, with T counted from when the slide opened (@x,y,z alone is 0): <photo.png | zooms="0.5@0.75,0.55,2.5; 2@0.3,0.3,2"> drifts in and across. A plain zoom=2 focus=0.3,0.2 on an image shows that view from the start. Consecutive slides of the same image or document with zoom=@x,y,z chain like a clip does: each slide eases from the previous slide's view to its own. An image's zoom is built into the slide (it works the same in every player and export); a document's is applied by the player's document host.
  • until=T (video) — play from start to T once and hold there.
  • A walk through a clip, one slide per zoom. Consecutive slides on the same clip, the later ones each with a single keyframe zoom=T@x,y,z, are chained: each slide starts at its own time, plays until the next slide's time and holds there, and eases from the previous slide's view to its own — so advancing moves the zoom on and lets the clip carry on from where it paused (advance early and it skips ahead to the next slide's time). The first slide starts at its start (or its own keyframe); the last plays on to the end, looping or once. The slides after the first render like reveal steps: only the clip and the zoom move.
    <demo.mov | zoom=0:05@0.7,0.3,2.5>
    ---
    <demo.mov | zoom=0:12@0.2,0.6,3>
    ---
    <demo.mov | zoom=0:20@0.5,0.5,1 once>
    
    Or let a keyframe list do it: zooms="…" steps expands the slide into an opening slide (the clip from its start to the first keyframe) and one slide per keyframe, chained the same way.
  • cue / cue=T (video) — put a still slide in front: the slide expands into two, the first showing the clip frozen at T (bare cue: where start is, else the first frame), the second the slide itself with the clip playing. Advancing from the first starts the video, so you can switch to a demo and talk over it before it runs: <demo.mov | start=0:12 cue>. The playing slide doesn't re-animate the rest of the page; only the video starts. A video that is alone on its slide normally plays as the file itself; with any of these options it is embedded instead, since a bare movie file can't carry them.
  • events="…" (document) — a touch script played on the embedded document, so an interactive demo runs itself: <stopwatch.rc | events="1@click(588,542) wait(1.5) click(312,542)">. Actions are click(x,y) (press, release, click), touchdown(x,y), touchup(x,y) (a release, which also clicks) and drag(x,y), in the document's own coordinates. T@ puts an action at T seconds; one without follows the step before it, and wait(s) moves on. The script runs on the document's clock from the moment the slide opens and loops (its length is its last moment, a trailing wait included) unless the include says once. Each touch shows as a fading fingertip, so the audience sees what is pressed.
  • frame=<name> (video, document, image, camera) — show it inside a device frame the theme defines. A [frames.<name>] table in settings.toml names the frame image and three things in that image's own pixels: bounds, the device (fitted to the box, so the box takes its aspect), screen, where the content goes (drawn under the frame, clipped to radius), and optionally fit (fill, the default, covers the screen; fit letterboxes) and screen_color:
    [frames.android]
    image  = "android-case-edges.png"
    bounds = [1554, 149, 2439, 2012]
    screen = [1595, 189, 2391, 1970]
    radius = 103
    <demo.mp4 | frame=android>. width=/height= size the device, as they size any embed.

A crop/fit on a .json or .rc include frames it: instead of splicing it flat into the slide (which re-lays-it-out to fill), refract embeds it as a nested document at its own design size — so the crop rectangle and scale are well-defined (a .json is compiled to out/media/<name>.rc for this). Without crop/fit, includes splice flat as before.

Panes

Split a slide with +++; a ratio in the metadata sets the pane widths (height is shared): :: content [2:3], :: [1:1], :: [2:2:4] — one number per pane.

The split slide type reuses the same +++ split but lays it out row-first — the right column runs full-height past the title, and the title is confined to the left column:

:: split [3:2]
# Left title
- a point
+++
```kotlin
fun rightColumn() { }

### Stacked sections

`+++` splits a slide across; **`===`** (three or more `=`) splits it **down**. Each stacked
section is parsed like a mini-slide — its own `::` type line, its own `# title`, its own
content — and they render one above the next:

```markdown
:: content
# Before and after

- the old way, and what it cost us

===

<before.png>
+++
<after.png>

Heights are not shared evenly. A text section takes its natural height; the media sections (panes, images, embeds, graphs, charts, videos) divide whatever is left. So a couple of bullets above two full-height image columns give the images the rest of the slide, not half of it.

A section can instead be given an exact height: height= on its own :: line (:: as: dark_b height=245), or height = 245 in the theme it uses. The first section takes the slide's theme; a later one, the theme on its own :: as: line; a height= written on the line wins over the theme's.

Transitions & "magic move"

--transitions (or [transition] enabled = true) animates each slide in from the previous one on load. Styles ([transition] style or per-slide transition=):

  • fade (default) — a StateLayout crossfade.
  • push / slide — the previous slide slides out while the new one slides in (horizontal). Use slide-up (push-up) for a vertical move — the previous slide travels up and off while the new one rises from the bottom.
  • magic move (automatic between two consecutive graph slides) — nodes matched by their dot identifier glide/resize to their new positions (snappy ease-out), edges morph along (resampled so their splines interpolate), and unmatched elements fade.

:: same continues the previous slide: it inherits that slide's type/layout and renders it again with only the changed content animated (new blocks fade/slide in, removed ones collapse out, matched content stays put) — so a :: same after a :: split lays out as the same split, letting you add an element to one panel while everything else holds still.

The first slide has no in-transition (nothing to come from) — it renders statically and its out is animated by the next slide. So :: section transition=slide-up on the slide after the title makes the title glide up as that slide rises in.

Push/slide speed is the slide time in seconds — set [transition] duration globally or transition_duration= per slide (larger = slower), e.g. :: section transition=slide-up transition_duration=0.9.

Per-slide-type defaults live in [transition.<type>], so every slide of a type shares a transition without repeating it. Section slides default to sliding up from below via:

[transition.section]
style    = "slide-up"
duration = 0.9
fx       = true          # draw the [shader.transition] overlay during the transition

Precedence for each knob: per-slide transition*= override → [transition.<type>] → [transition] → built-in default.

python3 refract.py examples/deck --transitions

Content reveal (animate content in)

How bullets and content blocks appear when a slide loads, set by [reveal] mode and overridable per slide with reveal=:

  • immediate (default) — everything appears at once.
  • stagger — items cascade in (fade + a small upward slide, snappy ease-out), each a little after the last. Timing via [reveal] delay / stagger / duration / rise.
:: content reveal=stagger
# Cascades in
- first
- second
- third

The reveal runs on load (it also plays as a slide transitions in); the outgoing slide of a transition is never re-revealed.

Stepped reveal — one .rc per step (progressive)

To reveal bullets across separate slides (press the next key → the next bullet appears), enable steps. refract expands the slide into one .rc per cumulative top-level bullet; each step after the first animates just the newly-revealed bullet in (via the :: same diff).

  • Per slide: the fragment / steps flag turns it on; nosteps (or steps=off) turns it off.
  • Globally: [reveal] steps = true makes every bullet slide stepped by default.
:: content steps
# Build it up
- first
- second
- third

Overflowing content — autosize & scroll

When a slide's text is taller than the content area, there are three ways to handle it:

1. Autosize (default). The body font shrinks just enough that the content fits — never enlarges, so slides that already fit are untouched. It applies per content column (including each side of a :: split and each pane), and it won't shrink past a floor (default 0.5×; content that still overflows wants scrolling instead). Tune or disable it:

[layout]
autosize     = true    # deck-wide on/off
autosize_min = 0.5     # smallest allowed fraction of the base body size
:: content autosize=false    # opt a single slide out

2. Scroll pages (scroll = N / scroll = auto). Instead of shrinking, keep the text full-size and split it across generated slides that scroll the content window. Pressing next scrolls down (animated). auto makes as many pages as needed; an explicit count spreads the content evenly across exactly that many pages. On a :: split slide it scrolls the first column (the text) while the other column stays fixed.

:: content scroll=auto
# Long API reference
… lots of text …

3. Scroll-aware :: same. Tag several :: same slides with a manual scroll= offset (in viewport fractions — 1 = one screenful down) to step through overflowing content yourself, so the content scrolls between slides while the shared-element diff animates.

:: same scroll=0
# Spec walk-through
… long content …
---
:: same scroll=1        # same content, scrolled one screen down
# Spec walk-through
… long content …

settings.toml

[slide]
width     = 1600
height    = 900
title_gap = 44                  # vertical gap between title and content

[theme]
preset          = "dark"        # dark | light | midnight | warm | mono (applied first)
background      = "#FF141A2E"
title_color     = "#FFFFFFFF"
body_color      = "#FFE6EEF6"
accent          = "#FF4FC3F7"   # subtitles, table headers, emphasis (overridable per slide)
primary         = "#FF4FC3F7"   # deck brand colour (section numbers, outline); stable across
                                # slides. Defaults to accent if unset.
table_bg        = "#1AFFFFFF"
table_header_bg = "#22FFFFFF"

[chrome]                        # optional slide chrome (never shown on the title slide)
page     = true                 # "n / total" page number
footer   = "RemoteCompose · 2026"
progress = true                 # bottom progress bar: a connect-the-dots rail — a thin line
                                # (filled up to the current slide, faint beyond) with marks
                                # sitting ON it, the line leaving a gap around each mark
section_marks  = true           # draw the marks
mark_at        = "speaker"      # "speaker" = a mark at each speaker change (default);
                                # "section" = a mark at each `:: section` start
mark_shape     = "circle"       # circle | square | four | quad | diamond | asanoha | hline | vline
mark_filled    = true           # filled shape, or false for an outline
progress_color = "current"      # "current" = whole line in the current slide's accent;
                                # "section" = coloured by who's speaking (changes at include
                                # boundaries, so each speaker's stretch reads in their colour)
color    = "#66FFFFFF"

[bullet]                        # bullet-point marker
shape  = "circle"               # circle | square | four (diamond crest) | quad (square crest)
                                # | diamond | asanoha (hemp-leaf) | hline | vline
filled = true                   # filled shape, or false for an outline
color  = "#FF4FC3F7"            # the marker's own colour (default: the deck primary accent)
# Sub-levels (indented bullets, level >= 1) may differ from the top level:
sub_shape  = "hline"            # marker shape for sub-bullets ("" = same as shape)
sub_font   = "Avenir Next"      # text font family for sub-bullets ("" = same as body)
sub_weight = 300                # text weight for sub-bullets (thinner here)
sub_color  = "#FFB8C2D0"        # text colour for sub-bullets (light grey)

# Per-author colours. A slide/include marked "@Nico" takes that colour as its accent
# and shows the name in the chrome; names are also tinted wherever they appear in text.
# Full and short forms can both be listed (matched whole-word, longest first).
[authors]
"Nicolas Roard" = "#FF5CC8FF"
"Nico"          = "#FF5CC8FF"
"John Hoford"   = "#FFF6A96B"
"John"          = "#FFF6A96B"

# Per-speaker accent (":: content : Nico" → this colour for that slide).
[speakers]
Nico = "#FF4FC3F7"
John = "#FF81C995"
Yuri = "#FFFFB74D"

# Font sizes (px). Aliases: title (title-slide) / section / heading (content title) /
# body (content) / subtitle / table / code. Direct keys also work (content_body…).
# Named system font families + weights: title_* for headings, body_* for everything
# else, code_family for code. Resolved by the OS font manager (macOS CoreText / Linux
# fontconfig), so any installed family works.
[font]
heading  = 76
body     = 44
subtitle = 48
table    = 40
title_family = "Futura"         # headings
title_weight = 500              # 100–900 (Medium here)
body_family  = "Avenir Next"    # body / bullets / subtitle / tables
body_weight  = 400
code_family  = "SF Mono"        # code blocks & spans

[image]
corner_radius = 28              # round embedded images

[embed]                         # prebuilt `.rc` sub-documents (<name.rc>)
fit = "fit"                     # fit (aspect, centred) | fill (cover) | native (1:1)

[code]
background    = "#FF1E1E1E"
foreground    = "#FFD4D4D4"
font_size     = 28
corner_radius = 18              # round the code panel
[code.syntax]                   # any subset; rest use defaults
keyword = "#FFC586C0"
type    = "#FF4EC9B0"
string  = "#FFCE9178"
number  = "#FFB5CEA8"
comment = "#FF6A9955"
key     = "#FF9CDCFE"           # JSON property names
literal = "#FF569CD6"           # true / false / null

[graph]
node_fill   = "#FF1B2A3D"
node_stroke = "#FF4FC3F7"
node_text   = "#FFE6EEF6"
edge        = "#FF89A7C2"

[shader]                        # animated background (SkSL)
file = "shader.sksl"            # or source = """...SkSL..."""
[shader.title]                  # optional per-slide-type override
file = "title.sksl"

[transition]
enabled = false                 # same as --transitions
style   = "fade"                # fade | push | slide | slide-left | slide-up | push-up
duration = 0.45                 # push/slide time in seconds (larger = slower)
[transition.section]            # per-slide-type defaults (any [transition.<type>])
style    = "slide-up"           # section slides rise up from below…
duration = 0.9
fx       = true                 # …with the [shader.transition] overlay on

[reveal]                        # how content appears on a slide
mode     = "immediate"          # immediate | stagger (cascade bullets/blocks in)
delay    = 0.0                  # seconds before the first item animates
stagger  = 0.12                 # seconds between items
duration = 0.32                 # per-item animation time
rise     = 26                   # px each item slides up as it fades in
steps    = false                # also split bullet slides into one .rc per step

Precedence: CLI flag > settings.toml > built-in default. Any theme colour / shader / accent can also be overridden per slide via key=value metadata (e.g. :: content bg=#FF101820 accent=#FFE8955A shader=none). Nudge one slide's margins with pad_left= / pad_top= / pad_right= / pad_bottom= (px, added to the slide type's base margin), or pad= for all four — e.g. :: outline pad_left=160 to indent an outline.

align= / valign= set the slide's own horizontal / vertical alignment, and both the title and the content follow them. A heading level can range itself, whatever the slide does, with align in its [heading.<N>] table (left / center / right, or start / end) — a left-ranged title over centred content, say:

align  = "center"               # the content centres
valign = "center"

[heading.1]
align    = "left"               # …the title alone ranges left
pad_left = 40                   # and sits 40px in from the margin

Per slide that is h1_align=left (h2_align= … h6_align= for subheadings), next to the h1_pad_left= / h1_size= / h1_color= overrides that already exist.

The space under the slide title is title_gap, or gap in [heading.1] when that is set (h1_gap= per slide) — the title is the level-1 heading, and its own table is the more specific setting.

Background shaders

A slide background can be an animated SkSL shader (iResolution, iTime uniforms; iTime is animTime, so it animates). It's drawn full-slide behind transparent content. Different types can use different shaders via [shader.<type>] (title / section / content), e.g. give title/section slides their own backdrop:

[shader.title]
file = "dotgrid.sksl"           # e.g. a dot grid lit by a slowly-drifting glow
[shader.section]
file = "dotgrid.sksl"

examples/deck/dotgrid.sksl is such a backdrop — a grid of dots with a soft light that orbits over time, brightening different dots as it moves.

A shader can also sit behind just the title element of a content slide (on top of the slide's own background), giving the heading its own animated band:

[title]
shader = "title-dots.sksl"

The band is larger than the heading, so make the shader transparent (premultiplied half4) and fade it toward the edges — it then composites over the slide background and attenuates around the title instead of looking clipped. examples/deck/title-dots.sksl does this (the transparent, edge-fading sibling of the full-slide dotgrid.sksl). This applies to content/max slides; title & section slides use their full-slide [shader.<type>] instead.

A transition overlay shader ([shader.transition]) is drawn on top of the slide only while a transition plays. In addition to iResolution/iTime it receives an iProgress uniform (the transition's 0→1 progress), so the effect can envelope itself to nothing at the start and end. Return a premultiplied half4 (it composites over the slide). The bundled example (examples/deck/transition.sksl) drifts light dots up from the bottom that fade out quickly. It is opt-in per slide — add transition_fx=on to the metadata of the slide whose transition should show it (e.g. :: section transition=slide-up transition_fx=on).

[shader]
file = "shader.sksl"            # background, all slides
[shader.transition]
file = "transition.sksl"        # overlay, during transitions only (gets iProgress)

Embedded video & custom components

The C++ player supports RemoteCompose custom components (LAYOUT_CUSTOM, op 93): a leaf that the core lays out like any component, then delegates drawing to a host (CustomComponentHost) keyed by a config string. This keeps the core platform-agnostic while an app supplies renderers for things Skia alone can't do.

The viewer ships two hosts, both keyed off the config string:

  • video (config: "video:<file>", AVFoundation) — <name.mp4> plays in place, aspect-fit, looping. The file is copied next to the slides and referenced by name. A lone video with no title fills the whole slide instead.
  • web (config: "web:<url>", WKWebView) — <https://url> embeds a live, clickable browser positioned over the component's box; it follows layout and transitions and supports file-open dialogs. The host also keeps a snapshot of the page, refreshed twice a second, and draws it into the slide under the live view and into the off-screen stills: a native view is in neither the window's pixels nor a still, so without it the presenter's preview and the deck view's cards would show a hole where the demo is. An export, which never loads a page, keeps the dashed frame that names it.
  • camera (config: "camera:<device>#fit=…&crop=…&mirror=1", AVFoundation) — <camera> draws the machine's camera into the box: the speaker beside their slides, in whatever frame the layout gives it (the box's clip is the core's, so a clip=circle box is a circle of face). One capture session per device, started the first time a slide draws it and stopped by itself once no slide has drawn it for a few seconds, so the camera light is not on for the whole talk. macOS asks for camera access the first time; a refused camera (or one that is not there) leaves a dark plate where it would be. The web export asks the browser for the viewer's camera instead (getUserMedia).
# Live demo
Watch it run:

<demo.mp4>

# The Spec
<https://example.dev/spec | Reference>

# Q&A
<camera | ratio=1:1 clip=circle mirror title="you">

Custom components need the ANDROIDX+EXPERIMENTAL profile, which refract sets automatically. (macOS only for now — other platforms draw nothing; and PDF/screenshot export doesn't run the hosts, so embedded video/web are blank in exports.)

CLI

python3 refract.py <deck> [options]
  --width / --height     slide size (default 1600×900 or settings.toml)
  --transitions          crossfade / push / graph magic move between slides
  --debug                1px red outline on every component
  --watch                regenerate on slides.md / settings / includes changes
  --pdf [PATH]           export the deck to a PDF (default <deck>/out/deck.pdf)
  --images [DIR]         export each slide to a PNG (default <deck>/out/images/)
  --video [PATH]         play the slides into a movie with their narration (default <deck>/out/deck.mp4)
  --from N / --to N      the movie's first and last slide, 1-based (default: the whole deck)
  --fps F                movie frame rate (default 30)
  --dwell S              seconds a slide with no narration stays up in the movie (default 4)
  --captions             with --video: a caption line under the slides, from the transcripts
  --shrink-camera HEIGHT re-encode the camera takes in <deck>/voice to this height in px
  --web [DIR]            write a self-contained web site that plays the deck (default <deck>/web)
  --slides SPEC          the slides an export takes, 1-based: "3-12, 20", "7-" to the end (default: all)
  --json                 keep the intermediate JSON in out/json/ (default: discard)
  --force                rebuild every slide, ignoring the incremental build cache
  --json-only            emit JSON only; do not run json2rc
  --json2rc PATH         explicit json2rc launcher (default: auto-detect prebuilt)

Incremental builds

Builds are incremental: a slide whose output is already up to date is left alone, and only what changed goes through json2rc. Rebuilding an untouched deck does no compilation at all.

What is fingerprinted is the generated JSON document, not the markdown. That document is the entire input to json2rc, so an unchanged one means an unchanged .rc — and nothing has to reason about which markdown edit reaches which slide. Several things fall out of that:

  • Editing one slide rebuilds that slide. With --transitions it also rebuilds the next one, whose document embeds it.
  • Editing an image rebuilds the slides that embed it — by content, so a touch or a fresh checkout does not.
  • Reordering rebuilds everything from the move onwards. The page number and progress bar are drawn into each document, so a slide that only changed position is not the same slide. That is the case a cache keyed on the source text would get wrong.
  • A different json2rc throws the whole cache away.

The record lives in <deck>/out/.refract-cache.json, and it is only ever an optimisation: delete it, or pass --force, and the build is exactly what it always was. Files a build no longer claims — a renamed or deleted slide's .rc — are swept at the end, so nothing stale is left for the player to pick up.

Speaker notes (everything after a ??? line) are written to <deck>/out/notes.md and to a per-slide <deck>/out/<slide>.rc.notes sidecar. refractplayer shows them in the presenter window; the PDF export puts them in a panel below each slide (the page grows to fit them).

Editing a deck from the player

out/deck.json records where every slide was written — which markdown file, and which ----separated block of it. That is what lets refractplayer rearrange and rewrite a deck without a terminal: drag a slide in the deck view, type in the slide editor, press Rebuild in the build panel, and slides.md is what changes. The player never parses markdown itself; the edits are made by player/tools/*.py, which sit on refractkit.chunks so the block numbering is the same one markdown.py produces.

python3 player/tools/reorder.py <deck>/out --move 12 --to 3      # move a slide
python3 player/tools/slide.py   <deck>/out --slide 12 --read     # one slide's markdown
python3 player/tools/build.py   <deck>/out --transitions         # rebuild, and say what it did
python3 player/tools/slide.py   <deck>/out --slide 12 --split 4   # break it in two
python3 player/tools/history.py <deck>/out --undo                # take the last one back

See player/README.md.

Captions from a recorded talk

refractplayer --record-audio records one wav per slide, --transcribe turns those into per-word caption timings, and --captions shows them as a close-caption window with each word lit as it is spoken (or press C). All three are the player's — none of it has anything to say about turning markdown into slides.

prebuilt/refractplayer mytalk/out --record-audio     # record
prebuilt/refractplayer mytalk/out --transcribe       # transcribe + align
prebuilt/refractplayer mytalk/out --captions         # play back with captions
prebuilt/refractplayer mytalk/out --web mytalk/web   # …or as a web page

--web writes a self-contained site that plays the deck in a browser — the real .rc slides rendered by the RemoteCompose TypeScript player, the recorded narration, and captions lit word by word. It opens by double-clicking index.html as well as from a server, and compresses the narration on the way out. It needs that player's bundle built once (cd ../remotecompose-experiments/players/typescript && npm install && npm run bundle).

Two steps, each with its own optional dependency — the same split Echo's scripts make, because forced alignment against a known transcript is far more accurate than a transcriber's own word timings:

pip install openai-whisper     # transcription (or: pip install faster-whisper)
pip install whisperx           # forced alignment

The work itself is Python's — whisper and whisperx live there — so --transcribe runs player/tools/captions.py, which also stands alone. The transcript lands in voice/NN.txt, so a misheard word can be corrected there and --transcribe re-run: only the alignment is redone, against the text you supplied.

Prebuilt tools

  • prebuilt/json2rc — JSON → .rc converter (built from the local androidx checkout; adds an image component that embeds a file inline)
  • prebuilt/refractplayer — the deck player: presenter window (clock, notes, next slide), navigator, talk timer, blanking, fullscreen, rehearsal recording (--record / --record-audio, replayed with --auto-voice), a deck view that reorders the deck by rewriting its markdown (V, or --deck-view), a build panel that re-runs refract with its options on screen (M, or --build), a slide editor that rewrites one slide's markdown and rebuilds (E, or --editor), an asset window listing what is in includes/ and which slides use it (I, or --assets), and export to PDF (--pdf talk.pdf) or PNGs (--images dir/). This is what refract.py --pdf / --images run. Built from player/ on top of the rcplayer library in the RemoteCompose players/cpp tree — playback, export and the custom-component hosts are shared with rcviewer, not forked. player/build.sh rebuilds it. See player/README.md.
  • prebuilt/rcviewer — interactive C++ viewer, and the fallback exporter when the player has not been built (--pdf / --screenshot-dir are the same code refractplayer runs; --screenshot / --frames are its own). Keys: ←/→ step, Space pause, R reload, D debug, S screenshot, Q/Esc quit. Embedded web pages are live in the slide; click to interact, Esc returns keyboard focus to the deck. Slides are laid out at their design size and scaled to fit the window, so they fill fullscreen.
  • prebuilt/rc2image — headless .rc → PNG (--anim <sec> pins the animation time)

All three native tools are arm64, target macOS 11, and link only macOS's own frameworks — see The prebuilt binaries. prebuilt/json2rc is the odd one out: a Gradle launcher script plus jars, so it needs a JVM 21+ rather than being a binary at all.

Architecture

Implementation lives in the refractkit package; refract.py is just the CLI.

Module Responsibility
settings load settings.toml (stdlib tomllib)
theme Theme (colors, fonts, code+syntax, chrome, shaders, presets) from settings
markdown slide markdown → {meta, title, blocks, notes}
deck load slides.md, expand deck includes, resolve includes
components low-level component builders (text, dbg)
inline inline **bold** / *italic* / `code` → styled spans
images image dimensions + contained bitmap canvas (+ rounded clip)
highlight syntax highlighting — a language registry
graph graphviz layout → drawing (clusters/styles); magic-move geometry
chart bar / line / pie charts on a canvas
markers the four progress-bar marker shapes
measure how tall a block will be — shrinking a font to fit, and deciding when a slide needs scroll steps
samematch which content two consecutive slides share, for magic move
render blocks + theme → RemoteCompose component JSON
chunks the ----separated blocks of a slides.md: split, read, replace, insert, delete
reorder moving those blocks — a slide, a section, an included sub-deck
buildcache what the last build produced, so an unchanged slide is not recompiled
manifest reading out/deck.json, and replaying the options a deck was built with
history undo and redo for every edit that rewrites a deck's markdown
keys the block a slide was written in, and keeping it pointing there when blocks move
assets what is in includes/, and which slides use it — answered by loading the deck, so it cannot disagree with the build
meta the :: line's vocabulary and the include options, in one place: what may be written, and what each word does
preflight what this machine has and what it lacks, behind --check

refract.py itself is the CLI plus the build: slide_style (the theme a slide renders with), render_slide (which of the seven ways it is drawn) and manifest_record (what a player is told about it) are separate from the loop that walks the deck, so each can be asked directly — tests/test_build_pieces.py does, without json2rc in sight.

Add a language: drop a tokenize_x in highlight.py and register it in LANGUAGES. Restyle: edit settings.toml. Change the background: edit the .sksl.

chunks, reorder, history and keys are the ones the player edits a deck through. The player never parses markdown itself: block numbering has to agree exactly with markdown.py's (which splits on --- with no awareness of code fences, deliberately reproduced), and a second implementation would drift and rewrite the wrong slide. player/tools/*.py are thin CLIs over them.

assets and meta are there for the same reason one layer up: the editor offers a file or a word only if refract would accept it, so both answers come from refract's own code rather than from a list the player keeps. A slide type added to render.SLIDE_TYPES turns up in the editor's menu with nobody editing the player.

Tests

python3 -m unittest discover -s tests          # refract, and the player's tools
ctest --test-dir player/build                  # the player's own logic — no window, no GPU

Both run on every push (.github/workflows/tests.yml). CI does not build the RemoteCompose engine — configuring the player fetches Skia, which is minutes of compiling for none of what usually breaks — so it runs the Python suite and the three C++ suites that need nothing but their own source. The tests that run a real build need json2rc, which comes from a local androidx checkout; about sixty of the five hundred are in that group and they skip cleanly where it is missing.

The Python suite covers the markdown grammar, rendering, the incremental build, and the tools the player edits decks through. The C++ suites cover the parts of the player that are pure logic: the reordering arithmetic, the editor's text model, and the rehearsal trace. Neither needs a display.

Notes

  • Images embed inline (the C++ viewer only renders inline images, not URL/file refs).
  • A binary .rc can't be spliced into a JSON tree, so live rc-embed uses the sibling .json.
  • Graph magic move uses expression-interpolation (matched by dot id), which fits canvas-drawn graphs and needs no player changes.
  • Custom components (LAYOUT_CUSTOM, op 93) delegate drawing to a host keyed by a config string; the viewer's video host plays embedded <name.mp4> in place — see Embedded video & custom components above.
  • Graph node glow is a real gaussian blur: the bright node borders are drawn into a layer with a graphicsLayer blur render effect (the Skia equivalent of Android RenderEffect.createBlurEffect), behind the crisp graph. Tunable/disable-able via [graph] glow, glow_radius, glow_strength. Implementing this added blur support to the C++ player (saveLayerWithBlur) and exposed a blur key on the graphicsLayer JSON modifier — both reusable beyond graphs.
  • Push transitions share one background: when the outgoing and incoming slides use the same background (shader or solid), it's drawn once behind the stage and only the foreground content slides — half the full-slide shader work per frame, so the animate-in stays smooth. The ambient background simply doesn't slide (visually equivalent).

Slide-driven embedded documents

An embedded .rc normally lives and dies with its slide: it loads when the slide appears, runs on the slide's clock, and is dropped when you move on. Three include options turn one document into something that runs across slides, paced by them:

<film.rc | persist step=3 stepid=42 timeid=43 ratio=16:9>
  • persist keeps the document alive across slide changes (like an embedded web view) on its own clock — seconds since it first loaded — so consecutive slides embedding the same file share one live document that neither reloads nor rewinds. step= implies it.
  • step=N is this slide's number for the document, written each frame into the float variable whose id is stepid; timeid names the float that receives the host's time (seconds since the slide started). Both are the document's own DATA_FLOAT ids — declare the two as plain-number variables first in resources.variables and they are 42 and 43 (read them back with rc2json if in doubt).
  • In the document, derive the clock from them: TA = start[STEP] + span[STEP]·clamp(SLIDETIME·rate[STEP], 1, 0) (float arrays hold the per-chapter numbers), and add + animTime*0.0 to it so the whole dependent chain re-evaluates every frame — a host override on a plain variable only wakes its direct listeners, whereas anything hanging off the clock is walked each frame.

Put transition=none on those slides: a crossfade or push would draw the previous slide's copy over the document's own hand-over.

About

Presentation software

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages