wayscriber

A ZoomIt-like real-time screen annotation tool for Linux/Wayland, written in Rust.

Draw over any app, present with callouts and zoom, keep your boards between sessions — all from a lightweight daemon you toggle with one keybind.

Docs: https://wayscriber.com/docs/

More screenshots


Radial tool menu	Boards & pages
Blackboard	Whiteboard
Advanced toolbar	Command palette
Built-in controls (F1)	Simple toolbar

Demo video

View demo (wayscriber.com)

demo.mp4

Why wayscriber?

Annotate live over any app without disrupting your workflow
Professional presentation tools — presenter mode, numbered callouts, click highlights, screen freeze, zoom
Persistent sessions that survive restarts
Native Wayland performance with ZoomIt-like controls
Lightweight daemon with instant toggle via keybind

Platform support

Platform	Status	Notes
Wayland (layer-shell)	✅ Supported	Hyprland, Sway, River, Wayfire, Niri/Cosmic, Plasma/KWin
GNOME	⚠️ Partial	Normal overlay and Freeze via portal when available; light passthrough unavailable
X11	❌	Not supported

The v0.9.23+ prebuilt wayscriber packages require glibc 2.39 and GTK 4.12 — see the notes in Debian and Ubuntu and Fedora and RHEL. The AUR packages and Nix are unaffected.

Tested environments

Ubuntu 25.10 GNOME (xdg fallback)
Fedora 43 KDE (Plasma, layer-shell)
Fedora 43 GNOME (xdg fallback)
Debian 13.2 KDE (Plasma, layer-shell)
Debian 13.2 GNOME (xdg fallback)
CachyOS 2025-August KDE (Plasma, layer-shell)
Hyprland on Arch (layer-shell)
Niri on Arch (layer-shell)

Comparison with ZoomIt

Feature	ZoomIt (Windows)	wayscriber
Drawing tools	✅	✅
Boards/Backgrounds	✅	✅
Multi-line text	❌	✅
Custom fonts	❌	✅
Config file	❌	✅
Help overlay	❌	✅
Zoom	✅	✅
Break timer	✅	❌

Features

Drawing and editing

Freehand pen, highlighter, eraser (circle/rect)
Shapes: lines, rectangles, ellipses, polygons (with fill toggle)
Arrows with optional auto-numbered labels; step markers for walkthroughs
Blur tool with four styles: soften, pixelate, secure (flattens the region to one color), and black out
Spotlight tool: dims everything except the regions you draw
Multiline text and sticky notes with smoothing
Selection: Alt-drag, V tool, properties panel
Duplicate (Ctrl+D), delete (Delete), undo/redo
Color picker, screen eyedropper with a magnified pixel loupe, palettes, size via hotkeys or scroll
Render color profiles for print/projector/light-theme preview
Radial menu at cursor (Middle-click): quick tool/color selection with recent colors, press-flick-release tool commits, plus a draggable outer size ring and scroll size adjust

Boards

Named boards with transparent overlay or custom backgrounds
Isolated pages per board with auto-contrast pens
Pan solid boards with Space + left-drag; reset from the context menu
Jump slots: Ctrl+Shift+1..9
Toggle whiteboard/blackboard
Board picker: Ctrl+Shift+B

Capture and screenshots

Full-screen saves, active-window grabs, region capture
Copy to clipboard or save to file
Uses grim, slurp, wl-clipboard (installed automatically by deb/rpm/AUR packages; fallback: xdg-desktop-portal)

Sessions and persistence

Session persistence is enabled by default for boards, undo/redo history, and tool state
Per-output default sessions, plus named session files with --session-file
Overlay Session panel, configurator Session tab, tray toggle, and CLI overrides
See Session manager and persistence for the full workflow

Toolbars and UI

Floating toolbars (F9 toggles visibility; F2 cycles the top strip full → micro chip → hidden)
Two toolbar frontends: GTK4-rendered bars on layer-shell compositors (Hyprland, KWin, Wayfire, River, ...), with automatic fallback to the built-in Cairo bars everywhere else (GNOME xdg fallback, forced-inline mode, builds without the toolbar-gtk feature)
Pick a frontend explicitly with ui.toolbar.backend = "auto" | "gtk" | "builtin" or WAYSCRIBER_TOOLBAR_BACKEND
Preset slots, icon or text modes
Color picker with extended palettes and a screen eyedropper (toolbar, popup, or command palette)
Status bar with independently configurable output, selection, board, page, color, tool, size, context, toolbar-hint, Help, and About/version items
Help overlay (F1), quick reference (Shift+F1)
Command palette (Ctrl+K or Ctrl+Shift+P)
Search, run, edit, unbind, or reset action shortcuts from the command palette; hold Ctrl+Shift while clicking a bindable toolbar control for direct shortcut capture (the modifier chord is configurable). An accepted shortcut is written straight back to config.toml — only that action's entry, with a timestamped .bak — and Ctrl+Shift+E on a palette row opens the same shortcut in the configurator

Multi-monitor

Move overlay focus between monitors: Ctrl+Alt+Shift+←/Ctrl+Alt+Shift+→
Toolbars and status bar follow the active output when output focus changes
Optional active output badge in status bar (ui.active_output_badge)
Output-scoped session restore when session.per_output = true
GNOME fallback output pinning via ui.preferred_output or WAYSCRIBER_XDG_OUTPUT

Presets

Save tool + color + size (plus fill/opacity/text) into 3–5 slots
Apply: 1–5; save: Shift+1–Shift+5

Presenter tools

Click highlights with configurable colors/radius/duration
Persistent ring while the click highlight tool is active
Presenter mode (Ctrl+Shift+M): hides UI, forces click highlights
Input HUD (Ctrl+Shift+K): on-screen keystroke and click chips for demos and screencasts (opt-in system-wide capture via the input-monitor build feature — see docs/CONFIG.md)
Light passthrough (layer-shell): draw while input passes through to the app underneath — see Light passthrough mode
Screen freeze (Ctrl+Shift+F): pause the display while apps keep running. On GNOME, this uses the screenshot portal when available
Spotlight: drag an ellipse to dim everything around it; stack several to highlight multiple areas. Dim strength and edge softness are configurable under [spotlight]

Callouts and zoom

Numbered callouts: auto-numbered arrow labels and step markers; reset arrow labels with Ctrl+Shift+R
Zoom: spotlight details with ZoomIt-style controls
- Zoom in/out: Ctrl+Alt + scroll or Ctrl+Alt + +/-
- Reset: Ctrl+Alt+0; lock view: Ctrl+Alt+L
- Pan: middle drag or arrow keys
- Right-click menu: Zoom → Zoom In / Zoom Out / Reset Zoom

Installation

Pick the path that matches your setup:

You want	Use
Fast CLI install with auto-updates on Debian/Ubuntu/Mint/Pop!_OS	Debian and Ubuntu
Fast CLI install with auto-updates on Fedora/Nobara or RHEL/Rocky/Alma 10+	Fedora and RHEL
Arch, Manjaro, CachyOS, or another Arch-based distro	AUR, preferably `wayscriber-bin` for the prebuilt package
NixOS, or the Nix package manager on another distro	NixOS and Nix — `nixpkgs` for the standard install, the project flake for the newest release and the Configurator
One-off package (browser or terminal) without adding a repo	GitHub Releases
Hacking on wayscriber or building a local binary	From source

Distro repositories, the AUR, and declarative NixOS installs are the best default for CLI users because they follow the normal system update flow. Packages installed with nix profile are updated separately with nix profile upgrade. GitHub .deb/.rpm downloads are one-off installs (no auto-updates); use them only when you do not want to add a repo.

Install the main wayscriber package first. wayscriber-configurator is an optional GUI settings app and does not include the wayscriber binary.

Debian and Ubuntu

Also use this path for Linux Mint, Pop!_OS, and other Debian-based distros.

Wayscriber v0.9.23+ requires Ubuntu 24.04+ or Debian 13 (trixie) or newer. This includes Linux Mint 22+ and Pop!_OS 24.04+. These release packages 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 remains below the GTK requirement; use the GTK-less source build there.

sudo apt update
sudo apt install curl gpg
sudo install -d -m 0755 /usr/share/keyrings
curl -fsSL https://wayscriber.com/apt/WAYSCRIBER-GPG-KEY.asc | gpg --dearmor | sudo tee /usr/share/keyrings/wayscriber.gpg > /dev/null
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
# Optional GUI configurator:
sudo apt install wayscriber-configurator

For a one-off .deb without adding the repo, see GitHub Releases.

Fedora and RHEL

Use this path for supported Fedora and Nobara releases, or RHEL, Rocky Linux, and AlmaLinux 10+.

Wayscriber v0.9.23+ prebuilt RPMs require glibc 2.39 and GTK 4.12. This means RHEL/Rocky/Alma 10+ and compatible Fedora/Nobara releases.

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
# Optional GUI configurator:
sudo dnf install wayscriber-configurator

For a one-off .rpm without adding the repo, see GitHub Releases.

Arch Linux (AUR)

Also use this path for Manjaro, CachyOS, and other Arch-based distros. The examples use yay as the default AUR helper; equivalent paru commands are shown for each package.

# Prebuilt binary:
yay -S wayscriber-bin
paru -S wayscriber-bin

# Or build from source:
yay -S wayscriber
paru -S wayscriber

# Optional GUI configurator:
yay -S wayscriber-configurator
paru -S wayscriber-configurator

NixOS and Nix

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

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
This project's flake	The tag or branch recorded in your `flake.lock`

If you are on a stable NixOS channel and want the newest release, use the project flake rather than waiting for nixpkgs.

NixOS, from nixpkgs — add Wayscriber to configuration.nix or another NixOS 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 without installing:

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

nix run does not add wayscriber to your PATH.

Latest release and Configurator on NixOS

The project flake provides release-pinned packages plus the optional Configurator. Replace RELEASE_TAG with a published tag, such as the one shown on the latest release, when adding the input to your existing flake.nix:

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 Wayscriber revision. 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 distro — when running the Nix package manager on Ubuntu, Fedora, or elsewhere, a user profile install is reasonable:

nix profile install nixpkgs#wayscriber

For the 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 (and nix profile upgrade wayscriber-configurator), or remove them with nix profile remove wayscriber.

Development shell (for contributing or building locally, not for installing):

nix develop github:devmobasa/wayscriber

GitHub Releases (one-off)

Install the release package directly if you prefer not to add a repo — these are one-off installs with no auto-updates.

In a browser:

Open the latest release.
Install the main app package that matches your distro:
- wayscriber-amd64.deb — v0.9.23+ supports Ubuntu 24.04+, Linux Mint 22+, Pop!_OS 24.04+, Debian 13+, and compatible newer Debian-based distros (see the release requirement)
- wayscriber-x86_64.rpm — v0.9.23+ supports compatible Fedora/Nobara releases and RHEL/Rocky/Alma 10+ (see the release requirement)
Optional: install the configurator package after wayscriber:
- wayscriber-configurator-amd64.deb
- wayscriber-configurator-x86_64.rpm
- Note: wayscriber-configurator is a separate app and does not install wayscriber.
Launch Wayscriber from your application menu/launcher.
Optional later: switch to daemon mode (recommended) using the steps in Daemon mode.

Same one-off install from the terminal (.deb / .rpm)

Debian/Ubuntu:

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

Fedora/Nobara or RHEL/Rocky/Alma 10+:

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

Configurator .deb (optional):

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

Configurator .rpm (optional):

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

From source

Rust 1.95 or newer is required. If rustup is not already installed, install it (this also installs cargo), then load Cargo into your current shell:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Then clone the repository — the dependency and build steps below run from inside it:

git clone https://github.com/devmobasa/wayscriber.git
cd wayscriber
rustup toolchain install 1.95.0
rustup override set 1.95.0
cargo --version

The override selects Rust 1.95 only inside this checkout and leaves your global default unchanged. You can instead keep any existing default that is already Rust 1.95 or newer.

Dependencies:

# 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

On Ubuntu 24.04 LTS and Mint 22 there is no libgtk4-layer-shell-dev package, but GTK itself is new enough. Either build the small layer-shell library from the pinned source (needs meson ninja-build wayland-protocols, installs into /usr):

sudo apt-get install meson ninja-build wayland-protocols
bash tools/install-gtk4-layer-shell.sh   # builds + installs gtk4-layer-shell 1.3.0

…or skip it and use the GTK-less build option below. That keeps the built-in Cairo toolbars and every other default feature.

Pop!_OS 22.04 ships GTK 4.6, below the GTK 4.12 API required by the default build. Building only gtk4-layer-shell is therefore not enough there: use the GTK-less build below, unless you separately install GTK 4.12 or newer.

Build:

With the GTK toolbar frontend (the default):

cargo build --release
# Binary: target/release/wayscriber

Without the GTK toolbar frontend:

cargo build --release --no-default-features --features tablet-input,portal,tray
# Binary: target/release/wayscriber

Optional install script:

./tools/install.sh

Screenshot tools

wl-clipboard, grim, and slurp are installed automatically by deb/rpm/AUR packages. If you build from source or use the tarball, install them manually:

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

First launch

After installing:

wayscriber --version
wayscriber --active

(If you used nix run instead of installing, wayscriber is not on your PATH — keep using the nix run command from Installation.)

Once the overlay is up:

F1 or F10 — help overlay
Shift+F1 — quick reference
Ctrl+K / Ctrl+Shift+P — command palette
F11 — configurator
Escape — hide or exit

For daily use, set up daemon mode: toggles are faster and session state survives between activations.

Usage

Daemon mode (recommended)

Run wayscriber in the background and toggle it with a keybind. Recommended for daily use: faster toggle, better workflow, and session persistence.

Enable the service:

systemctl --user enable --now wayscriber.service
wayscriber --daemon-toggle

Prefer a GUI? Open wayscriber-configurator, go to the Daemon tab, and click Install/Update Service, then Enable + Start.

Bind a toggle key:

Bind wayscriber --daemon-toggle to a global shortcut in your compositor or desktop environment. The configurator's Daemon tab can also do this: set a shortcut and click Apply Shortcut (GNOME: writes a GNOME custom shortcut; KDE/Plasma: writes the systemd drop-in env WAYSCRIBER_PORTAL_SHORTCUT for portal global shortcuts).

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

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

Traditional Hyprland config (~/.config/hypr/hyprland.conf):

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

Then reload your config:

hyprctl reload

GNOME (Ubuntu/Debian/Fedora):

Open Settings -> Keyboard -> Keyboard Shortcuts.
Scroll down to Custom Shortcuts, click +.
Name: Wayscriber Toggle.
Command: wayscriber --daemon-toggle.
Set a shortcut key (recommended on Ubuntu GNOME: Super+G; Super+D is often already in use).

KDE Plasma:

Open Settings -> Keyboard -> Shortcuts.
Add new Command or Script.
Name: Wayscriber Toggle.
Command: wayscriber --daemon-toggle.
Assign a key (for example Meta+Shift+D).

Other desktops/window managers: bind wayscriber --daemon-toggle to any global shortcut key you prefer.

Use only one toggle binding. Duplicate entries (for example two SUPER+D binds, or a leftover one-shot bind on the same key) can fire twice and immediately undo the toggle. If your compositor shortcut environment does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber instead.

System tray:

Right-click the tray icon for options. Less-frequent actions are grouped into Drawing Modes, Capture, and Settings & Data submenus so the menu remains usable on shorter or scaled displays:

Toggle overlay visibility
Freeze/unfreeze the current overlay
Capture full screen / active window / region
Toggle the help overlay
Open session persistence settings in the configurator
Clear saved session data
Open the log folder
Open configurator / open config file / quit

Supported desktops use a theme-adaptive symbolic tray icon. Hosts that do not reliably resolve named icons (including Omarchy/Quickshell, Noctalia/Quickshell, and COSMIC) automatically receive scale-aware colored pixmaps, including a 48px HiDPI rendition. Set [tray].icon_style to "auto" (default), "symbolic", or "colored" to choose the main tray icon style; restart the daemon after changing it. Use --no-tray or WAYSCRIBER_NO_TRAY=1 if you don't have a system tray. If the tray icon is still blank or the menu shows square placeholders, start the daemon with WAYSCRIBER_TRAY_FORCE_PIXMAP=1; this environment override takes precedence over the TOML setting.

Alternative — compositor autostart instead of systemd:

For Hyprland Lua, add these to 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

Service commands:

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

One-shot mode (alternative)

Launch wayscriber when you need it, then exit:

wayscriber --active
wayscriber --active --mode whiteboard
wayscriber --active --mode blueprint
wayscriber --freeze   # start with screen frozen

whiteboard and blackboard are built in; blueprint is an example of a custom board defined in config.toml ([[boards.items]] — see Configuration).

Bind to a key (Hyprland Lua config):

o.bind("SUPER + D", "Open Wayscriber", "wayscriber --active")

Traditional Hyprland config:

bind = SUPER, D, exec, wayscriber --active

The same in-overlay shortcuts apply as in First launch; Escape or Ctrl+Q exits.

Light passthrough mode

Light passthrough (layer-shell compositors only) lets normal keyboard and pointer input reach the app underneath while wayscriber stays visible for drawing.

F6 enters passthrough from the focused overlay. It is a wayscriber in-overlay shortcut, not an OS/global shortcut — once passthrough is active, wayscriber may no longer receive that keypress.
For reliable control (including getting back out of passthrough), bind compositor/global shortcuts to wayscriber --light-toggle and wayscriber --light-draw-toggle.
Use wayscriber --light-draw-on on press and wayscriber --light-draw-off on release for draw-while-held shortcuts.
Hyprland and KDE binding examples are in docs/SETUP.md; the KDE section follows the Hyprland binding example.
Stock GNOME Wayland does not support this mode — regular app windows cannot provide the required click-through shell overlay. Freeze may still work for still-image capture, but it is not a live passthrough replacement. A GNOME Shell extension approach would be needed for true shell-level passthrough.

Screenshots and export

Shortcut	Action
`Ctrl+Alt+F`	Capture full screen (respects `capture.copy_to_clipboard`)
`Ctrl+Shift+O`	Capture active window (respects `capture.copy_to_clipboard`)
`Ctrl+Shift+I`	Capture selection (respects `capture.copy_to_clipboard`)
`Ctrl+C`	Copy full screen to clipboard
`Ctrl+S`	Save full screen as PNG
`Ctrl+Shift+C`	Select region → clipboard
`Ctrl+Shift+S`	Select region → save PNG
`Ctrl+6`	Region → clipboard (explicit)
`Ctrl+Alt+6`	Region → save PNG (explicit)
`Ctrl+Alt+O`	Open last capture folder

Shortcuts marked "respects capture.copy_to_clipboard" send the capture to the clipboard or a file according to that config.toml setting; the other shortcuts always use the destination shown. Captures need the screenshot tools and fall back to xdg-desktop-portal if they are missing.

Use --exit-after-capture / --no-exit-after-capture to override whether the overlay closes after a capture.

PDF export

Canvas export commands are available in the command palette and keybindings. export_board_pdf_file saves the active board as a multi-page PDF, export_all_boards_pdf_file saves every board in board order, and both PDF actions are unbound by default. PDF exports keep transparent pages blank unless [export.pdf] transparent_background = "desktop" is set, which captures the live desktop behind the overlay for transparent pages only.

Getting help

Help overlay: F1 or F10
Quick reference: Shift+F1
Command palette: Ctrl+K or Ctrl+Shift+P (search monitor or display for output actions)
About window: wayscriber --about
Check for a newer release: wayscriber --check-update (Wayscriber never installs updates itself; it points at the instructions for your install method). Turn the background check off with [updates] check = false or WAYSCRIBER_DISABLE_UPDATE_CHECK=1 — see https://wayscriber.com/docs/getting-started/updating.html
Full docs: https://wayscriber.com/docs/

Controls reference

Press F1 for the complete in-app cheat sheet.

Essential shortcuts

Action	Key
Freehand pen	Drag
Arrow	`Ctrl+Shift` + drag
Rectangle	`Ctrl` + drag
Text mode	`T`
Select/move	`Alt` + drag or `V`
Undo / Redo	`Ctrl+Z` / `Ctrl+Y`
Color keys	`R` `G` `B` `Y` `O` `P` `W` `K`
Size	`+` / `-` or scroll
Help	`F1`
Exit	`Escape`

All drawing tools

Action	Key/Mouse
Freehand pen	Drag with left mouse button
Straight line	`Shift` + drag
Rectangle	`Ctrl` + drag
Ellipse/Circle	`Tab` + drag
Arrow	`Ctrl+Shift` + drag
Triangle / parallelogram / rhombus / regular polygon	Shape picker in the top strip (bindable)
Freeform polygon	Shape picker, then click vertices; `Enter` or double-click to finish
Blur	Shape picker (bindable) — drag a region; style via Cycle Blur Style
Spotlight	Shape picker (bindable) — drag an ellipse; everything else dims
Step marker tool	Toolbar (bindable)
Highlight brush	`Ctrl+Alt+H`
Text mode	`T`, `Click` to place, type, `Enter` to finish
Sticky note	`N`, `Click` to place, type, `Enter` to finish

Where the Shape picker is. The top strip shows the common tools inline and puts the rest behind a single Shape picker button. What sits inline depends on the strip mode: the simple strip keeps Select, Pen, Marker, Step marker, and Eraser inline, while the full strip adds Line and Arrow. Everything else — rectangle, ellipse, blur, spotlight, and the polygons — is one click away inside the picker.

Every tool is also its own toolbar item, so you can show, hide, and reorder them from the settings popover (gear icon) or via ui.toolbar.items in config.toml. That is how the screenshot button ships hidden by default.

These tools' default keybindings are intentionally empty; bind them under [keybindings.tools] if you reach for them often. Drag and mouse-button mappings are configurable — see Drag-tool mappings.

Text editing

While a text block or sticky note is being edited, these keys belong to the editor and are not configurable. Everything else — undo, tool switching, board navigation, capture — still reaches its usual binding.

Action	Key/Mouse
Place the caret	`Click`
Select text	`Shift` + `Click`, or `Shift` + arrows
Select all text	`Ctrl+A`
Move the whole block	`Alt` + drag
Move by character	`←` / `→`
Move by word	`Ctrl` + `←`/`→`
Move by line	`↑` / `↓`
Line start / end	`Home` / `End`
Text start / end	`Ctrl+Home` / `Ctrl+End`
Copy / cut / paste	`Ctrl+C` / `Ctrl+X` / `Ctrl+V`
Delete character	`Backspace` / `Delete`
Delete word	`Ctrl+Backspace` / `Ctrl+Delete`
New line	`Shift+Enter`
Finish editing	`Enter`
Cancel editing	`Escape`

Caret movement and selection follow the rendered layout, so they behave correctly in wrapped text and in right-to-left or mixed-direction scripts. Ctrl+C and Ctrl+X only apply to a selection; with no selection they fall through to whatever those keys are bound to. Copy, cut, and paste use the system clipboard via wl-copy/wl-paste.

Boards

Action	Key
Toggle Whiteboard	`Ctrl+W`
Toggle Blackboard	`Ctrl+B`
Return to Transparent	`Ctrl+Shift+T`
Switch board slot	`Ctrl+Shift+1..9`
Previous/next output	`Ctrl+Alt+Shift` + `←`/`→`
Previous/next board	`Ctrl+Shift` + `←`/`→`
New board	`Ctrl+Shift+N`
Delete board	`Ctrl+Shift+Delete`
Board picker	`Ctrl+Shift+B`
Pan solid boards	Hold `Space` + left-drag
Reset solid-board pan	`Right-click` → Reset Canvas Position

Colors and sizes

Color	Key
Red	`R`
Green	`G`
Blue	`B`
Yellow	`Y`
Orange	`O`
Pink	`P`
White	`W`
Black	`K`

The first eight quick colors map to the shortcuts above and are customizable — see Quick colors.

Pick a color directly from the displayed desktop with the screen eyedropper: press I, use the eyedropper button in the toolbar or color picker, or search for Pick screen color in the command palette (Ctrl+K). Rebind it if you prefer another shortcut:

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

Action	Key
Increase thickness	`+` / `=` / scroll down
Decrease thickness	`-` / `_` / scroll up
Increase font size	`Ctrl+Shift` + `+` / `Shift` + scroll down
Decrease font size	`Ctrl+Shift` + `-` / `Shift` + scroll up
Increase marker opacity	`Ctrl+Alt` + `↑`
Decrease marker opacity	`Ctrl+Alt` + `↓`

Selection and arrange

Action	Key
Duplicate selection	`Ctrl+D`
Copy selection	`Ctrl+Alt+C`
Paste selection or copied PNG/JPEG image	`Ctrl+Alt+V`
Delete selection	`Delete`
Bring to front/back	`]` / `[`
Nudge selection	Arrow keys (large: `PageUp`/`PageDown`)
Move to edges	`Home`/`End` / `Ctrl+Home`/`Ctrl+End`
Select/move shapes	Hold `Alt` + drag
Select tool	`V`
Add to selection	`Shift` + click
Selection properties	`Ctrl+Alt+P`

Pages

Action	Key
Previous/next page	`Ctrl+Alt` + `←`/`→` or `Ctrl+Alt` + `PageUp`/`PageDown`
New page	`Ctrl+Alt+N`
Duplicate page	`Ctrl+Alt+D`
Delete page	`Ctrl+Alt+Delete`

Editing and UI

Action	Key
Undo	`Ctrl+Z`
Redo	`Ctrl+Shift+Z` / `Ctrl+Y`
Select all	`Ctrl+A`
Eraser	`D`
Toggle eraser mode	`Ctrl+Shift+E`
Clear all	`E`
Cancel action	`Right-click` (while drawing) / `Escape`
Context menu	`Right-click` (idle) / `Shift+F10` / `Menu`, `Arrow keys` + `Enter`/`Space`
Edit selected text/note	`Enter` (single selection)
Toggle toolbars	`F9`
Cycle top strip (full → micro → hidden)	`F2`
Help overlay	`F1` / `F10`
Quick reference	`Shift+F1`
Configurator	`F11`
Command palette	`Ctrl+K` / `Ctrl+Shift+P`
Screen eyedropper	`I`, toolbar/color picker, or `Ctrl+K` → Pick screen color
Radial menu	`Middle-click` (idle) open/close; hold + flick toward a wedge to commit instantly (release in the center cancels); `Left-click` select; `Right-click`/`Escape` dismiss; drag the outer ring or scroll to adjust active tool size
Status bar	`F4` / `F12`
Apply preset slot	`1` - `5`
Save preset slot	`Shift+1` - `Shift+5`
Toggle click highlight	`Ctrl+Shift+H`
Toggle input HUD	`Ctrl+Shift+K`
Toggle light passthrough (in-overlay)	`F6` (see Light passthrough mode)
Reset arrow labels	`Ctrl+Shift+R`
Toggle freeze	`Ctrl+Shift+F`
Zoom in/out	`Ctrl+Alt` + scroll / `Ctrl+Alt` + `+` / `Ctrl+Alt` + `-`
Reset zoom	`Ctrl+Alt+0`
Toggle zoom lock	`Ctrl+Alt+L`
Pan zoom view	`Middle drag` / `Arrow keys`
Exit	`Escape` / `Ctrl+Q`

Notes:

Arrow labels can auto-number when enabled in the arrow toolbar; reset with Ctrl+Shift+R.
Step markers auto-increment and reset from the toolbar (or bind reset_step_markers in config.toml).
Preset slots can be saved/cleared from the toolbar; the slot changes right away and is written back to config.toml on a background worker, with the toast confirming it once the file has it. Edit names and advanced fields in the configurator's Presets tab.
The blur tool has no default keyboard shortcut; bind select_blur_tool in config.toml if you want direct keyboard access.

Configuration

Config file: ~/.config/wayscriber/config.toml

Create from example:

mkdir -p ~/.config/wayscriber
cp config.example.toml ~/.config/wayscriber/config.toml

Or use the GUI configurator:

wayscriber-configurator   # or press F11

See docs/CONFIG.md and https://wayscriber.com/docs/ for the full reference.

config.toml contains authored defaults, and it changes only through an explicit user edit action — never automatically. Two things write it: the configurator's Save, and the overlay's three narrow editors (shortcut editing, preset slots, and the quick-color palette), each of which rewrites only its own key and copies the previous file to a timestamped .bak first. Running, using, and quitting Wayscriber never changes the file on its own. An incidental preference toggle applies to the current run and offers a route to the configurator screen that owns its default.

Toolbar pins (updated by the pin buttons and by the toolbar show/hide keybinding, so the next start matches what was on screen), dragged positions, the top strip's display form, minimized/pane/collapsed state, individual toolbar item visibility/order, and board pins changed in the overlay are direct interaction state and are saved separately in the generated $XDG_DATA_HOME/wayscriber/runtime-ui.toml file. Inspect, recover, or reset those runtime preferences from the overlay Settings panel; see Configuration Guide.

Key sections

[drawing]
default_color = "red"
default_thickness = 3.0
polygon_sides = 5

[[drawing.quick_colors]]
label = "Blush"
color = "#FFB3BA"

[drawing.drag_tools.right]
drag_tool = "pen"
drag_color = "blue"

[presets]
# slot_count: 3-5
slot_count = 5

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

[performance]
# vsync and fps caps — see Performance tuning under Troubleshooting

[ui]
# status bar visibility and position

[boards]
# named boards + backgrounds

Drag-tool mappings

Drag modifier mappings are configurable via [drawing] (drag_tool, shift_drag_tool, ctrl_drag_tool, ctrl_shift_drag_tool, tab_drag_tool) or in the configurator Drawing tab. For per-button workflows, use [drawing.drag_tools.left], [drawing.drag_tools.right], and [drawing.drag_tools.middle]; each binding can set a tool and optional color. The polygon tools have intentionally empty default keybindings — select them from the toolbar picker or bind them yourself. Freeform polygon is selectable but not drag-bindable.

Quick colors

The quick color palette is configurable with ordered [[drawing.quick_colors]] entries. The first eight entries map to the R/G/B/Y/O/P/W/K shortcuts; if fewer are configured by hand, missing shortcut positions use the built-in defaults. The implicit default toolbar palette also preserves Cyan, Purple, and Gray as expanded toolbar colors while the radial menu keeps its original first-eight color ring. Explicit entries beyond the first eight have no shortcut action binding and opt those extra colors into dense palette UIs, capped to the first 24 colors.

You can also recolor the palette without opening an editor: right-click any swatch to open the color picker for that slot. The swatch updates live as you drag, OK saves that one entry's color back to config.toml (leaving your other settings and comments alone, with a timestamped .bak), and Cancel restores it. The slot keeps its label and shortcut, so R still selects the red slot after you point it at a different red. Recoloring the swatch you are drawing with moves the live color along with it. Left-click still just selects a swatch, and the leftmost chip still opens the picker for the active tool's own color.

Changed your mind? The recolor picker carries a Default button that loads the color wayscriber ships for that slot. It stages the color like any other pick, so the swatch previews it and OK/Cancel still decide. It appears only for the eleven built-in slots — extra colors you added yourself have no shipped default to restore.

Session manager and persistence

Session persistence is enabled by default. Manage it in the configurator (F11 → Session tab, also reachable from the tray menu's Session persistence settings… entry) or override it for one run with the CLI flags below.

wayscriber --resume-session      # force resume (persist/restore all boards + history/tool state)
wayscriber --no-resume-session   # disable resume for this run
wayscriber --session-info        # inspect saved sessions
wayscriber --clear-session       # remove stored boards
wayscriber --clear-tool-state    # reset saved tool defaults, keep boards/history

# Named session files — --session-file combines with any of the flags above
# and with --active / --freeze / --daemon:
wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session

See Session manager examples for complete CLI, overlay, and configurator workflows.

Behavior notes

Config values seed startup defaults. When restore_tool_state is enabled (default), the last-used tool settings saved in the session (including arrow head placement) override those config defaults on startup. Run wayscriber --clear-tool-state to remove only that saved tool layer so config defaults apply next startup while saved boards/history remain. In a running overlay, use Command Palette → Reset Tool Defaults to clear the saved layer and immediately apply config defaults to the active tools.
--session-file uses exactly the selected file, implies persistence for that overlay run, rejects directories/symlinks/special files, and does not create missing parent directories. A running daemon can launch a hidden overlay with a named target; if the overlay is already visible, hide it before switching to a different named session.
The overlay Session panel lives in the side toolbar's Settings drawer. It can open an existing named session, save the current overlay as another named session, show session info, clear the active session, reopen recent named sessions, and jump to the configurator. The Open/Save As dialogs use zenity or kdialog; Save As appends .wayscriber-session when no extension is supplied and asks before replacing existing session artifacts.
The configurator Session tab manages recent named sessions recorded when named-session targets are opened or saved from the CLI, daemon, or overlay. It can rename catalog labels, reveal files, and forget metadata without touching files. Clear Tool State removes only the saved tool layer; Clear Saved Data removes session files. Duplicate, Move, Clear Tool State, and Clear are disabled while an overlay, manually started daemon, or background service is active.

Tablet and stylus support

Tablet support (zwp_tablet_v2) ships in default builds and is enabled at runtime by default:

[tablet]
enabled = true
pressure_enabled = true
min_thickness = 1.0
max_thickness = 8.0

It works out of the box in default builds. Set [tablet].enabled = false in config.toml to opt out. To build without tablet support, drop only that feature (bare --no-default-features would also strip portal capture, tray, and the GTK toolbars): cargo build --release --no-default-features --features portal,tray,toolbar-gtk.

Troubleshooting

Daemon not starting after reboot

Enabled user services start when you log in, not at boot — if the daemon is missing after a reboot and login, see Service won't start. Enable lingering only if you want the daemon started before login or kept running after logout:

loginctl enable-linger $USER

Or use compositor autostart instead. For Hyprland Lua, add this to ~/.config/hypr/autostart.lua:

o.launch_on_start("wayscriber --daemon")

Traditional Hyprland config:

exec-once = wayscriber --daemon

Service won't start

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

Overlay is blurry/non-transparent on KDE Plasma

Cause: The "Better Blur DX" effect (or similar blur effects) may blur wayscriber's transparent overlay.

Solution (Option 1 — configure Better Blur DX):

Open System Settings → Window Management → Desktop Effects
Click the configure button next to "Better Blur DX"
Go to the Force Blur tab
Add wayscriber to the window class list
Make sure Blur all except matching is selected
Click Apply

Solution (Option 2 — use standard blur):

Disable "Better Blur DX" in Desktop Effects
Enable the standard "Blur" effect instead

To find wayscriber's window class, run this and launch wayscriber before the 2-second sleep ends:

sleep 2; qdbus org.kde.KWin /KWin queryWindowInfo | grep resourceClass

Overlay not appearing

Verify Wayland session: echo $WAYLAND_DISPLAY
Ensure compositor supports wlr-layer-shell
Run with logs: RUST_LOG=info wayscriber --active

Config issues

ls -la ~/.config/wayscriber/config.toml
RUST_LOG=info wayscriber --active   # watch for TOML errors

Environment variables

Common toggles:

WAYSCRIBER_TOOLBAR_DRAG_PREVIEW=0 disables inline toolbar drag preview (default: on)
WAYSCRIBER_TOOLBAR_POINTER_LOCK=1 enables pointer-lock drag path (default: on)
WAYSCRIBER_TOOLBAR_DRAG_THROTTLE_MS=12 throttles toolbar drag updates (default: 12; set 0 to disable)
WAYSCRIBER_DEBUG_TOOLBAR_DRAG=1 enables toolbar drag logging (default: off)
WAYSCRIBER_DEBUG_TOOLBAR_COLOR=1 enables toolbar color picker logging (default: off)
WAYSCRIBER_FORCE_INLINE_TOOLBARS=1 forces inline toolbars on Wayland (default: off)
WAYSCRIBER_TOOLBAR_BACKEND=auto|gtk|builtin overrides the toolbar frontend (default: auto)
WAYSCRIBER_NO_TRAY=1 disables the tray icon (default: tray enabled)
WAYSCRIBER_TRAY_FORCE_PIXMAP=1 forces colored tray pixmaps and overrides [tray].icon_style

See docs/CONFIG.md for the full list.

Performance tuning

Default behavior prioritizes lower drawing latency by disabling vsync and capping no-vsync rendering:

[performance]
buffer_count = 3
enable_vsync = false
max_fps_no_vsync = 120
ui_animation_fps = 30

Use 120 as a strong low-latency cap for common systems. 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.

Set enable_vsync = true when tear-free presentation, lower power use, or quieter behavior matters more than input latency. Vsync usually adds a frame-cadence floor, especially on 60 Hz displays; disabling it improves input latency but may allow tearing and higher CPU/GPU usage.

Contributing

Contribution principles: wayscriber is shared as a gift exchange, not a contract. Requests are welcome, but there is no guaranteed timeline or support obligation. For the full principles, see https://wayscriber.com/docs/ethos/gift-exchange.html

See CONTRIBUTING.md for development setup, project structure, and workflow notes.

Roadmap

Future plans are tracked in GitHub issues.

License and credits

MIT License — see LICENSE

Acknowledgments

Inspired by ZoomIt by Mark Russinovich
Built for Linux (distros that use Wayland)
Similar ideas from Gromit-MPX
Uses Cairo and smithay-client-toolkit

Developed with AI assistance (ChatGPT, Codex, Claude Code).

Name		Name	Last commit message	Last commit date
Latest commit History 1,401 Commits
.github		.github
assets		assets
configurator		configurator
docs		docs
examples		examples
packaging		packaging
src		src
tests		tests
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
clean.sh		clean.sh
config.example.toml		config.example.toml
flake.lock		flake.lock
flake.nix		flake.nix

Folders and files

Latest commit

History

Repository files navigation

wayscriber

Table of contents

Why wayscriber?

Platform support

Features

Drawing and editing

Boards

Capture and screenshots

Sessions and persistence

Toolbars and UI

Multi-monitor

Presets

Presenter tools

Callouts and zoom

Installation

Debian and Ubuntu

Fedora and RHEL

Arch Linux (AUR)

NixOS and Nix

GitHub Releases (one-off)

From source

Screenshot tools

First launch

Usage

Daemon mode (recommended)

One-shot mode (alternative)

Light passthrough mode

Screenshots and export

Getting help

Controls reference

Essential shortcuts

Configuration

Key sections

Drag-tool mappings

Quick colors

Session manager and persistence

Tablet and stylus support

Troubleshooting

Daemon not starting after reboot

Service won't start

Overlay is blurry/non-transparent on KDE Plasma

Overlay not appearing

Config issues

Environment variables

Performance tuning

Contributing

Roadmap

License and credits

Acknowledgments

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Contributors

Languages