Wayscriber Docs

Wayscriber is a Wayland screen annotation tool for drawing on top of your desktop during demos, teaching, and screen shares.

These docs track the latest source. If you need an older version, use the GitHub release notes.

Start here

Quick Start
Installation
First Run and Keybinds
The Gift Exchange

What you can do

Draw on top of any screen
Switch between named boards with custom backgrounds (transparent, whiteboard, blackboard, and more)
Pan solid boards with Space+drag and reset them from the right-click menu
Jump between boards with the picker and quick slots
Use board pages for multi-step walkthroughs
Zoom in/out, pan, and reset the view during callouts
Draw while zoomed to highlight fine details
Pick a drawing color from the displayed desktop with the screen eyedropper and magnified pixel loupe
Keep separate named session files and manage them from the overlay or configurator
Create multi-line text and sticky notes
Drop numbered step markers and auto-numbered arrows
Paste copied PNG/JPEG images as movable canvas objects
Save full per-tool preset profiles for instant switching
Apply or create preset profiles from the top strip’s presets island
Undo/redo quickly and clear the canvas in one keypress
Capture screenshots to file or clipboard
Presenter helpers: freeze the screen, presenter mode, click highlights, an on-screen input HUD for keystrokes and clicks, and layer-shell light passthrough
Select/move shapes with Alt-drag or V, copy/paste from the context menu, then edit in the properties panel
Configure drag tools globally or per mouse button
Use the icon-led command palette to search actions, edit shortcuts, and reopen persisted recent commands, including Save Preset 1–5
Click the chip HUD to open boards/pages, colors, tools, or searchable Help
Open Canvas… from the top-strip overflow for boards, pages, advanced history, zoom, and Step Undo/Redo controls
Adjust zoom from the persistent bottom-right percentage chip
Use the contextual style pill instead of keeping a permanent side panel open
Save and restore sessions across runs
Configure everything with the GUI or the config file

Requirements

A Wayland session. X11 is not supported.
Known-good layer-shell compositors: Hyprland, Sway, River, Wayfire, Niri/COSMIC, and KDE Plasma/KWin.
GNOME is supported through the xdg-shell/portal fallback, with limits: light passthrough is unavailable and fullscreen/input behavior can vary.
Runtime libraries are installed by the DEB/RPM/AUR/Nix packages. You only need to install Cairo, Pango, Wayland, and libxkbcommon development packages yourself when building from source or using the tarball.

What is Wayscriber

Wayscriber is a Wayland overlay for screen annotation. It lets you draw, highlight, and write on top of any window without switching apps, with built-in zoom for precise callouts.

You can run it as a background daemon and toggle the overlay instantly, or launch a one shot overlay when you need it.

Wayscriber is built for presenters, teachers, streamers, and anyone who wants fast visual callouts on Linux.

Why Wayscriber

Wayscriber exists to make live explanation feel effortless. It keeps you in flow during a demo or lesson while your audience stays oriented.

Key goals:

Immediate access to drawing and highlighting
Low friction switching between tools and modes
Works across multiple Wayland compositors
Practical defaults, with deep customization when you want it

Feature Highlights

Freehand pen, line, rectangle, ellipse, arrow, step marker, text, sticky note, marker, and eraser tools
Named boards with custom backgrounds, quick slots, and per-board pages
Session persistence across runs, named session files, the top-strip Session popover, and configurator catalog management. See Sessions and Session Manager.
Fast toggle via daemon and keybind
Low-latency drawing mode with optional vsync disablement and configurable 120/144/240+ FPS caps
Incremental dirty-region rendering keeps long accumulated strokes responsive
Screenshot capture to file or clipboard
Preset slots that restore full per-tool drawing profiles, with filled/empty slots available directly in the top strip
Configurator GUI and full config file control
Zoom, freeze, click highlights, auto-numbered arrows, presenter mode, and light passthrough for clean callouts
Input HUD showing your keystrokes and clicks on screen for demos and screencasts, with optional system-wide capture
Context menu, selection tools (Alt-drag or V), copy/paste, duplicate/delete shapes, docked selection properties, and an expanded command palette for editing
External PNG/JPEG image paste as editable canvas objects
Configurable drag tools, including per-button left/right/middle bindings
Fixed-compass radial marking menu with press-flick-release tool selection, recent colors, shape sub-menu, and an outer size ring
Screen eyedropper with a magnified pixel loupe, available from both color interfaces and the command palette

Customization

GTK4 toolbars are used automatically on supported layer-shell paths, with a feature-equivalent builtin Cairo fallback.
The default top UI uses detached Tools, Presets, History, and Chrome islands plus a contextual style pill for color, size, text, eraser, and selection controls.
The interactive chip HUD opens boards/pages, colors, the radial menu, and Help directly. Canvas, Session, and Settings live in top-strip overflow popovers.
The Canvas popover re-homes boards, pages, advanced history, zoom, and Step Undo/Redo controls. A bottom-right chip keeps the live zoom percentage and zoom-out, zoom-in, Fit, and Lock controls available without a side panel.
side_layout = "panel" restores the deprecated four-pane side palette for one compatibility release and shows a once-per-session map to the new homes.
Toolbars are configurable: show/hide individual items, collapse side sections, and reorder top tools/top controls/side sections. Overlay preferences survive restarts in separate runtime UI state without rewriting authored config.toml defaults. See Toolbars.
Dark/light chrome and reduced motion are configurable under [ui].
The configurator has global search with scoped matches across tabs, sections, sessions, boards, presets, profiles, and keybindings.

Discoverability

The command palette has action icons, category headers, fuzzy matching, shortcut editing, Save Preset 1–5 actions, and a persisted Recent section.
The help overlay is searchable and clickable, reflows to one or two columns, and can replay the guided tour.
The first-run tour teaches colors/thickness, radial flicking, and Boards & Pages using the user’s current bindings. Later, staggered hints introduce the chip HUD, Canvas popover, and zoom chip without piling up, while the shortcut coach can surface occasional key hints.
Prioritized notifications keep critical warnings and undo actions ahead of routine information and hints.

The Gift Exchange

Wayscriber is built primarily for my own workflow. I share it as open source because it helps others and I like shipping the tool in public.

This project is a gift exchange, not a contract. If the framing is new, see The Open Source Gift Exchange for a clear explanation.

What that means:

The software is free to use and you can rely on the license.
Requests are welcome, but no one is owed features, timelines, or support.
I have already shipped dozens of user requested features when they aligned with the project and I had time, and I will keep doing that when it makes sense.
Bugs are fixed as quickly as I can, but there is no guaranteed response time.

If you want to influence the roadmap, the best ways are:

Ask politely and explain the use case.
Contribute code, docs, or testing.
Share clear bug reports with steps to reproduce.

How to Ask for Features

Feature requests are welcome when they are clear and respectful. Good requests save time and make it easier to say yes.

A good request includes

The problem you are trying to solve
Your compositor and distro
The exact workflow you want
Why existing features are not enough

Ways to help

Offer to test a build
Share screenshots or short recordings
Contribute a PR if you can

If a request does not fit the project or timing, the answer may still be no. That is normal and not personal.

Quick Start (5 min)

3) Pick a run mode

For daily use, daemon mode is best:

wayscriber --daemon

If you have the user service installed:

systemctl --user enable --now wayscriber.service

4) Add a keybind

Hyprland Lua config (~/.config/hypr/bindings.lua):

o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

Traditional Hyprland config:

bind = SUPER, D, exec, wayscriber --daemon-toggle

Use your compositor settings to bind the same command. Define the toggle binding only once. If your compositor does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber.

Light passthrough has one extra rule: F6 is an in-overlay shortcut, not a global shortcut. Once passthrough is active, bind compositor shortcuts to wayscriber --light-toggle and wayscriber --light-draw-toggle so you can still switch modes, including exiting passthrough, while input is going to the app underneath. See Compositor Guides for Hyprland and KDE examples.

5) Learn the basics

F1 opens the help overlay (F10 is the alternative)
F11 opens the configurator (if installed)
F9 shows or hides the toolbars; F2 cycles the top strip full → micro → hidden
F6 enters light passthrough while Wayscriber has focus; use a global wayscriber --light-toggle shortcut to get back out
Hold middle-click and flick toward a radial-menu wedge for quick tool selection, or open it normally for tools, colors, recent colors, and size adjustment
Escape or Ctrl+Q exits the overlay

Installation

Ubuntu / Debian

Wayscriber v0.9.23+ .deb packages support Ubuntu 24.04+, Linux Mint 22+, Pop!_OS 24.04+, and Debian 13 (trixie)+. They require glibc 2.39 and GTK 4.12, and embed the pinned GTK4 layer-shell integration, so no separate libgtk4-layer-shell0 package is needed. Pop!_OS 22.04 has GTK older than the default build requires; use the GTK-less build there unless you separately install GTK 4.12 or newer.

Repo install (recommended):

sudo install -d /usr/share/keyrings
curl -fsSL https://wayscriber.com/apt/WAYSCRIBER-GPG-KEY.asc | sudo gpg --dearmor -o /usr/share/keyrings/wayscriber.gpg
echo "deb [signed-by=/usr/share/keyrings/wayscriber.gpg] https://wayscriber.com/apt stable main" | sudo tee /etc/apt/sources.list.d/wayscriber.list
sudo apt update
sudo apt install wayscriber

Configurator (repo):

sudo apt install wayscriber-configurator

One-off .deb (no auto-updates):

wget -O wayscriber-amd64.deb https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-amd64.deb
sudo apt install ./wayscriber-amd64.deb

Configurator .deb (no auto-updates):

wget -O wayscriber-configurator-amd64.deb https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-configurator-amd64.deb
sudo apt install ./wayscriber-configurator-amd64.deb

Fedora / RHEL

Repo install (recommended):

cat <<'EOF' | sudo tee /etc/yum.repos.d/wayscriber.repo
[wayscriber]
name=Wayscriber Repo
baseurl=https://wayscriber.com/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://wayscriber.com/rpm/RPM-GPG-KEY-wayscriber.asc
EOF
sudo dnf clean all
sudo dnf install wayscriber

The RPM repo publishes the key as both RPM-GPG-KEY-wayscriber.asc and RPM-GPG-KEY-wayscriber. Use the extensionless alias if your rpm-ostree or repo tooling expects that form.

Configurator (repo):

sudo dnf install wayscriber-configurator

One-off .rpm (no auto-updates):

wget -O wayscriber-x86_64.rpm https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-x86_64.rpm
sudo rpm -Uvh wayscriber-x86_64.rpm

Configurator .rpm (no auto-updates):

wget -O wayscriber-configurator-x86_64.rpm https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-configurator-x86_64.rpm
sudo rpm -Uvh wayscriber-configurator-x86_64.rpm

Arch Linux (AUR)

The AUR is the recommended path because pacman tracks the installed files and your AUR helper handles upgrades. Install the prebuilt binary:

yay -S wayscriber-bin
# or
paru -S wayscriber-bin

Or build from source:

yay -S wayscriber
# or
paru -S wayscriber

Configurator (GUI):

yay -S wayscriber-configurator
# or
paru -S wayscriber-configurator

Direct release installer (no AUR)

On x86_64 Arch-based systems, you can install the latest stable GitHub release without waiting for an AUR package. Download the script so you can inspect it before running it:

curl -fsSL https://wayscriber.com/arch-install.sh -o arch-install.sh
sh arch-install.sh --dry-run
sh arch-install.sh

The dry run downloads the release, checks its SHA-256 and install manifest, verifies the required Arch packages, and checks for a pacman-owned or unmanaged Wayscriber installation without installing files. Both the dry run and the full run refuse another copy that is not this install: unmanaged files under /usr, ~/.local/bin/wayscriber, or a user unit / drop-in whose ExecStart is not /usr/local/bin/wayscriber. A symlink that already resolves to the dest is not a conflict. Pass --replace-other on those commands to remove the other copy first. If wayscriber.service is already active, the installer restarts it unless you pass --no-restart. If a dependency is missing, it prints the pacman command to install it.

Remove the direct installation before moving to the AUR. Otherwise, the copy under /usr/local continues to take priority. Follow the direct installer removal steps.

NixOS / Nix

Wayscriber is packaged in nixpkgs. On NixOS, install it declaratively. nix profile is mainly useful when running Nix on another Linux distribution.

Which version you get:

Source	Tracks
`nixpkgs-unstable`	Follows Wayscriber releases, usually within a few weeks
Stable channels (`nixos-25.11`, `nixos-26.05`, …)	Pinned when the release branch was cut; version bumps are not backported
The project flake	The tag or branch recorded in your `flake.lock`

On a stable channel, use the project flake below when you want the newest release.

NixOS, from nixpkgs (recommended) — add to configuration.nix or another module:

{ pkgs, ... }:

{
  environment.systemPackages = with pkgs; [
    wayscriber

    # Optional screenshot and clipboard helpers on wlroots compositors:
    grim
    slurp
    wl-clipboard
  ];
}

Then rebuild with sudo nixos-rebuild switch, or sudo nixos-rebuild switch --flake .#myhost for a flake-based configuration.

Home Manager:

{ pkgs, ... }:

{
  home.packages = [ pkgs.wayscriber ];
}

Then run home-manager switch.

The nixpkgs build installs the wayscriber binary. The desktop entry, icons, and the wayscriber.service systemd user unit come with the flake packages below, which also provide the optional Configurator.

Try it without installing:

nix run nixpkgs#wayscriber -- --active
# Or the current upstream development branch:
nix run github:devmobasa/wayscriber -- --active

Latest release and the Configurator — add the flake input to your existing flake.nix, replacing RELEASE_TAG with a published tag such as the one shown on the latest release:

inputs.wayscriber.url = "github:devmobasa/wayscriber?ref=RELEASE_TAG";

Make it available in outputs:

outputs = { nixpkgs, wayscriber, ... }: {
  # Your existing outputs...
};

Then add this module to the modules list of your nixosSystem:

({ pkgs, ... }:

  let
    wayscriberPackages =
      wayscriber.packages.${pkgs.stdenv.hostPlatform.system};
  in
  {
    environment.systemPackages = [
      wayscriberPackages.wayscriber
      wayscriberPackages.wayscriber-configurator
    ];

    # Required before `systemctl --user enable --now wayscriber.service` works.
    systemd.packages = [ wayscriberPackages.wayscriber ];
  }
)

Your flake.lock pins the exact revision — a GitHub flake input does not keep following the branch on its own. To upgrade to a newer release, change RELEASE_TAG in flake.nix to the new published tag, then update only this input:

nix flake update wayscriber
sudo nixos-rebuild switch --flake .#myhost

Nix on another Linux distribution — a user profile install is reasonable there:

nix profile install nixpkgs#wayscriber
# Current upstream development branch and the optional Configurator:
nix profile install github:devmobasa/wayscriber#wayscriber
nix profile install github:devmobasa/wayscriber#wayscriber-configurator

Profile installs do not update with the rest of the system. Upgrade them with nix profile upgrade wayscriber, or remove them with nix profile remove wayscriber.

Build from source (any distro)

Rust 1.95 or newer is required.

Clone first so the optional dependency helper is available:

git clone https://github.com/devmobasa/wayscriber.git
cd wayscriber

Dependencies for the default GTK toolbar build:

# Debian 13+ / Ubuntu 25.04+ (including Ubuntu 26.04 LTS)
sudo apt-get install build-essential pkg-config libcairo2-dev libwayland-dev libpango1.0-dev libgtk-4-dev libgtk4-layer-shell-dev

# Fedora
sudo dnf install gcc gcc-c++ make pkgconf-pkg-config cairo-devel wayland-devel pango-devel libxkbcommon-devel cairo-gobject-devel gtk4-devel gtk4-layer-shell-devel

Ubuntu 24.04 LTS and Mint 22 have suitable GTK4 but not the layer-shell development package. Install the base dependencies, then build the pinned library:

sudo apt-get install build-essential pkg-config curl libcairo2-dev libwayland-dev libpango1.0-dev libgtk-4-dev meson ninja-build wayland-protocols
bash tools/install-gtk4-layer-shell.sh

Build with the default GTK frontend:

cargo build --release

Or build without GTK toolbars (required for the normal Pop!_OS 22.04 packages):

sudo apt-get install build-essential pkg-config libcairo2-dev libwayland-dev libpango1.0-dev
cargo build --release --no-default-features --features tablet-input,portal,tray

The GTK-less build retains the builtin Cairo toolbars.

The binary will be at target/release/wayscriber.

Screenshot tools (source/tarball only):

# Ubuntu / Debian
sudo apt-get install wl-clipboard grim slurp

# Fedora
sudo dnf install wl-clipboard grim slurp

Configurator build (optional):

cargo build --release --manifest-path configurator/Cargo.toml

Install script (optional):

cargo build --release
./tools/install.sh

The installer copies the binary to /usr/bin/wayscriber (or $WAYSCRIBER_INSTALL_DIR) and offers to set up a systemd user service or Hyprland keybinds. It refuses a second copy under /usr/local/bin or ~/.local/bin unless you pass --replace-other or confirm.

Keeping it current

Wayscriber tells you when a newer release exists but never installs anything itself. See Updating for the upgrade command for each source above, and for how to switch the check off.

Updating

Wayscriber never installs updates itself. It can tell you that a newer release exists — in the About window, in the tray menu, and once per release as a desktop notification — and then sends you here. Installing stays with whatever put Wayscriber on your system, so your package manager keeps its usual authority over what is on disk.

Check what you are running:

wayscriber --version

Ask right now whether anything newer exists, without waiting for the background check:

wayscriber --check-update

Then follow the section for the way you installed Wayscriber. If you are not sure, the About window’s “Copy diagnostics” button reports the install source when the package was built with one.

The tarball and source sections below take a version number. Set it once from what --check-update reported, and the commands in those sections will use it:

read -r -p "Version reported by wayscriber --check-update: " VERSION

Ubuntu / Debian

Wayscriber v0.9.23 and newer supports Ubuntu 24.04+, Linux Mint 22+, Pop!_OS 24.04+, and Debian 13+. The v0.9.22 package accidentally required libgtk4-layer-shell0, which is unavailable on Ubuntu 24.04 and its derivatives; upgrading to v0.9.23 or newer removes that external dependency.

From the apt repo (the recommended install):

sudo apt update
sudo apt install --only-upgrade wayscriber wayscriber-configurator

If you installed a one-off .deb, download the new one and install it over the old package:

wget -O wayscriber-amd64.deb https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-amd64.deb
sudo apt install ./wayscriber-amd64.deb

One-off .deb files never update themselves. Switching to the repo (see Installation) is the easier path if you expect to keep up with releases.

Fedora / RHEL

From the dnf repo:

sudo dnf upgrade --refresh wayscriber wayscriber-configurator

If you installed a one-off .rpm:

wget -O wayscriber-x86_64.rpm https://github.com/devmobasa/wayscriber/releases/latest/download/wayscriber-x86_64.rpm
sudo rpm -Uvh wayscriber-x86_64.rpm

Arch Linux (AUR)

Same helper you installed with, same package name:

yay -Syu wayscriber              # source build
yay -Syu wayscriber-bin          # prebuilt binary
yay -Syu wayscriber-configurator # optional GUI

paru works the same way. AUR mirrors can lag the release by a few minutes.

Direct release installer

If you installed Wayscriber with the direct Arch release installer, download a fresh copy and rerun it. The script resolves the latest stable release each time:

curl -fsSL https://wayscriber.com/arch-install.sh -o arch-install.sh
sh arch-install.sh --dry-run
sh arch-install.sh

The installer updates its allowlisted files under /usr/local. It refuses to shadow an AUR or other pacman-owned installation, and it refuses another copy under /usr, ~/.local/bin, or a user unit / drop-in whose ExecStart is not /usr/local/bin/wayscriber, unless you pass --replace-other. If the user service is already active, it restarts that unit so the overlay daemon follows /usr/local/bin/wayscriber; pass --no-restart to leave the running unit alone. Keep using your AUR helper instead if that is how you originally installed Wayscriber.

Move from the direct installer to the AUR

Remove the direct installation before installing the AUR package. Files under /usr/local take priority over the package’s files under /usr, including the systemd user service.

systemctl --user disable --now wayscriber.service
curl -fsSL https://wayscriber.com/arch-install.sh -o arch-install.sh
sh arch-install.sh --uninstall --dry-run
sh arch-install.sh --uninstall
yay -S wayscriber-bin
systemctl --user enable --now wayscriber.service

The uninstaller removes only files in the direct install manifest under /usr/local. It leaves every pacman-owned file in place, and it does not remove your Wayscriber configuration or data. Actual removal is refused until wayscriber.service is stopped and disabled. A leftover unmanaged git build under /usr is left in place; pass --remove-unmanaged-usr only when that /usr copy should go too. Default uninstall does not remove ~/.local/bin/wayscriber or a user unit / drop-in; the script warns if those still point at /usr/local so they cannot shadow the AUR package.

NixOS / Nix

From nixpkgs, update the channel or flake input your system already tracks, then rebuild:

sudo nixos-rebuild switch                      # channel-based configuration
sudo nixos-rebuild switch --flake .#myhost     # flake-based configuration

Stable channels pin the version that existed when the release branch was cut, and Wayscriber bumps are not backported. If you need the newest release on a stable channel, use the project flake.

From the project flake, change RELEASE_TAG in your flake.nix to the new tag, then update only that input:

nix flake update wayscriber
sudo nixos-rebuild switch --flake .#myhost

A nix profile install (Nix on another distribution) upgrades with:

nix profile upgrade wayscriber

Tarball

Download the new release tarball and the checksum file published beside it, verify the archive, then replace the files you installed from the previous one. VERSION is the version you set above:

BASE="https://github.com/devmobasa/wayscriber/releases/download/v${VERSION}"
wget "${BASE}/wayscriber-v${VERSION}-linux-x86_64.tar.gz" "${BASE}/checksums.txt"
sha256sum --ignore-missing --check checksums.txt

sha256sum must print wayscriber-v${VERSION}-linux-x86_64.tar.gz: OK. If it prints anything else, stop and do not install the archive. Then extract and install:

tar -xzf "wayscriber-v${VERSION}-linux-x86_64.tar.gz"
sudo install -Dm755 "wayscriber-v${VERSION}-linux-x86_64/usr/bin/wayscriber" /usr/local/bin/wayscriber

The archive also carries the desktop entry, icons, and the wayscriber.service systemd user unit under usr/. If you installed those the first time, copy the same paths again:

sudo cp -r "wayscriber-v${VERSION}-linux-x86_64/usr/share/." /usr/local/share/
sed 's#/usr/bin/wayscriber#/usr/local/bin/wayscriber#' \
    "wayscriber-v${VERSION}-linux-x86_64/usr/lib/systemd/user/wayscriber.service" \
    > wayscriber.service.local
sudo install -Dm644 wayscriber.service.local /usr/local/lib/systemd/user/wayscriber.service

Restart the daemon after replacing the binary:

systemctl --user daemon-reload
systemctl --user restart wayscriber.service

Build from source

Pull the new tag and rebuild with the same feature flags you used before:

cd wayscriber
git fetch --tags
git checkout "v${VERSION}"
cargo build --release

INSTALLED="$(type -P wayscriber)"
if [[ -w "${INSTALLED}" ]]; then
    install -Dm755 target/release/wayscriber "${INSTALLED}"
else
    sudo install -Dm755 target/release/wayscriber "${INSTALLED}"
fi

That final step replaces the executable already on your PATH; rebuilding by itself does not update an earlier installed copy. Restart wayscriber.service afterward if you run the daemon as a systemd user service.

Build dependencies occasionally change between releases; if the build fails, re-read the dependency list in Installation before filing anything.

The update check

The check is a single HTTPS request for one small static file, https://wayscriber.com/latest.json, containing the newest published version and the links to these instructions. Wayscriber compares that version to its own and stops there. It does not download packages, execute anything, or restart your session.

Details worth knowing:

What is sent: no Wayscriber or user identifier, no Wayscriber version, no query parameters, and no cookies. The HTTP client’s version is suppressed too. The request goes out through whichever of curl or wget is installed, so it uses your system’s CA store and proxy settings — but it is invoked with client config files disabled, and Wget cannot consult ~/.netrc, so those files cannot attach headers, cookies, or credentials. One check is one request: if the client is installed and the request fails, that is the result — nothing is retried with a second client.
How much is read: the response is cut off past 64 KiB, so a wrong or hostile answer cannot be streamed into memory.
How often: once a day by default, and never more than once per hour. The daemon performs the check; the About window only reads the cached result unless you press “Check now”.
Notifications: at most one desktop notification per release, suppressed while the annotation overlay is active. The tray keeps the notice until you act on it.
Where the result is stored: $XDG_CACHE_HOME/wayscriber/update-check.json (~/.cache/wayscriber/update-check.json by default). Deleting it just makes the next check look like the first one. If the file cannot be written at all, the interval is still honored for the life of the process, so an unwritable cache does not turn the daily check into a repeated one.
What “checked N ago” means: the last check that actually got an answer. A failed attempt delays the next one, but never presents an older result as freshly verified: the About window says “Last check failed” alongside the age of the last real answer. Failed explicit checks count toward the interval too — the request was already made.

Turning it off

In config.toml:

[updates]
check = false          # never contact the network
notify = false         # keep the About/tray notice, drop the desktop notification
interval_hours = 24    # minimum 1, maximum 720

Or, without editing config — useful for a session wrapper or a locked-down deployment:

export WAYSCRIBER_DISABLE_UPDATE_CHECK=1

The environment variable wins over the config file. wayscriber --check-update still works when it is set: asking for a check explicitly is its own consent.

Setting it to 0, false, no, off, disable, disabled, or an empty value leaves the check on, matching the boolean words Wayscriber’s other variables accept. Any other value opts out — for a switch whose only job is to stop network access, a value it does not recognize is honored rather than ignored.

If the config file exists but cannot be parsed, the background check does not run at all: Wayscriber cannot confirm your [updates] setting, so it assumes the stricter one until the file is valid again.

Distribution packagers who must guarantee that the binary never contacts wayscriber.com can remove the check at build time:

WAYSCRIBER_NO_UPDATE_CHECK=1 cargo build --release

Such a build reports “Update checks are off in this build” in the About window, and wayscriber --check-update says the same instead of making a request. Nothing in config.toml or the environment can turn it back on. This is a separate variable from the runtime opt-out above, so exporting WAYSCRIBER_DISABLE_UPDATE_CHECK in your shell does not quietly change what a source build is capable of.

Packagers should also set WAYSCRIBER_INSTALL_SOURCE (apt, rpm, aur, nix, tarball, source) when they do ship the check, so the update notice opens the section of this page that applies to their users.

First Run and Keybinds

Wayscriber has two run modes: daemon mode (recommended) and one-shot mode.

Daemon mode (recommended)

Wayscriber stays running in the background. You toggle the overlay on and off with a keyboard shortcut — instant, no startup delay. This is the best way to use wayscriber day-to-day.

Start the daemon:

systemctl --user enable --now wayscriber.service

Or run it directly:

wayscriber --daemon

Then add a keybind that runs wayscriber --daemon-toggle. For Hyprland Lua, add this to ~/.config/hypr/bindings.lua:

o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

For a traditional Hyprland config:

bind = SUPER, D, exec, wayscriber --daemon-toggle

On GNOME, add a Custom Shortcut in Settings → Keyboard with the command wayscriber --daemon-toggle.

Use only one toggle binding. Duplicate compositor bindings can fire twice and immediately undo the toggle. If your shortcut environment does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber.

Press the shortcut to draw, press it again to hide.

Light passthrough shortcuts

Light passthrough mode makes the overlay click-through until drawing is explicitly enabled. The default F6 keybinding is a Wayscriber in-overlay shortcut: it works while the overlay has focus, but once passthrough is active Wayscriber may no longer receive that keypress.

Once passthrough is active, normal keyboard and pointer input goes to the app underneath. For reliable control, add compositor/global shortcuts that run:

wayscriber --light-toggle
wayscriber --light-draw-toggle
wayscriber --light-draw-on
wayscriber --light-draw-off

Use --light-toggle for passthrough on/off, including getting back out after input is passed through. Use --light-draw-toggle for sticky drawing, and --light-draw-on / --light-draw-off for draw-while-held. See Compositor Guides for Hyprland and KDE examples. Light passthrough requires layer-shell support; it is disabled on the xdg-shell fallback.

One-shot mode

Opens the overlay once and exits when you close it. Good for quick tests or occasional use — no service needed.

wayscriber --active

Default keys you should know

F1 opens help (F10 is the alternative)
Shift+F1 opens the quick reference
F9 shows or hides the toolbars
F2 cycles the top strip through full, micro chip, and hidden
F11 opens the configurator (if installed)
About Wayscriber (version, links, update status) has no default key. Reach it from the top strip’s chrome, the overflow’s Settings… popover, the help overlay footer, or the command palette — or bind open_about yourself.
F4 toggles the status bar (F12 is the alternative)
Ctrl+Shift+F freezes/unfreezes the screen
Ctrl+Shift+M toggles presenter mode
F6 enters light passthrough while the overlay has focus; use a global wayscriber --light-toggle shortcut to get back out
Ctrl+Shift+H toggles click highlights
Ctrl+Shift+K toggles the input HUD (keystrokes and clicks on screen)
Ctrl+K opens the command palette. It shows action icons, category headers, and persisted recent commands. Use arrows/Home/End to navigate, Ctrl+U to clear, and Ctrl+Backspace to delete the previous word. Search Save preset to save slots 1–5 from the palette.
Ctrl+Shift+B opens the board picker
Ctrl+Alt+Shift+Left/Right moves overlay focus to previous/next output
V toggles the selection tool
Hold Alt and drag to select/move shapes
Ctrl+D duplicates selected shapes
Delete removes selected shapes
Escape or Ctrl+Q exits the overlay

Guided tour and quick help

First launch shows a short guided tour. Space/Enter advances, Backspace goes back, Escape skips.
The tour resolves shortcut text from your current bindings and covers drawing, colors/thickness, the middle-click radial flick gesture, and opening Boards & Pages from the status bar or current board-picker shortcut.
Replay it from the searchable Help footer or from the command palette: Ctrl+K, then search for “Replay Tour”.
For output actions, open the command palette and search for “monitor” or “display”.
The full help overlay supports fuzzy search; just start typing to filter shortcuts. Rows are clickable, and the layout uses one or two columns depending on available width.
After the tour, the shortcut coach may show a limited number of hint notifications when a toolbar, palette, Canvas-popover, or zoom-chip action has a useful keyboard shortcut. It is rate-limited and suppressed while other onboarding UI is active.
Later sessions can show staggered, capped hints for the status-bar board picker, Canvas… popover, and bottom-right zoom chip. They only appear when the named surface is reachable and never stack on top of other feedback.
If you deliberately use deprecated side_layout = "panel", a once-per-session notice points to the style pill, Canvas popover, zoom chip, status bar, presets island, and Session/Settings overflow entries.

Overlay vs Daemon

Overlay (one shot)

Starts immediately and exits when you close it
Simple and predictable
Best for quick annotations
Can open a named session with --session-file

Command:

wayscriber --active
wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session

Daemon (background)

Runs in the background and keeps your drawings between toggles
Faster to access during presentations
Works well with a keybind
Can be targeted by named-session toggle requests

Command:

wayscriber --daemon
wayscriber --daemon-toggle
wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session

If installed, the systemd user service is the most reliable way to keep the daemon running. Use only one compositor/global toggle binding; duplicate bindings can fire twice and immediately undo the toggle.

Overlay UI

The default overlay UI uses a top strip, contextual style pill, interactive chip HUD, and focused popovers:

The style pill contains color, size, and active-tool or selected-object properties.
The HUD opens the board picker, page controls, color picker, radial menu, and Help.
The overflow menu opens Canvas, Session, and Settings popovers. Canvas contains boards, pages, advanced history, zoom, and Step Undo/Redo controls. Session contains Open, Save As, Info, Clear, recents, and Manager. See Sessions and Session Manager.
Settings contains toolbar/status options, config/configurator shortcuts, section toggles, and customization.
A persistent bottom-right zoom chip shows the live percentage and exposes zoom-out, zoom-in, Fit, and (while zoomed) Lock controls.

Toolbar pins, minimized/pane/collapsed state, individual item visibility/order, and board pins are saved in generated runtime UI state, so they survive overlay and daemon restarts without rewriting authored defaults in config.toml. Settings shows the runtime-state status and provides reset and recovery actions. Authored toolbar section toggles still update config.toml. See Config File Overview.

Set ui.toolbar.side_layout = "panel" only when you need the deprecated four-pane Draw/Canvas/Session/Settings side palette. See Toolbars for the default layout, F2/F9 behavior, GTK4/builtin selection, and width-aware overflow.

Toolbars and the chip HUD

Wayscriber’s default interface keeps drawing controls close to the canvas without a permanent side panel. Press F9 to show or hide the toolbars. Press F2 to cycle the top strip through full → micro → hidden.

Top strip

The full top strip is arranged as detached islands:

Tools: drawing tools, the Shapes picker, Text, Sticky Note, Screenshot, and Highlight.
Presets: 3–5 saved slots between Tools and History. A filled slot applies its saved tool profile; an empty slot saves the current profile.
History: Undo, Redo, and the overflow menu.
Chrome: an About button plus the pin and minimize controls. About opens the standalone About window (version, links, update status) and closes the overlay, because that window is a normal one and the overlay draws above those. Hide it from Customize if you would rather keep the strip narrower.

The presets island follows show_presets and is the first island removed when the viewport gets tight. Lower-priority controls then move into the overflow menu while Pen, Eraser, Undo, Redo, Clear, and the strip chrome stay reachable.

The overflow always provides three focused surfaces: Canvas…, Session…, and Settings…. Opening one closes the others. They remain available under the legacy panel layout as transient quick surfaces; under pill mode they are the canonical homes for those workflows.

Clear lives at the top of the overflow menu instead of occupying a permanent button. A normal click clears with a short Undo? action; Shift+click clears immediately. The E shortcut remains immediate.

After about four idle seconds, the islands dim and restore when the pointer approaches or drawing resumes. Set [ui] reduced_motion = "on" to make that transition snap instead of animate.

Contextual style pill

A second pill below the strip changes with the active tool. It is the single home for the current-color chip and quick-color swatches, plus the controls that matter now:

stroke or eraser size;
marker opacity;
fill and auto-number options;
text size and Sans/Mono selection;
eraser brush/stroke mode;
selection properties when the Select tool has an active selection.

Click a displayed px/pt value for precise keyboard entry. The quick-color row uses the first eight configured colors and keeps the R/G/B/Y/O/P/W/K shortcuts. Hiding top.group.quick-colors hides those swatches but deliberately keeps the current-color chip, so the full color picker remains reachable.

Micro mode and minimizing

The F2 cycle’s micro state is one 44px chip: the active tool glyph sits inside a ring drawn with the current color and stroke width. Click it to restore the full strip. The full/micro choice persists; the hidden step is runtime-only.

Minimize is separate from micro mode. It collapses a toolbar to an edge restore tab, while F9 is the direct show/hide toggle.

Interactive chip HUD

The status bar is a compact chip HUD rather than a passive text line. Depending on available space it shows board, page, current color, tool/size, text font, and Help. Its segments open the corresponding surface:

board or page → board picker;
color → color picker;
tool/size → radial menu;
Help → help overlay.

Set ui.status_bar_interactive = false if you prefer a display-only HUD whose clicks pass through to the canvas. Frozen, zoom, pan, and editing states appear as stacked badges above it.

Choose Canvas… from the top strip’s ... overflow to reach the controls that formerly occupied the Canvas side pane. The popover contains five independently configurable sections:

Boards: previous, next, new, duplicate, and delete;
Pages: previous, next, new, duplicate, and delete;
Advanced: undo/redo all, timed undo/redo, and Freeze;
Zoom: zoom in, zoom out, reset, and lock;
Step Undo/Redo: step buttons, counts, and optional delay sliders.

The existing show_boards_section, show_pages_section, show_actions_advanced, show_zoom_actions, show_step_section, and show_delay_sliders settings control those sections. There is no separate Canvas-popover configuration key.

When show_zoom_actions = true, a persistent chip in the bottom-right corner shows ⊖ NN% ⊕ Fit; while zoomed, it also adds Lock. The percentage is live, Fit returns to 100%, and the chip remains available whether the toolbar frontend is GTK4 or builtin Cairo. It replaces the old duplicate zoom status badge, so only one zoom percentage is shown.

Where the old side-panel functions went

ui.toolbar.side_layout = "pill" is the default. It does not create a standalone side palette:

drawing properties live in the contextual style pill;
canvas management lives in the Canvas… overflow popover, bottom-right zoom chip, and chip-HUD board picker;
presets live in the top-strip presets island;
Session and Settings open from the top strip’s overflow menu.

The Canvas, Session, and Settings popovers contain the same workflows as their former panes and scroll internally when needed.

side_layout = "panel" is the legacy escape hatch. It restores the classic Draw, Canvas, Session, and Settings side palette, including pane scrolling, collapsible sections, side pinning, and side minimizing. It is deprecated and planned for removal after one compatibility release. Panel-mode users receive a once-per-session notice that names each replacement surface.

Do not confuse side_layout with layout_mode: side_layout chooses pill versus legacy panel, while layout_mode = "simple" | "regular" | "advanced" chooses the baseline complexity of visible sections. Explicit shown/hidden choices survive a layout-mode change.

GTK4 and builtin frontends

Default builds include two frontends driven by the same control specification:

GTK4 is selected automatically when Wayscriber can use separate layer-shell toolbar surfaces.
Builtin uses Wayscriber’s Cairo renderer for forced-inline layouts, unsupported compositor paths, GTK-less builds, or GTK startup fallback.

Choose explicitly in config.toml:

[ui.toolbar]
backend = "auto" # auto, gtk, or builtin

For a one-off override, set WAYSCRIBER_TOOLBAR_BACKEND=auto|gtk|builtin. gtk is a request rather than a guarantee: Wayscriber warns and falls back to the builtin frontend when that path cannot run.

Visibility and ordering

The Settings popover and configurator can:

switch Simple, Regular, or Advanced layout mode;
show or hide supported tools, controls, and legacy-panel sections;
reorder top tools, top controls, and side-section blocks;
restore the built-in order;
enable the optional ink-preview cursor, whose dot follows the current drawing color and width and includes the active tool glyph.

The configurator stores these choices as authored defaults under ui.toolbar in config.toml. The overlay Customize view uses those values as seeds and stores direct item visibility and order overrides in the generated $XDG_DATA_HOME/wayscriber/runtime-ui.toml file. Toolbar pin/minimized state, the active legacy pane, collapsed legacy sections, and board pins use that runtime file as well. Toolbar drag positions and authored choices such as section visibility continue to update their corresponding fields in config.toml.

Do not hand-edit runtime-ui.toml. Open Settings… to inspect its full path and status, reset runtime preferences, or recover from a failed save. See Configured defaults and runtime UI preferences.

Sessions and Session Manager

Wayscriber can restore drawings automatically, or you can work with named session files when each meeting, lecture, or project needs its own canvas state.

Default sessions

Default persistence is controlled by the [session] config section. It is the right choice when you want Wayscriber to reopen with the same drawing state you used last time.

[session]
persist_transparent = true
persist_history = true
restore_tool_state = true
per_output = true
storage = "auto"
max_file_size_mb = 50

With per_output = true, Wayscriber keeps separate default session files for each monitor.

Named session files

Use --session-file when you want a specific file to hold a specific drawing set:

wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --freeze --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --daemon --session-file ~/Documents/default-work.wayscriber-session
wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session
wayscriber --session-info --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --clear-session --session-file ~/Documents/lecture-04.wayscriber-session

--session-file uses the exact selected file, implies persistence for that run, and conflicts with --no-resume-session. Launch, Open, and Save As flows require an existing parent directory. --session-info and --clear-session can still inspect or clean up stale named-session paths after the parent directory is gone.

If a daemon overlay is already visible with one named session, hide it before toggling to a different named session target.

Open the top strip’s overflow menu and choose Session…. Use this popover for the active session you are working in now:

Open loads an existing named session and records it in recent sessions.
Save As writes the current overlay to another named session and switches the active target. If no extension is supplied, Wayscriber appends .wayscriber-session; if target artifacts already exist, it asks before replacing them.
Info reports the active session file size, board shape counts, and history status.
Clear removes saved data for the active target.
Recent session rows reopen named sessions you used earlier.
Manager opens the configurator Session tab.

The Open and Save As file pickers use zenity first, then fall back to kdialog when available.

Configurator Session tab

The configurator manages default persistence settings and the named-session catalog. Named sessions are recorded when they are opened or saved from the CLI, daemon, or overlay Session popover.

Catalog actions:

Save Name changes only the catalog display label.
Reveal File opens the session file location.
Forget removes catalog metadata without deleting session files.
Duplicate copies an inactive session’s primary file to a new named target.
Move relocates an inactive session file and its non-lock sidecars.
Clear Saved Data removes saved data for that catalog entry.

Duplicate, Move, and Clear Saved Data are offline file-maintenance actions. They are disabled while an overlay, manually started daemon, or background service is active. Use Save As from the overlay for the currently active session, or stop the overlay/service before changing inactive files from the configurator.

Boards and Modes

Wayscriber uses named boards plus pages. Each board has its own canvas, pages, and undo history, so you can keep separate workspaces without losing work.

Boards

Boards can be transparent overlays or solid-color backgrounds.
Solid-color boards can be panned for more room with Space + left-drag.
Use the board picker to switch, rename, recolor, pin, or reorder boards.
Quick slots jump to boards 1-9, and you can cycle or create boards from the keyboard.
The legacy whiteboard/blackboard toggles still work as shortcuts.

Default board keys

Board picker: Ctrl+Shift+B
Jump to board slot: Ctrl+Shift+1..9
Previous/next board: Ctrl+Shift+Left / Ctrl+Shift+Right
New/duplicate/delete board: Ctrl+Shift+N / Ctrl+Shift+D / Ctrl+Shift+Delete
Whiteboard / blackboard / transparent: Ctrl+W / Ctrl+B / Ctrl+Shift+T

Board picker shortcuts

Navigate: Up/Down, Home/End
Switch: Enter or Space
Search: type to match a board name or slot number (Backspace edits, Esc clears then closes)
Edit: Ctrl+N new, Ctrl+R or F2 rename, Ctrl+C recolor, Ctrl+P pin, Delete removes

Solid-board pan

Hold Space and drag with the left mouse button on whiteboards and other solid-color boards.
Transparent overlay stays fixed to the live screen and does not pan.
Right-click includes Reset Canvas Position plus a Zoom submenu with Zoom In, Zoom Out, and Reset Zoom.
Pan offset is stored per page, so each page remembers its own board position.

Config notes

Prefer the [boards] section for named boards, backgrounds, and defaults.
The legacy [board] section still exists for white/blackboard settings and is what the configurator edits today.

Tools and Shapes

Wayscriber focuses on fast input with modifier drags plus toolbar or hotkey tool selection.

Drawing tools

Pen: drag (default)
Line: Shift + drag (or select Line tool)
Rectangle: Ctrl + drag
Ellipse: Tab + drag
Arrow: Ctrl+Shift + drag
Marker: H (translucent)
Highlight-only tool: Ctrl+Alt+H (click highlight only)
Eraser: D (toggle brush/stroke with Ctrl+Shift+E)
Step marker tool: place numbered bubbles (toolbar tool)

Drag modifier mappings can be changed in config or the configurator. For per-button workflows, configure left, right, and middle drag bindings separately, including optional colors.

Numbered callouts

Arrow labels: enable Auto-number in the arrow toolbar section and use Reset to restart at 1.
Step markers: the Step Marker tool increments automatically; use Reset in the toolbar (or bind reset_step_markers).

Text and notes

Text: press T, click to place, type, press Enter
Sticky note: press N, click to place, type, press Enter
Shift+Enter adds a newline while editing text

Selection and editing

Hold Alt to select and move shapes (or use the Select tool).
Select tool: V
Shift+click adds items to the selection.
Right click (while idle), Shift+F10, or Menu opens the context menu.
Ctrl+Alt+P toggles the selection properties panel (fill, arrow heads, text background, size).
Duplicate: Ctrl+D
Copy selection: Ctrl+Alt+C
Paste selection or copied PNG/JPEG image: Ctrl+Alt+V
Context menus expose Paste; shape menus also expose Copy for selected annotations.
Nudge: Arrow keys (Shift for larger steps)

Quick controls

Colors: R/G/B/Y/O/P/W/K
Screen eyedropper: I, the eyedropper button in the toolbar or color picker, or Pick screen color from Ctrl+K
Thickness: + or = / - or _ (or scroll)
Presets: 1-5 apply, Shift+1-5 save
Command palette: Ctrl+K (type to search actions)
Reset arrow labels: Ctrl+Shift+R

Screen eyedropper

The screen eyedropper samples a drawing color from the captured desktop currently displayed through Wayscriber. Move the crosshair to inspect the magnified pixel loupe, then click or tap to apply the selected color. Escape or right-click cancels without changing the color.

The default shortcut is I. Rebind it if you prefer another key:

[keybindings.colors]
pick_screen_color = ["I"]

On a transparent overlay, Wayscriber can briefly freeze the desktop when it needs a clean image to sample. On a solid board, use an already active screen freeze; the eyedropper cannot sample a desktop image hidden by an active zoom on a solid board.

Open/close: middle-click while idle.
The eight tool directions form a fixed compass, so positions do not reflow.
Hold middle-click, flick toward a tool wedge, and release to commit without waiting for the menu to paint. Release in the center to cancel.
Hover to preview; left-click applies a tool or color in the fully opened menu.
Right-click or Escape dismisses the menu.
Drag the outer size ring or scroll to adjust thickness/eraser size.
The color ring includes session-recent colors without duplicating quick colors.
Shapes opens a sub-ring from the shared shape catalog; the notes direction contains Step Marker and Sticky Note.

Use F1 for the full help overlay (or F10). Shift+F1 opens the quick reference.

Capture

Wayscriber includes fast screenshot capture tools that can save to file and/or clipboard.

Dependencies

Capture uses wl-clipboard, grim, and slurp for best results. If you build from source or use the tarball, install them as listed in the Installation guide (Build from source section).

If these are missing, Wayscriber falls back to xdg-desktop-portal. GNOME freeze uses the screenshot portal when available; the first use may show a desktop permission prompt and can be slower than compositor screencopy.

On wlroots compositors, freeze and zoom use the shared-memory screencopy path. If capture features fail on a newer Sway/wlroots stack, update Wayscriber first; current builds avoid the dmabuf-only screencopy path that older builds could not consume.

Default capture keys

Full screen: Ctrl+Shift+P
Active window (Hyprland only): Ctrl+Shift+O
Selection: Ctrl+Shift+I

Clipboard and file variants

Clipboard full screen: Ctrl+C
File full screen: Ctrl+S
Clipboard selection: Ctrl+Shift+C
File selection: Ctrl+Shift+S
Clipboard region: Ctrl+6
File region: Ctrl+Alt+6
Open capture folder: Ctrl+Alt+O

Presenting and Teaching

Recommended setup

Run the daemon so the overlay is instant.
Bind a single key to toggle the overlay.
Use whiteboard or blackboard for long explanations and transparent mode for quick callouts.
Keep the status bar and toolbars on until the controls feel automatic.

Before you present

Start the daemon ahead of time and do a quick toggle test.
Pick a thicker pen size for visibility on streams and recordings.
If you rely on click highlights, enable them in the configurator or toggle with Ctrl+Shift+H.
Presenter mode hides UI chrome and can force click highlights, so test it once before going live.
Teaching shortcuts? Turn on the input HUD (Ctrl+Shift+K) so the audience sees the keys and clicks you are describing.

During the session

Freeze the screen to explain without the background moving.
Zoom for details, then reset to keep orientation. Lock zoom to pan around without drifting.
Use presenter mode when you want a clean, distraction-free view.
Drop step markers or auto-numbered arrows for clear step-by-step callouts.
Clear the canvas when a section is done so the next topic is clean.

Helpful keys

Help: F1 (F10 is the alternative)
Show/hide toolbars: F9
Cycle top strip full/micro/hidden: F2
Status bar: F4 (F12 is the alternative)
Presenter mode: Ctrl+Shift+M
Click highlights: Ctrl+Shift+H
Input HUD: Ctrl+Shift+K
Freeze: Ctrl+Shift+F
Zoom: Ctrl+Alt + scroll (Ctrl+Alt+0 to reset, Ctrl+Alt+L to lock)
Board picker: Ctrl+Shift+B
Clear canvas: E

Recording and Streaming

Tips for recording:

Use daemon mode so your overlay is ready before you start recording.
Prefer whiteboard or blackboard for clear contrast.
Use thicker strokes for visibility at lower resolutions.
Turn on the input HUD (Ctrl+Shift+K) so viewers can see the shortcuts you press.

Showing keystrokes and clicks

The input HUD draws a row of keycap-style chips for the keys, mouse buttons, and scroll ticks you press, fading out a moment later. It has two sources, because a Wayland client only receives input aimed at its own surfaces:

Overlay (works everywhere, no permissions): everything Wayscriber itself receives. That covers the usual case of annotating while you talk.
System (opt-in build, needs read access to /dev/input): every key and button on your seat, including what goes to the app underneath while light passthrough is on.

Set the source with ui.input_hud.mode; the default auto uses system-wide capture when it is available and falls back to overlay-only without complaining. See Config Reference for anchor, timing, and content options.

System mode sees every keystroke on your seat, including passwords typed into other applications. It is off by default and one shortcut turns it off again.

If your capture tool records the overlay, it will appear in your final video by default.

Multi Monitor Tips

What this feature is for

Keep one annotation workflow while moving focus between displays.
Preserve per-display canvas/session state when session.per_output = true.
Keep toolbar + status UI aligned with the output you are actively drawing on.

Default shortcuts

Previous output: Ctrl+Alt+Shift+ArrowLeft
Next output: Ctrl+Alt+Shift+ArrowRight
Command palette: Ctrl+K, then search monitor or display

Config knobs

ui.multi_monitor_enabled = true enables output focus cycling.
ui.active_output_badge = true shows current output in the status bar.
session.per_output = true keeps separate session files per monitor.
ui.preferred_output = "eDP-1" (optional) pins GNOME fallback to a target monitor.

GNOME / xdg fallback

Output naming is compositor-dependent. Use ui.preferred_output (or env override) when startup monitor choice is not what you want.
Env override: WAYSCRIBER_XDG_OUTPUT=<output-name>

Quick test checklist

Start on monitor A and draw a few strokes.
Press Ctrl+Alt+Shift+ArrowRight to move output focus to monitor B.
Confirm toolbar/status now render on monitor B.
Draw on monitor B, then switch back with Ctrl+Alt+Shift+ArrowLeft.
Confirm monitor A canvas is intact and monitor B canvas is unchanged.

Troubleshooting

Output switch does not trigger: verify ui.multi_monitor_enabled = true.
Wrong display on GNOME: set ui.preferred_output or WAYSCRIBER_XDG_OUTPUT.
Unexpected cross-monitor canvas restore: confirm session.per_output is set the way you want.

Compositor Guides

Hyprland

For Hyprland Lua, put daemon autostart and the toggle keybind in the matching files:

-- ~/.config/hypr/autostart.lua
o.launch_on_start("wayscriber --daemon")

-- ~/.config/hypr/bindings.lua
o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

Traditional Hyprland config:

exec-once = wayscriber --daemon
bind = SUPER, D, exec, wayscriber --daemon-toggle

Reload Hyprland with hyprctl reload. Define the toggle binding only once. If Hyprland does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber.

Light passthrough should use compositor-level binds because the overlay passes normal input to the app underneath. Do not rely on the in-overlay F6 shortcut to get back out after passthrough starts.

Hyprland Lua (~/.config/hypr/bindings.lua):

local wayscriber = "wayscriber"

o.bind("F6", "Toggle Wayscriber light passthrough", wayscriber .. " --light-toggle")
o.bind("XF86Tools", "Toggle Wayscriber light passthrough", wayscriber .. " --light-toggle")
o.bind("SUPER + ALT + D", "Toggle Wayscriber light drawing", wayscriber .. " --light-draw-toggle")

Traditional Hyprland config:

$wayscriber = wayscriber

unbind = SUPER ALT, L
bind = SUPER ALT, L, exec, $wayscriber --light-toggle
unbind = SUPER ALT, D
bind = SUPER ALT, D, exec, $wayscriber --light-draw-toggle
unbind = SUPER ALT, F
bind = SUPER ALT, F, exec, $wayscriber --light-draw-on
bindr = SUPER ALT, F, exec, $wayscriber --light-draw-off

# Optional lower side mouse button, commonly mouse:275
bind = , mouse:275, exec, $wayscriber --light-toggle

GNOME

Use Settings -> Keyboard -> Custom Shortcuts.

Choose one of these commands:

One shot: wayscriber --active
Daemon toggle: wayscriber --daemon-toggle (run the daemon first)

If you want fullscreen on GNOME, set WAYSCRIBER_XDG_FULLSCREEN=1. If GNOME renders fullscreen as opaque, leave it off or force it with WAYSCRIBER_XDG_FULLSCREEN_FORCE=1.

To target a specific monitor, set WAYSCRIBER_XDG_OUTPUT to a matching output name.

Freeze works on GNOME when the screenshot portal is available and responsive. The first freeze may show a desktop permission prompt, and portal capture can be slower than layer-shell compositor capture.

Light passthrough is not currently available on GNOME sessions that use Wayscriber’s xdg-shell fallback. The fallback cannot reliably pass keyboard input through, so wayscriber --light-toggle is intentionally disabled there.

KDE

Use System Settings -> Shortcuts -> Custom Shortcuts.

Choose one of these commands:

One shot: wayscriber --active
Daemon toggle: wayscriber --daemon-toggle (run the daemon first)

Light passthrough controls are manual for now: add global shortcuts that run wayscriber --light-toggle and wayscriber --light-draw-toggle. Draw-while-held needs a shortcut system that can run wayscriber --light-draw-on on press and wayscriber --light-draw-off on release; otherwise use the sticky draw toggle. Light passthrough requires layer-shell support.

Configurator (GUI)

Wayscriber has a native configurator for editing settings without touching the config file by hand. It writes authored defaults to config.toml; direct overlay preferences are layered separately as runtime UI state.

Launch

Press F11 inside the overlay
Or run wayscriber-configurator

If the configurator is not installed, install wayscriber-configurator or point to it with WAYSCRIBER_CONFIGURATOR.

The search field is meant for direct keyboard use:

Start typing after launch to filter settings.
Press Ctrl+F to focus search again.
Press Escape in search to clear it and keep typing.
Search matches tabs, sections, saved sessions, boards, render profiles, presets, and keybinding names.
Scoped searches work, for example ui toolbar blur, session lecture, keybinding capture, or preset red.

When a result belongs to a nested settings page, selecting it opens the matching tab or subtab.

What you can change

Drawing defaults: color, thickness, marker opacity, fill, font family/weight/style, text background, drag tool bindings
Arrow settings: length, angle, head placement
Performance: buffer count and vsync
UI: dark/light theme, reduced motion, interactive status HUD, help overlay styling, click highlight settings (including highlight ring), frozen badge, and context menu
UI toolbar: pill/legacy-panel side layout, layout complexity, top-strip display, section visibility (boards, pages, presets, actions, zoom, step controls), ink-preview cursor, marker opacity slider, preset toasts, per-item visibility, and saved toolbar order
History: undo/redo delay playback and Step control defaults
Board modes (legacy): enable, default mode, board colors, auto adjust pen color
Capture: enable, save directory, filename template, format, clipboard behavior, exit after capture
Session: per mode persistence, restore tool state, per output, storage mode, size limits, compression, backups, and named-session catalog management
Presets: edit slot definitions and defaults
Keybindings: edit all shortcuts by category

Note: full multi-board setup lives under [boards] in config.toml and currently needs manual editing (or the in-app board picker with boards.persist_customizations = true).

The UI tab controls broad toolbar behavior such as the default contextual-pill versus legacy-panel layout, Simple/Regular/Advanced complexity, pinned startup state, full/micro top-strip display, icon-only mode, section toggles, context-aware UI, ink-preview cursor, offsets, and force-inline mode.

Under pill mode, the Boards, Pages, Advanced, Zoom, Step, and delay visibility toggles control sections in the top-strip Canvas… popover. The Zoom toggle also controls the persistent bottom-right zoom chip.

The UI -> Toolbar Visibility subtab controls individual toolbar items. Checked means shown. Uncheck an item to remove it from toolbar sizing, drawing, and hit testing. Explicit visibility choices survive changes between the Simple, Regular, and Advanced layout presets.

Order controls are available for:

Top tools
Top controls
Side sections

Use the up/down controls to move an item within its group, or reset a group back to the built-in order. Configurator changes are written as authored defaults to ui.toolbar.items.order in config.toml.

The overlay also has toolbar customization. In the default pill layout:

Open the top strip’s overflow menu, choose Settings…, then use Customize.
Pick a group such as Top tools, Top controls, Side sections, Actions, Pages, Boards, Presets, Tool options, or Sessions.
Toggle items to show/hide them.
Move supported Top tools, Top controls, and Side sections up/down or drag rows to reorder them.
Reset hidden items or reset an order group when you want the defaults back.

Under legacy side_layout = "panel", the same editor remains in the Settings pane. That panel also has a Sections tab and collapsible side-section headers.

Overlay changes to individual item visibility/order, toolbar pins, minimized and pane state, collapsed side sections, and board pins are stored in generated $XDG_DATA_HOME/wayscriber/runtime-ui.toml state. Authored section-visibility toggles still update config.toml. Overlay Settings shows whether runtime persistence is available and provides reset, retry, disk-adoption, and invalid-file recovery actions. See Config File Overview.

The screenshot toolbar button is hidden by default. Enable top.utility.screenshot from Toolbar Visibility or remove it from ui.toolbar.items.hidden in TOML to show it. See Toolbars for the runtime layout and frontend behavior.

Session catalog

The Session tab manages both default persistence settings and the named-session catalog. Named sessions are recorded when they are opened or saved from the CLI, daemon, or overlay Session popover. See Sessions and Session Manager for the full workflow.

Catalog actions:

Save Name changes only the display label.
Reveal File opens the session file location.
Forget removes catalog metadata without deleting the files.
Duplicate copies an inactive session to a new named target.
Move relocates an inactive session file and its non-lock sidecars.
Clear Saved Data removes saved data for that catalog entry.

Duplicate, Move, and Clear are disabled while an overlay, manually started daemon, or background service is active. Stop the overlay or service before doing offline file maintenance from the configurator.

Workflow

Reload: re-read the config from disk
Defaults: load built-in defaults without saving
Save: validate inputs and write the config with a backup

Config File Overview

The config file lives at:

~/.config/wayscriber/config.toml

To start from the defaults:

mkdir -p ~/.config/wayscriber
cp /usr/share/doc/wayscriber/config.example.toml ~/.config/wayscriber/config.toml

If you built from source, use the repo file at config.example.toml. Some distros may install the example under /usr/share/doc/wayscriber/ (path can vary by package).

Applying changes

Use the configurator when you want validation and backups:

wayscriber-configurator

Or edit TOML directly and restart the running overlay or daemon:

systemctl --user restart wayscriber.service

For one-shot mode, close Wayscriber and start it again.

Configured defaults and runtime UI preferences

config.toml is the authored source for configured defaults. The configurator edits those defaults. Wayscriber stores some direct overlay customizations separately so a pin, collapse, or reorder action does not rewrite unrelated configuration:

top and side toolbar pin and minimized state;
the active legacy side pane and collapsed side sections;
individual toolbar item visibility and toolbar item order; and
per-board pin state.

The generated file is $XDG_DATA_HOME/wayscriber/runtime-ui.toml, normally ~/.local/share/wayscriber/runtime-ui.toml. Treat it as application state, not as a second configuration file, and do not hand-edit it. The configured values act as startup seeds; retained runtime overrides are applied on top. Toolbar drag positions and authored choices such as toolbar layout and section visibility still update their corresponding fields in config.toml.

Open the overlay’s Settings… popover to see the complete runtime-state path and status, reset runtime preferences, or recover from a failed save. A newer file version is kept read-only. Resetting a newer or invalid file requires confirmation and first preserves its exact bytes in a recovery artifact whose path is shown in Settings.

Writes are conditional on the exact file and parent directory that Wayscriber inspected. If another process changes or retargets the path, Wayscriber does not overwrite it; it blocks further runtime preference changes until you retry or adopt the freshly inspected disk state. If runtime-state persistence cannot start, overlay changes remain process-only and Settings reports that they will not survive restart.

Low-latency drawing

For live demos, teaching, and screen annotation, use low-latency mode when input responsiveness matters more than tear-free presentation:

[performance]
buffer_count = 3
enable_vsync = false
max_fps_no_vsync = 240
ui_animation_fps = 60

This is a high-refresh example. max_fps_no_vsync controls the drawing redraw cap when vsync is off; use 120 (the default) on common systems, or try 144, 165, 240, or higher if it matches your display and the machine handles the extra rendering work. Use max_fps_no_vsync = 0 only for profiling, because uncapped rendering can spin CPU/GPU hard.

ui_animation_fps controls toolbar and UI effects, not the drawing FPS cap. 60 makes those effects smoother than the default 30, at the cost of extra redraws while animations are active.

Keep buffer_count = 3 unless you have a specific reason to tune it. It is the balanced default: 2 uses less render-buffer memory, while 4 uses more. Buffer count affects how many render buffers are available; it does not raise the FPS cap by itself.

If tear-free presentation matters more than input latency, turn vsync back on:

[performance]
enable_vsync = true

Disabling vsync improves input latency but may allow tearing and higher CPU/GPU usage. Enabling vsync gives smoother tear-free synchronization, but usually adds a frame-cadence floor, especially on 60 Hz displays.

Wayscriber’s perf logging can be enabled with:

WAYSCRIBER_PERF_LOG=1 wayscriber

The relevant line is:

perf.input_to_paint_latency proxy=input_to_wayland_commit

This is an input-to-Wayland-commit proxy metric: it measures from input sample receipt inside the app to Wayland surface commit. Wayland compositor scheduling, display scanout, and hardware can add more latency outside the app. In local continuous-drawing measurements, 120 FPS low-latency mode held p95 around 8-9 ms and p99 around 8-9 ms for this proxy metric; isolated max spikes existed, but p99 stayed under 16 ms.

Interface layout and motion

The redesigned interface is configured under [ui] and [ui.toolbar]:

[ui]
theme = "auto"              # auto, dark, or light; auto currently resolves to dark
reduced_motion = "auto"     # auto, on, or off; on disables UI animation
status_bar_interactive = true

[ui.toolbar]
layout_mode = "regular"     # simple, regular, or advanced complexity
side_layout = "pill"        # pill (default) or deprecated panel
top_display_mode = "full"   # full or micro at startup
show_presets = true
show_zoom_actions = true      # Canvas Zoom section + bottom-right zoom chip
show_tool_preview = false

side_layout and layout_mode solve different problems. The default pill side layout removes the standalone side palette: drawing properties move into the contextual style pill; canvas management moves into the Canvas… overflow popover, bottom-right zoom chip, and chip-HUD board picker; presets move into the top strip; and Session / Settings move into overflow popovers. panel restores the legacy four-pane side palette and shows a once-per-session map to these replacement surfaces.

The Canvas popover’s Boards, Pages, Advanced, Zoom, and Step Undo/Redo sections reuse the existing show_* toggles. In particular, show_zoom_actions controls both the popover’s Zoom row and the persistent ⊖ NN% ⊕ Fit chip; Lock appears while zoomed. No new configuration key is required.

layout_mode changes only the baseline complexity of visible sections. Explicit item visibility choices survive switching between Simple, Regular, and Advanced. Changes made in the configurator are authored defaults; item visibility changes made from the overlay are runtime overrides stored in runtime-ui.toml.

F9 toggles toolbar visibility. F2 cycles the top strip through full, a 44px active- tool micro chip, and hidden. The full/micro choice persists; the hidden cycle step does not. When show_tool_preview = true, the cursor preview uses the active color and width, adds the tool glyph, and outlines itself for contrast.

Hide individual toolbar items or whole side sections with stable IDs:

[ui.toolbar.items]
hidden = [
  "top.utility.screenshot",
  "top.tool.blur",
  "top.group.quick-colors",
]
shown = []

Checked in the configurator means shown. IDs in hidden are explicitly hidden; IDs in shown stay visible against the Simple/Regular/Advanced layout baseline. These explicit choices survive layout-mode changes. Unknown future IDs are preserved across saves so newer configs do not get destroyed by an older binary.

The same controls in the overlay’s Customize view create runtime overrides instead of rewriting these lists. Use Reset runtime preferences in overlay Settings to return to the configured visibility and order defaults.

top.group.quick-colors controls the quick swatches in the contextual style pill. The current-color chip stays visible so the full picker remains reachable. The 3–5-slot presets island follows show_presets rather than a per-slot item ID.

Reorder the supported groups with ui.toolbar.items.order:

[ui.toolbar.items.order]
top_tools = [
  "top.tool.select",
  "top.tool.pen",
  "top.tool.marker",
  "top.tool.eraser",
]

top_controls = [
  "top.utility.text",
  "top.utility.sticky-note",
  "top.utility.screenshot",
  "top.utility.clear-canvas",
]

side_sections = [
  "side.group.colors",
  "side.group.thickness",
  "side.group.actions",
  "side.group.pages",
  "side.group.boards",
  "side.group.settings",
]

Empty lists use the built-in order. Known IDs omitted from a non-empty list are appended in their default order. Side section ordering uses runtime section blocks; detailed tool-option sections such as eraser mode, polygon sides, and font can be hidden but are not independently orderable.

Named sessions

Default persistence is configured under [session]:

[session]
persist_transparent = true
persist_history = true
restore_tool_state = true
per_output = true
storage = "auto"
max_file_size_mb = 50

Use --session-file when you want a named session for a lecture, meeting, or project:

wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session
wayscriber --session-info --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --clear-session --session-file ~/Documents/lecture-04.wayscriber-session

--session-file uses the exact selected file and implies persistence for that run. It does not create missing parent directories, rejects directories/symlinks/special files for foreground Open/Save As flows, and conflicts with --no-resume-session.

See Sessions and Session Manager for CLI, overlay, and configurator workflows.

Config Reference

This is a compact map of the config file. For the full list of settings, see config.example.toml in the repo.

drawing

Defaults for pen color/thickness, eraser behavior, marker opacity, fill, font options, hit testing, and undo limits. Use drawing.drag_tools to customize drag mappings per left, right, or middle mouse button, including optional colors for each modifier binding.

presets

Quick tool slots for saving full per-tool profile snapshots. Current presets can include tool_settings and drag bindings; legacy presets with only tool/color/size still work.

arrow

Arrowhead length, angle, and head placement.

performance

Buffer count, vsync, max fps, and UI animation fps.

buffer_count = 3 is the balanced default. 2 uses less render-buffer memory and 4 uses more; increasing it does not increase the FPS cap.
enable_vsync = false enables low-latency drawing by avoiding the compositor frame-callback/vsync cadence floor.
max_fps_no_vsync = 120 caps no-vsync rendering. Use 144, 165, 240, or higher only when it matches the display and the machine handles it.
max_fps_no_vsync = 0 is uncapped and is mostly for profiling; avoid it as a normal default because it can spin CPU/GPU hard.
ui_animation_fps = 30 is the default for toolbar and UI effects. Raise it to 60 for smoother effects at the cost of more redraws; it does not change the drawing FPS cap.
Set enable_vsync = true when tear-free presentation matters more than input latency.

With WAYSCRIBER_PERF_LOG=1, the perf.input_to_paint_latency proxy=input_to_wayland_commit line reports an input-to-Wayland-commit proxy metric. It is not end-to-end display latency; compositor scheduling and display scanout can add more latency outside Wayscriber.

history

Undo/redo playback delays and the optional Step toolbar section.

ui

Theme/motion preferences, status HUD toggles, badges, help overlay filtering, and GNOME output/fullscreen hints.

theme = "auto" | "dark" | "light" selects overlay and toolbar chrome. auto currently resolves to dark.
reduced_motion = "auto" | "on" | "off" controls UI animation. on disables motion; auto currently behaves like off until system-preference integration lands.
status_bar_interactive = true lets the board, page, color, tool, and Help chips open their corresponding surfaces. Set it to false for display-only, click-through HUD. Includes multi-monitor controls:
ui.multi_monitor_enabled (output focus cycling)
ui.active_output_badge (show active output in status bar)
ui.preferred_output (pin GNOME fallback output)

ui.status_bar_style

Font size, padding, and colors for the chip HUD. The HUD degrades to fit 80% of the viewport, while frozen/zoom/pan/editing states stack as badge pills above it.

ui.click_highlight

Click highlight colors, radius, outline thickness, duration, pen-color sync, and the optional persistent ring while the highlight tool is active.

ui.input_hud

The on-screen keystroke/click HUD: enabled, the capture mode (auto | overlay | system), the position anchor (a 3x3 grid from top-left to bottom-right), show_mouse, show_bare_modifiers, combine_repeats, display_ms, fade_ms, max_entries, and font_size. Chips use the status-bar style tokens, so they match the rest of the overlay chrome.

overlay mode shows only what Wayscriber itself receives and needs no permissions. system mode reads /dev/input through libinput to report everything on your seat — including input going to the app underneath during light passthrough — and needs a build with the input-monitor feature plus read access to the input devices, which normally means input group membership:

sudo usermod -aG input "$USER"   # then log out and back in

When that is unavailable, the HUD falls back to overlay mode; auto does so silently, while an explicit system request explains what stopped it. System mode sees every keystroke on the seat, including passwords typed into other applications, so it is off by default and chip labels are never logged or saved.

presenter_mode.enable_input_hud forces the HUD on while presenting.

ui.context_menu

Enable/disable right-click menus.

ui.toolbar

Frontend selection, side-layout placement, layout complexity, full/micro display, section visibility, presets, marker opacity slider, delay sliders, ink preview, minimized state, legacy side-pane state, offsets, and force-inline behavior.

ui.toolbar.backend = "auto" | "gtk" | "builtin": select the toolbar frontend.
ui.toolbar.side_layout = "pill" | "panel": pill is the default and removes the standalone side palette. panel restores the deprecated four-pane palette.
ui.toolbar.layout_mode = "simple" | "regular" | "advanced": choose the baseline section complexity independently of side_layout (full remains an alias for regular).
ui.toolbar.top_display_mode = "full" | "micro": choose the persisted top-strip form. F2 also reaches a runtime-only hidden step; F9 directly toggles visibility.
ui.toolbar.show_presets: show the 3–5-slot presets island. It drops before other islands under width pressure.
ui.toolbar.show_zoom_actions: show both the Zoom section in the Canvas… overflow popover and the persistent bottom-right zoom chip. The chip shows the live percentage with zoom-out, zoom-in, Fit, and (while zoomed) Lock controls.
ui.toolbar.show_boards_section, show_pages_section, show_actions_advanced, show_step_section, and show_delay_sliders: control the corresponding sections inside Canvas… under pill mode and the classic Canvas pane under panel mode.
ui.toolbar.show_tool_preview: show the active tool glyph beside an ink dot using the current drawing color and width with an automatic contrast outline.
ui.toolbar.items.hidden: stable IDs for hidden toolbar buttons, actions, or side sections.
ui.toolbar.items.shown: explicit items that remain visible against the selected layout preset.
ui.toolbar.items.order.top_tools: saved order for top toolbar tool buttons.
ui.toolbar.items.order.top_controls: saved order for top utility controls.
ui.toolbar.items.order.side_sections: saved order for side toolbar section blocks.

The screenshot button (top.utility.screenshot) is hidden by default. top.group.quick-colors hides the contextual pill’s swatches but keeps its current-color chip. The configurator writes authored visibility and order defaults to config.toml. The overlay Customize view treats those values as seeds and stores direct item visibility and order overrides in the generated runtime-ui.toml file. Authored section-visibility toggles continue to update config.toml. Supported groups can be moved up/down; the overlay also supports drag reorder. Unknown future IDs and fields are preserved across supported-version saves.

Simple, Regular, and Advanced provide non-destructive visibility baselines; explicit shown/hidden choices survive a mode switch. Canvas, Session, and Settings live in top-strip overflow popovers under the default pill layout. See Toolbars.

Generated runtime UI preferences

This is application state, not a config.toml section. Wayscriber writes toolbar pin/minimized state, the active legacy pane and collapsed sections, individual item visibility/order, and per-board pins to $XDG_DATA_HOME/wayscriber/runtime-ui.toml (normally ~/.local/share/wayscriber/runtime-ui.toml). Inspect, recover, or reset it from the overlay Settings popover; do not hand-edit it. See Config File Overview.

ui.help_overlay_style

Font and color styling for the help overlay.

presenter_mode

Hide UI chrome, force click highlights, tool behavior, and presenter toasts.

boards

Named boards, backgrounds, default board, max count, auto-create, pan settings, badges, and persistence.

boards.pan_enabled: enable Space + left-drag panning on solid-color boards.
boards.show_pan_badge: show the pan hint in the status bar or as a floating badge.
Panned solid boards expose Reset Canvas Position and a Zoom submenu from the right-click menu.

board

Legacy whiteboard/blackboard settings (kept for compatibility and configurator support).

tablet

Stylus support when built with the tablet feature flag.

capture

Screenshot enablement, save directory, filename templates, and clipboard behavior. Clipboard paste also accepts copied PNG/JPEG image data and local image files from file managers.

session

Persistence settings, autosave, storage location, per-output, compression, and backups.

restore_tool_state saves the last pen color, thickness, font size, arrow placement, and status bar state.
per_output keeps separate default sessions per monitor when enabled.
storage = "auto" | "config" | "custom" selects the default session directory.
max_file_size_mb, compression, and backup settings protect large or corrupt session files.

Named sessions are selected with --session-file <PATH>, not by adding a path under [session]. The top-strip Session popover can Open, Save As, Info, Clear, reopen recent sessions, and jump to the configurator. The configurator Session tab can rename/reveal/ forget catalog entries and can duplicate, move, or clear inactive session files when no overlay or daemon is running.

updates

Update notifications only — Wayscriber never installs anything.

check = true lets the daemon ask wayscriber.com once per interval whether a newer release exists. WAYSCRIBER_DISABLE_UPDATE_CHECK=1 overrides this for a run.
notify = true shows one desktop notification per release. With it off, the notice still appears in the About window and the tray menu.
interval_hours = 24 sets the gap between checks (minimum 1, maximum 720).

See Updating for what is sent, where the result is cached, and how packagers remove the check at build time.

keybindings

Full keyboard shortcut map, including board/page navigation, selection editing, step markers, arrow label resets, light passthrough (toggle_light_mode), output focus (focus_prev_output / focus_next_output), the command palette, toolbar visibility (toggle_toolbar, default F9), the top-strip cycle (cycle_toolbar_display, default F2), and the screen eyedropper (pick_screen_color).

The screen eyedropper defaults to I and is also available from the toolbar, color picker, and command palette. Rebind it if you prefer another key:

[keybindings.colors]
pick_screen_color = ["I"]

Selection copy/paste defaults to Ctrl+Alt+C / Ctrl+Alt+V; the context menu defaults to Shift+F10 and Menu as keyboard alternatives to right-click.

toggle_light_mode defaults to F6, but that is a Wayscriber in-overlay shortcut. Once light passthrough is active, do not rely on that in-overlay shortcut to get back out; use compositor/global shortcuts that call wayscriber --light-toggle and the light-draw commands.

Full reference: https://github.com/devmobasa/wayscriber/blob/main/config.example.toml

Profiles and Presets

Tool presets (quick slots)

Presets let you save the current drawing profile and switch instantly. Newly saved presets capture the selected tool plus the full per-tool settings profile: colors, sizes, fill, marker opacity, text background, eraser settings, arrow settings, status-bar preference, and drag bindings.

Older presets that only contain tool, color, and size still load with the legacy behavior.

Defaults:

Apply preset 1-5 with keys 1 to 5
Save preset 1-5 with Shift+1 to Shift+5
Open the command palette and search for Save preset to save any slot without memorizing its shortcut

Configure them in config.toml:

[presets]
slot_count = 5

[presets.slot_1]
name = "Red pen"
tool = "pen"
color = "red"
size = 3.0

# Optional full profile saved by current Wayscriber versions.
[presets.slot_1.tool_settings.pen]
color = "red"
size = 3.0

[presets.slot_1.tool_settings.arrow]
color = "yellow"
size = 4.0

With ui.toolbar.show_presets = true, the top strip shows 3–5 slots between the Tools and History islands. Click a filled slot to apply it or an empty slot to save the current profile. Clear presets with their keybindings or from the legacy panel layout. Save Preset 1–5 also appear as normal searchable command-palette actions. Apply/save/clear feedback can use toast notifications. Edit simple names and defaults in the configurator; use config.toml for advanced full-profile fields.

Config profiles (file switching)

Wayscriber uses a single config file. You can simulate profiles by keeping multiple files and symlinking the one you want.

Example:

mkdir -p ~/configs
cp config.example.toml ~/configs/wayscriber-presentation.toml
cp config.example.toml ~/configs/wayscriber-recording.toml

ln -sf ~/configs/wayscriber-presentation.toml ~/.config/wayscriber/config.toml

Switch the symlink and restart Wayscriber to apply the new profile.

CLI Reference

Run wayscriber --help for the full list. Key options:

--daemon, -d: run as background daemon
--daemon-toggle: ask a running daemon to show/hide the overlay
--active, -a: start active (one shot overlay)
--mode <MODE>: initial board id (transparent, whiteboard, blackboard, or a custom id)
--no-tray: disable system tray in daemon mode
--clear-session: delete persisted session data
--session-info: show session paths and status
--session-file <PATH>: use a named session file instead of the configured default session
--freeze: start with frozen background
--exit-after-capture: exit after capture completes
--no-exit-after-capture: keep overlay open after capture
--resume-session: force session resume on
--no-resume-session: force session resume off
--light-toggle: compositor/global shortcut command for light passthrough on/off
--light-draw-toggle: compositor/global shortcut command for sticky drawing in light mode
--light-draw-on / --light-draw-off: press/release commands for draw-while-held light mode
--about: show the About window
--check-update: ask wayscriber.com whether a newer release exists (nothing is installed — see Updating)
--help: show help
--version: show version

Named session examples

wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --freeze --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --daemon --session-file ~/Documents/default-work.wayscriber-session
wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session
wayscriber --session-info --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --clear-session --session-file ~/Documents/lecture-04.wayscriber-session

--session-file uses exactly that file, implies persistence for the run, and conflicts with --no-resume-session. Open/Save As flows require an existing parent directory. --session-info and --clear-session can still inspect or clean up stale paths.

If the daemon overlay is already visible with one named session, hide it before toggling to a different named session target.

See Sessions and Session Manager for overlay and configurator workflows.

Environment Variables

Wayscriber supports optional environment overrides.

Core overrides

WAYSCRIBER_NO_TRAY=1 disables the system tray in daemon mode.
WAYSCRIBER_TRAY_FORCE_PIXMAP=1 disables themed tray icons (useful for Noctalia/Quickshell).
WAYSCRIBER_RESUME_SESSION=1/0 forces session resume on or off for the current run.
WAYSCRIBER_CONFIGURATOR=/path/to/wayscriber-configurator sets the configurator path.
WAYSCRIBER_DISABLE_UPDATE_CHECK=1 stops the background update check for this run. It overrides [updates] check in config.toml; wayscriber --check-update still works. See Updating.

Build-time variables

These are read when Wayscriber is compiled, not when it runs.

WAYSCRIBER_NO_UPDATE_CHECK=1 removes the update check from the build entirely; no config or environment setting can re-enable it.
WAYSCRIBER_INSTALL_SOURCE=apt|rpm|aur|nix|tarball|source records how the package was installed, so the update notice opens the matching instructions.

Desktop integration

WAYSCRIBER_ENABLE_PORTAL_SHORTCUTS=1 opts the daemon into KDE/portal global shortcut handling.
WAYSCRIBER_PORTAL_SHORTCUT=Meta+Shift+D stores the shortcut label used by the portal setup.

Logging

WAYSCRIBER_LOG_FILE=/path/or/dir writes overlay logs to a specific file or directory.
WAYSCRIBER_LOG_MAX_SIZE_MB=10 caps each log file before rotating to a new one.

GNOME and xdg-shell fallback

WAYSCRIBER_XDG_OUTPUT=NAME selects a preferred output by name.
WAYSCRIBER_XDG_FULLSCREEN=1 requests fullscreen overlay.
WAYSCRIBER_XDG_FULLSCREEN_FORCE=1 forces fullscreen even if GNOME warns about opacity.

UI and debug

WAYSCRIBER_FORCE_INLINE_TOOLBARS=1 forces inline toolbars.
WAYSCRIBER_TOOLBAR_BACKEND=auto|gtk|builtin overrides the configured toolbar frontend.
WAYSCRIBER_TOOLBAR_DRAG_PREVIEW=0 disables inline toolbar drag preview.
WAYSCRIBER_TOOLBAR_POINTER_LOCK=1 enables pointer-lock drag path (experimental).
WAYSCRIBER_TOOLBAR_DRAG_THROTTLE_MS=12 throttles toolbar drag updates; set 0 to disable throttling.
WAYSCRIBER_TOOLBAR_DRAG_HANDOFF_MS=250 controls the drag handoff timeout.
WAYSCRIBER_DEBUG_DAMAGE=1 enables debug damage output.
WAYSCRIBER_DEBUG_TOOLBAR_DRAG=1 enables toolbar drag logging.
WAYSCRIBER_DEBUG_TOOLBAR_COLOR=1 enables toolbar color-picker logging.
RUST_LOG=info enables Rust logging (use wayscriber=debug for app-level logs).

Systemd Service

If your package installs the user service, you can manage Wayscriber with systemd. On NixOS the unit ships with the project flake package and only becomes visible to systemctl once it is registered with systemd.packages.

Enable and start:

systemctl --user enable --now wayscriber.service

Status and logs:

systemctl --user status wayscriber.service
journalctl --user -u wayscriber.service -f

Restart:

systemctl --user restart wayscriber.service

If the service is not installed, run the daemon manually with wayscriber --daemon.

Common Issues

Overlay does not appear

Confirm you are on Wayland.
Run wayscriber --active from a terminal to see errors.

Keybind does not toggle

Make sure the daemon is running.
Check your compositor shortcut settings.
Verify the command is wayscriber --daemon-toggle.
Make sure you only defined the toggle once.
If the overlay appears and immediately disappears, look for duplicate shortcut entries or key-repeat bursts.
If the shortcut environment cannot find wayscriber, use the absolute path from command -v wayscriber.

Tray icon is missing

Some panels hide StatusNotifier icons.
Run with --no-tray if you do not need the tray.
If the tray icon is blank or the menu shows square placeholders (Noctalia/Quickshell), start the daemon with WAYSCRIBER_TRAY_FORCE_PIXMAP=1.

Capture shortcuts do nothing

Ensure wl-clipboard, grim, and slurp are installed (see Installation → Build from source if you are not using packages).
Check your config under [capture].
On GNOME, portal capture may ask for permission and can be slower. If freeze does not start, check the desktop portal service.
On newer Sway/wlroots stacks, update Wayscriber before debugging deeper; older builds could bind a screencopy path that did not provide the shared-memory frames Wayscriber needs.

Configurator does not launch

Install wayscriber-configurator.
Or set WAYSCRIBER_CONFIGURATOR to its path.

Logs and Debugging

Live logs

Run Wayscriber with logs:

RUST_LOG=info wayscriber --active

If you use the systemd service:

journalctl --user -u wayscriber.service -f

Log files (daemon/active)

When you run --daemon or --active, Wayscriber also writes log files to:

~/.local/share/wayscriber/logs/

This follows XDG_DATA_HOME when set.

Overrides:

WAYSCRIBER_LOG_FILE=/path/or/dir sets a specific file or directory.
WAYSCRIBER_LOG_MAX_SIZE_MB=10 caps each log file before rotating.

Include log output when reporting bugs. See Report a Bug.

Known Limitations

Wayland only. X11 is not supported.
Full overlay behavior requires layer-shell. Known-good layer-shell targets include Hyprland, Sway, River, Wayfire, Niri/COSMIC, and KDE Plasma/KWin.
GNOME uses the xdg-shell/portal fallback, so some fullscreen and input behavior differs.
Light passthrough requires layer-shell. It is disabled on the xdg-shell fallback because keyboard passthrough cannot be made reliable there.
Some compositors handle fullscreen or input differently.
The input HUD can only show the input Wayscriber itself receives unless system-wide capture is available: a Wayland client cannot see another app’s keystrokes. System mode needs a build with the input-monitor feature and read access to /dev/input (usually input group membership); without both, the HUD reports overlay input only. In system mode the keyboard layout comes from the environment (XKB_DEFAULT_LAYOUT and friends), which can differ from the compositor’s live layout.
Capture shortcuts need external tools for best results (see Installation → Build from source if you are not using packages).

Report a Bug

Start here: wayscriber.com/report. It has the button that opens a prefilled bug form, and it lists every other way to reach the project.

You can also start from inside Wayscriber: open the About dialog (wayscriber --about, or About from the tray menu) and click Report a problem. That copies your app details to the clipboard and opens the same page with the details already attached.

What to include

You do not need all of this. The first item alone is a real report.

What you did, and what happened instead. One or two sentences in your own words.
Your app details. In About, click Copy diagnostics and paste the result. It contains your version, install source, desktop, and which features the binary was built with — nothing personal.
Steps to reproduce, if you can find them. “It happens every time I press the hotkey on my second monitor” is a good step list.
Logs, if you can get them. See Logs and Debugging.

Not sure it is a bug?

Ask in Discussions instead. Questions are welcome, and “is this expected?” is a fair question.

Check Common Issues and Known Limitations first if you want — but do not let that stop you from asking.

Asking for a feature

That is a different form. See How to Ask for Features.

What happens after you file

A human reads it. You may get a follow-up question. A fix may take a while, or the request may not fit the project — that is normal and not personal. See The Gift Exchange.

FAQ

Does Wayscriber work on X11

No. Wayscriber is Wayland only.

Do I have to run the daemon

No. Use wayscriber --active for one shot mode.

Where is the config file

Authored defaults live in ~/.config/wayscriber/config.toml. Direct overlay preferences such as toolbar pins, minimized state, individual item visibility/order, and board pins are generated separately at $XDG_DATA_HOME/wayscriber/runtime-ui.toml (normally ~/.local/share/wayscriber/runtime-ui.toml). Inspect or reset that application state from overlay Settings instead of editing it by hand.

Does it work on GNOME and KDE

KDE Plasma/KWin is a known-good layer-shell target. GNOME works through Wayscriber’s xdg-shell/portal fallback, so normal overlay toggling works but light passthrough is disabled and fullscreen/input behavior can vary.

Does Wayscriber phone home

Only to answer “is there a newer release?”, and only if you leave that on. By default, once a day the daemon requests one static file, https://wayscriber.com/latest.json, and compares the version in it to the running build. The request carries no Wayscriber or user identifier, no Wayscriber version, and no query parameters; the HTTP client’s version is suppressed too. Nothing is ever downloaded or installed. Turn it off with [updates] check = false, WAYSCRIBER_DISABLE_UPDATE_CHECK=1, or a build with the check compiled out — see Updating. No other feature contacts the network.

Release Notes

These docs track the latest source. Current source version: v0.9.23.

v0.9.23 highlights

Runtime UI preferences now live in runtime-ui.toml, while config.toml remains the authored configuration. Saves preserve comments and formatting, write only the setting that changed, detect races and external edits, and keep rollback and recovery paths safe.
The annotation workspace has a new top-strip layout with configurable status-bar contents, Focus Mode, persistent chrome controls, a layout-cycle button, discoverable hidden controls, improved popover navigation, and a zoom-control surface.
Text tools now support Wayland IME input, key repeat, caret editing, selection, and clipboard operations. The configurable input HUD can show keystrokes and clicks during presentations.
Drawing tools gained tapered arrows, blur-redaction styles, a spotlight tool, RGBA colors, and persistent recent colors.
About and update notices are more useful and privacy-conscious, with opt-out controls and diagnostics. Release binaries now embed GTK4 layer-shell support, with Nix packaging parity checks and broader daemon, capture, and event-loop reliability improvements.

About window and update notices

The About window was rebuilt: themed chrome that follows [ui] theme, an icon header with version and build metadata, keyboard-navigable link rows (Tab/Enter/Esc), and a “Copy diagnostics” button that puts build, install source, desktop, and compiled features on the clipboard in one paste. The window now sizes itself to its content.
Links point only at wayscriber.com — website, documentation, release notes, and update instructions. The GitHub link is gone.
Wayscriber can now tell you that a newer release exists. It never installs anything: the notice appears as a card in the About window, an item in the tray menu, and at most one desktop notification per release (suppressed while the overlay is active), each opening the Updating instructions for your install method.
The check is one HTTPS request for a static file, made through the system curl/wget, with no Wayscriber or user identifier; the HTTP client’s version is suppressed too. Configure it under [updates], disable it per run with WAYSCRIBER_DISABLE_UPDATE_CHECK=1, or compile it out entirely with WAYSCRIBER_NO_UPDATE_CHECK=1.
wayscriber --check-update runs the check on demand and prints the result.
About is reachable from the overlay itself now: a chrome button on the top strip (hideable from Customize), an entry in the overflow’s Settings… popover, a clickable pill in the F1 help overlay footer, and a command-palette entry. The bindable action is open_about, unbound by default. Opening About closes the overlay, since About is a normal window and the overlay draws above those.

Interface overhaul

The default UI is now a set of detached top-strip islands with a contextual style pill instead of a permanent side palette. The pill follows the active tool and hosts color, size, opacity, fill, text, eraser, and selected-object controls.
A 3–5-slot presets island sits between Tools and History. Filled slots apply saved profiles; empty slots save the current profile. Quick colors now live only in the style pill.
The status bar is an interactive chip HUD: board/page, color, tool, and Help segments open their corresponding surfaces. Frozen, zoom, pan, and editing states stack above it as badges.
F2 cycles the top strip full → micro chip → hidden. F9 directly toggles toolbar visibility. Idle islands fade after four seconds and respect reduced motion.
Clear moved into overflow: click for a brief Undo action, or Shift+click to clear immediately. Canvas, Session, and Settings open from overflow popovers. Canvas contains Boards, Pages, Advanced, Zoom, and Step Undo/Redo sections.
A persistent bottom-right zoom chip shows the live percentage with zoom-out, zoom-in, Fit, and (while zoomed) Lock controls. It follows the existing show_zoom_actions toggle, so no new config key is required.
side_layout = "panel" temporarily restores the deprecated four-pane side palette; layout_mode remains the independent Simple/Regular/Advanced complexity setting. Panel users receive a once-per-session map to every replacement surface.

Runtime UI preferences

Direct overlay preferences now survive restarts without broad config.toml rewrites. Toolbar pin/minimized state, the active legacy pane and collapsed sections, individual item visibility/order, and board pins live in generated $XDG_DATA_HOME/wayscriber/runtime-ui.toml state; configured values remain the authored startup defaults.
Runtime-state writes detect external file changes, symlink/path retargeting, and uncertain write outcomes instead of overwriting blindly. The overlay blocks further runtime preference changes when recovery is required.
Overlay Settings shows the complete state and recovery-artifact paths and provides retry, adopt-disk, reset, and invalid/unsupported-file recovery flows. Newer formats stay read-only, and destructive reset requires confirmation after preserving the original bytes.

Faster tool selection

The radial menu is now an eight-direction fixed compass. Hold middle-click, flick toward a tool, and release to commit; a center release cancels.
The opened menu includes tool glyphs and live shortcut badges, a catalog-backed shape sub-ring, recent colors, and a draggable outer size ring.
An optional ink-preview cursor shows the current color and width, active tool glyph, and an automatic contrast outline.

Finding features and shortcuts

The command palette adds action icons, category headers, fuzzy matching, shortcut editing, Save Preset 1–5 actions, responsive query updates, and recents persisted across restarts.
The Help overlay is fuzzy-searchable, clickable, and limited to one or two columns. Its footer can replay the guided tour.
The tour reads current keybindings instead of hard-coded shortcuts and now teaches color/thickness changes, radial flicking, and Boards & Pages. Staggered later-session hints introduce the status-bar picker, Canvas popover, and zoom chip. A rate-limited shortcut coach can offer occasional hints afterward.
Notifications now prioritize critical warnings and undo actions over routine info and hints, with deduplication and rate limits.

Appearance and accessibility

Overlay and toolbar chrome share one accent and token-driven dark/light theme.
[ui] reduced_motion = "on" disables UI animation. auto is reserved for future system-preference detection and currently leaves motion enabled.
Swatches, keycaps, popovers, panels, and selection states use shared visual primitives across the GTK4 and builtin Cairo toolbar frontends.

Other recent additions

The screen eyedropper samples the displayed desktop through a magnified pixel loupe. Press I, use the contextual color controls, or search the command palette.
Light passthrough defaults to F6 while the overlay has focus; compositor/global wayscriber --light-* commands remain the reliable way to control it after input is passing through.
Default builds use GTK4 toolbars on supported layer-shell compositors and fall back to the builtin Cairo frontend where that path cannot run.

Release history is maintained on GitHub:

https://github.com/devmobasa/wayscriber/releases

Contributing (Short)

Contributions are welcome when they fit the project direction.

Start here:

Repository: https://github.com/devmobasa/wayscriber

If you are proposing a feature, open an issue first and explain the use case.

Architecture (Short)

Wayscriber is a Rust Wayland overlay that layers on top of the compositor using wlr-layer-shell when available, with an xdg-shell fallback.

Keyboard shortcuts

Wayscriber