Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 release. If you need an older version, use the GitHub release notes.

Start here

What you can do

  • Draw on top of any screen
  • Switch between transparent, whiteboard, and blackboard modes
  • Zoom in/out, pan, and reset the view during callouts
  • Draw while zoomed to highlight fine details
  • Save tool presets for instant switching
  • Undo/redo quickly and clear the canvas in one keypress
  • Capture screenshots to file or clipboard
  • Presenter helpers: freeze the screen and show click highlights
  • Save and restore sessions across runs
  • Configure everything with the GUI or the config file

Requirements

  • A Wayland compositor that supports wlr-layer-shell
  • Linux with Cairo, Pango, and Wayland libraries

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, and text tools
  • Whiteboard, blackboard, and transparent overlay modes
  • Session persistence across runs (optional)
  • Fast toggle via daemon and keybind
  • Screenshot capture to file or clipboard
  • Preset slots for instant tool switching
  • Configurator GUI and full config file control
  • Zoom and freeze tools for callouts
  • Context menu and selection tools for editing

Customization

  • Toolbars are configurable, so you can show or hide the sections you care about.

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.

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)

1) Install

If you are on Arch, the AUR packages are easiest:

yay -S wayscriber
# or
paru -S wayscriber

For other distros, see Installation.

2) Run once

Launch a one shot overlay to confirm it works:

wayscriber --active

Press Escape to exit.

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 example:

bind = SUPER, D, exec, pkill -SIGUSR1 wayscriber

Use your compositor settings to bind the same command.

5) Learn the basics

  • F1 opens the help overlay (F10 is the alternative)
  • F11 opens the configurator (if installed)
  • F2 or F9 toggles the toolbars
  • Escape or Ctrl+Q exits the overlay

Installation

Ubuntu / Debian

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

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)

Build from source:

yay -S wayscriber
# or
paru -S wayscriber

Prebuilt binary:

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

Configurator (GUI):

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

Build from source (any distro)

Dependencies:

# Debian/Ubuntu
sudo apt-get install libcairo2-dev libwayland-dev libpango1.0-dev

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

Build:

git clone https://github.com/devmobasa/wayscriber.git
cd wayscriber
cargo build --release

The binary will be at target/release/wayscriber.

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 ~/.local/bin/wayscriber and offers to set up Hyprland keybinds.

Optional capture tools

Wayscriber can use these for fast captures:

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

# Fedora
sudo dnf install wl-clipboard grim slurp

First Run and Keybinds

Wayscriber has two run modes:

One shot mode

Start the overlay immediately and exit when you are done.

wayscriber --active

Good for quick callouts or testing.

Daemon mode

Run in the background and toggle the overlay when needed.

wayscriber --daemon

If you have the user service installed:

systemctl --user enable --now wayscriber.service

Add a keybind that sends SIGUSR1 to toggle the overlay:

bind = SUPER, D, exec, pkill -SIGUSR1 wayscriber

Default keys you should know

  • F1 opens help (F10 is the alternative)
  • F2 or F9 toggles the toolbars
  • F11 opens the configurator (if installed)
  • F4 toggles the status bar (F12 is the alternative)
  • Escape or Ctrl+Q exits the overlay

Overlay vs Daemon

Overlay (one shot)

  • Starts immediately and exits when you close it
  • Simple and predictable
  • Best for quick annotations

Command:

wayscriber --active

Daemon (background)

  • Runs in the background and keeps your drawings between toggles
  • Faster to access during presentations
  • Works well with a keybind

Command:

wayscriber --daemon

If installed, the systemd user service is the most reliable way to keep the daemon running.

Boards and Modes

Wayscriber supports three board modes:

  • Transparent overlay (default)
  • Whiteboard
  • Blackboard

Each mode has its own canvas, so you can switch without losing work.

Default mode keys

  • Toggle whiteboard: Ctrl+W
  • Toggle blackboard: Ctrl+B
  • Return to transparent: Ctrl+Shift+T

You can change these in the config file under [keybindings].

Tools and Shapes

Wayscriber focuses on fast input with simple modifiers.

Core tools

  • Freehand: drag
  • Line: Shift + drag
  • Rectangle: Ctrl + drag
  • Ellipse: Tab + drag
  • Arrow: Ctrl+Shift + drag
  • Text: press T, click to place, type, press Enter

Quick actions

  • Undo: Ctrl+Z
  • Redo: Ctrl+Shift+Z
  • Clear canvas: E
  • Presets: 1-5 apply, Shift+1-5 save (configurable)
  • Thickness up: + or = or scroll down
  • Thickness down: - or _ or scroll up
  • Context menu: Right click or Shift+F10

Use F1 for the full help overlay (or F10).

Capture and Export

Wayscriber includes fast screenshot capture and export tools.

Dependencies

For the best capture workflow, install:

  • wl-clipboard
  • grim
  • slurp

If these are missing, Wayscriber falls back to xdg-desktop-portal.

Default capture keys

  • Full screen: Ctrl+Shift+P
  • Active window: 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

Export

Exports include full boards, cropped content, and board JSON files. Configure defaults under [export] in the config file.

Presenting and Teaching

  • 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.

During the session

  • Freeze the screen to explain without the background moving.
  • Zoom for details, then reset to keep orientation.
  • Clear the canvas when a section is done so the next topic is clean.

Helpful keys

  • Help: F1 (F10 is the alternative)
  • Toolbars: F2 or F9
  • Status bar: F4 (F12 is the alternative)
  • Freeze: Ctrl+Shift+F
  • Zoom: Ctrl+Alt + scroll (Ctrl+Alt+0 to reset)
  • 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.

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

Multi Monitor Tips

  • Enable per output sessions under [session] if you want separate canvases per display.
  • Use the overlay toggle on the monitor you want to annotate.
  • On GNOME fallback, you can set WAYSCRIBER_XDG_OUTPUT to match a specific monitor name.

If you see overlays on the wrong display, check your compositor output names and confirm your config or env vars.

Compositor Guides

Hyprland

Daemon mode with a toggle keybind:

exec-once = wayscriber --daemon
bind = SUPER, D, exec, pkill -SIGUSR1 wayscriber

Reload Hyprland with hyprctl reload.

GNOME

Use Settings -> Keyboard -> Custom Shortcuts.

Choose one of these commands:

  • One shot: wayscriber --active
  • Daemon toggle: pkill -SIGUSR1 wayscriber (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.

KDE

Use System Settings -> Shortcuts -> Custom Shortcuts.

Choose one of these commands:

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

Configurator (GUI)

Wayscriber has a native configurator for editing settings without touching the config file.

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.

What you can change

  • Drawing defaults: color, thickness, font family, weight, style, text background
  • Arrow settings: length, angle, head placement
  • Performance: buffer count and vsync
  • UI: status bar toggle/position/style, help overlay styling, click highlight settings, frozen badge
  • UI toolbar: preset visibility and preset toast feedback
  • Board modes: 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
  • Keybindings: edit all shortcuts in one place

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 code/config.example.toml.

Restart Wayscriber after changing the config to ensure settings apply.

Config Reference

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

drawing

Defaults for pen color, thickness, eraser behavior, font size, and undo limits.

presets

Quick tool slots for saving and applying tool + color + size combinations.

arrow

Arrowhead length, angle, and head placement.

performance

Buffer count and vsync.

ui

Status bar, click highlights, context menu, toolbars, and help overlay styling.

board

Enable whiteboard and blackboard modes and set their colors.

tablet

Stylus support when built with the tablet feature flag.

capture

Screenshot enablement, save directory, filename templates, and clipboard behavior.

export

Export directories, filenames, padding, and background options.

session

Persistence settings, storage location, compression, and backups.

keybindings

Full keyboard shortcut map. Each action can have multiple keys.

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

Profiles and Presets

Tool presets (quick slots)

Presets let you save a tool + color + size combination and switch instantly.

Defaults:

  • Apply preset 1-5 with keys 1 to 5
  • Save preset 1-5 with Shift+1 to Shift+5

Configure them in config.toml:

[presets]
slot_count = 5

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

The presets section can be shown in the side toolbar and can display apply/save/clear toasts.

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
  • --active, -a: start active (one shot overlay)
  • --mode <MODE>: initial mode (transparent, whiteboard, blackboard)
  • --no-tray: disable system tray in daemon mode
  • --clear-session: delete persisted session data
  • --session-info: show session paths and status
  • --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
  • --about: show the About window
  • --help: show help
  • --version: show version

Environment Variables

Wayscriber supports optional environment overrides.

Core overrides

  • WAYSCRIBER_NO_TRAY=1 disables the system tray in daemon mode.
  • WAYSCRIBER_RESUME_SESSION=1 forces session resume on.
  • WAYSCRIBER_CONFIGURATOR=/path/to/wayscriber-configurator sets the configurator path.

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_DEBUG_DAMAGE=1 enables debug damage output.
  • WAYSCRIBER_DEBUG_TOOLBAR_DRAG=1 enables toolbar drag logging.

Systemd Service

If your package installs the user service, you can manage Wayscriber with systemd.

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 pkill -SIGUSR1 wayscriber.

Tray icon is missing

  • Some panels hide StatusNotifier icons.
  • Run with --no-tray if you do not need the tray.

Capture shortcuts do nothing

  • Install wl-clipboard, grim, and slurp.
  • Check your config under [capture].

Configurator does not launch

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

Logs and Debugging

Run Wayscriber with logs:

RUST_LOG=info wayscriber --active

If you use the systemd service:

journalctl --user -u wayscriber.service -f

Include log output when reporting bugs.

Known Limitations

  • Wayland only. X11 is not supported.
  • Requires wlr-layer-shell or the xdg-shell fallback.
  • Some compositors handle fullscreen or input differently.
  • Capture shortcuts need external tools for best results.

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

~/.config/wayscriber/config.toml

Does it work on GNOME and KDE

Yes, using the xdg-shell fallback. Some fullscreen behavior may vary by compositor.

Release Notes

These docs track the latest release only.

Release history is maintained on GitHub:

Contributing (Short)

Contributions are welcome when they fit the project direction.

Start here:

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.