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 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
  • 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, 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 command palette to search across actions, recent commands, and hidden utility operations
  • 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, overlay Session panel, 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
  • Configurator GUI and full config file control
  • Zoom, freeze, click highlights, auto-numbered arrows, presenter mode, and light passthrough for clean callouts
  • Context menu, selection tools (Alt-drag or V), copy/paste, duplicate/delete shapes, properties panel, 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
  • Radial menu at cursor (middle-click) for quick tool/color picks and size adjustments
  • 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 top strip has shapes/overflow popovers, current-binding shortcut badges, width-aware degradation, and minimized restore tabs.
  • The four-pane side palette keeps Draw, Canvas, Session, and Settings workflows organized and remembers per-pane scrolling.
  • Toolbars are configurable: show/hide individual items, collapse side sections, reorder top tools/top controls/side sections, and save the result to TOML. See Toolbars.
  • The configurator has global search with scoped matches across tabs, sections, sessions, boards, presets, profiles, and keybindings.

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)

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, 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)
  • F2 or F9 toggles the toolbars
  • F6 enters light passthrough while Wayscriber has focus; use a global wayscriber --light-toggle shortcut to get back out
  • Middle-click opens the radial menu at cursor for quick tool/color selection
  • Escape or Ctrl+Q exits the overlay

Installation

Ubuntu / Debian

The Wayscriber .deb requires Ubuntu 25.04+ or Debian 13 (trixie)+ because it depends on libgtk4-layer-shell0. On older Debian-based systems, use the source-build options below. Pop!_OS 22.04 also has GTK older than the default build requires, so 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)

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

NixOS / Nix

Run without installing:

nix run github:devmobasa/wayscriber

Install to profile:

nix profile install github:devmobasa/wayscriber

Add to NixOS configuration (flake-based):

# flake.nix inputs
inputs.wayscriber.url = "github:devmobasa/wayscriber";

# In configuration
environment.systemPackages = [
  inputs.wayscriber.packages.${pkgs.system}.default
];

Configurator (optional):

nix profile install github:devmobasa/wayscriber#wayscriber-configurator

Build from source (any distro)

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

First Run and Keybinds

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

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

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
  • F2 or F9 toggles the toolbars
  • F11 opens the configurator (if installed)
  • 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+K opens the command palette. While it is open, use arrows/Home/End to navigate, Ctrl+U to clear, and Ctrl+Backspace to delete the previous word.
  • 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 covers drawing basics, including the middle-click radial menu for quick tool/color changes.
  • Replay it 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 search; just start typing to filter shortcuts.

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 side toolbar is where most runtime UI management lives. It has four top-level panes:

  • Draw pane: colors, presets, thickness, and tool-specific controls.
  • Canvas pane: pages, boards, actions, zoom, and step controls.
  • Session pane: Open, Save As, Info, Clear, recent sessions, and Manager. See Sessions and Session Manager for named-session workflows.
  • Settings pane: status/toolbar toggles, config file/configurator shortcuts, section toggles, and toolbar customization.

Side toolbar sections can be collapsed from their headers while working. Toolbar customization changes are saved to config.toml, so the next overlay or daemon start keeps the same visible items and order.

See Toolbars for the top strip, GTK4/builtin frontend selection, minimized restore tabs, shortcut badges, and width-aware overflow behavior.

Toolbars

Wayscriber has a compact top strip for fast drawing controls and a larger side palette for the rest of the active workflow. Press F2 or F9 to toggle both bars.

Top strip

The top strip keeps the frequent controls close to the canvas:

  • drawing tools and a Shapes popover;
  • annotation actions such as Text, Sticky Note, Screenshot, and Highlight;
  • quick colors plus the current-color picker and screen eyedropper;
  • Undo, Redo, Clear, drag, minimize, and pin controls.

The screenshot button is hidden by default. Enable top.utility.screenshot in the overlay Customize tab, the configurator, or ui.toolbar.items.

Short current keybindings appear as badges on tools, actions, and the first eight quick colors. The badges follow your configured bindings rather than showing hard-coded defaults. Longer modifier chords remain in tooltips. When the strip gets narrow, color swatches reduce first, lower-priority controls move into an overflow popover, and the remaining controls use a compact presentation.

Side palette

The side palette is split into four panes:

  • Draw: colors, presets, thickness, and tool-specific controls.
  • Canvas: actions, boards, pages, zoom, and step controls.
  • Session: Open, Save As, Info, Clear, recent sessions, and Manager.
  • Settings: layout mode, section toggles, configurator/config shortcuts, and the toolbar customization editor.

Each pane remembers its own scroll position. Sections can collapse to their header, and the active pane and collapsed sections persist across restarts.

The Draw pane’s color section and the color picker popup both include a screen eyedropper button. It enters a modal crosshair with a magnified pixel loupe; click to apply the sampled color, or press Escape/right-click to cancel.

The minimize button collapses either bar to a small edge restore tab; it does not make the toolbar unreachable. Pinning and full visibility remain separate controls.

GTK4 and builtin frontends

Default builds include two frontends with the same controls and configuration:

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

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

Simple, Regular, and Advanced are non-destructive layout presets. Explicit item choices survive mode changes. The overlay Customize tab and configurator can:

  • show or hide supported tools, controls, and side sections;
  • reorder top tools, top controls, and side-section blocks;
  • restore the built-in order.

These edits are stored under ui.toolbar.items. Unknown future IDs are preserved when an older version saves the file.

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.

Overlay Session panel

The overlay Session panel is in the side toolbar. Use it 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 panel.

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.

Pages

  • Each board has multiple pages for step-by-step walkthroughs.
  • Previous/next page: Ctrl+Alt+Left / Ctrl+Alt+Right
  • New/duplicate/delete page: Ctrl+Alt+N / Ctrl+Alt+D / Ctrl+Alt+Delete

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.

Radial menu

  • Open/close: middle-click while idle.
  • Hover to preview; left-click to apply a tool/color.
  • Right-click or Escape dismisses the menu.
  • Scroll adjusts active tool size (thickness or eraser size).
  • Shapes and Text entries expand to quick sub-tools.

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

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

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)
  • Toolbars: F2 or F9
  • Status bar: F4 (F12 is the alternative)
  • Presenter mode: Ctrl+Shift+M
  • Click highlights: Ctrl+Shift+H
  • 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.

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

  1. Start on monitor A and draw a few strokes.
  2. Press Ctrl+Alt+Shift+ArrowRight to move output focus to monitor B.
  3. Confirm toolbar/status now render on monitor B.
  4. Draw on monitor B, then switch back with Ctrl+Alt+Shift+ArrowLeft.
  5. 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

Daemon mode with a toggle keybind:

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:

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

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.

Search and navigation

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: status bar toggle/position/style, help overlay styling, click highlight settings (including highlight ring), frozen badge, context menu
  • UI toolbar: layout mode, section visibility (pages, presets, actions, step controls), 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).

Toolbar editing

The UI tab controls broad toolbar behavior such as layout mode, pinned startup state, icon-only mode, section toggles, context-aware UI, offsets, and force-inline mode.

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. The same saved order is written to ui.toolbar.items.order in config.toml.

Overlay toolbar customization

The overlay also has toolbar customization from the side toolbar:

  • Open the Settings drawer, then use Customize toolbar or the Customize tab.
  • 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.

The side toolbar also has a Sections tab for section-level toggles, and side sections can be collapsed from their headers while working.

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 panel. 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. Runtime changes made from the overlay toolbar, such as toolbar visibility/order and section toggles, are saved back to the same config file.

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.

Toolbar visibility and order

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

[ui.toolbar.items]
hidden = [
  "top.utility.screenshot",
  "top.tool.blur",
  "side.group.presets",
]
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.

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

Status bar toggles, badges, frozen badge, help overlay filtering, and GNOME output/fullscreen hints. 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 status bar.

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

Enable/disable right-click menus.

ui.toolbar

Frontend selection, layout mode, section visibility, presets, marker opacity slider, delay sliders, tool preview, minimized state, active side pane, offsets, and force-inline behavior.

  • ui.toolbar.backend = "auto" | "gtk" | "builtin": select the toolbar frontend.
  • 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. The overlay Customize tab and the configurator Toolbar Visibility tab both write these values. Supported groups can be moved up/down; the overlay also supports drag reorder. Unknown future IDs are preserved across saves.

Simple, Regular, and Advanced provide non-destructive visibility baselines; explicit shown/hidden choices survive a mode switch. See Toolbars.

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 overlay Session panel 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.

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, 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

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

The presets section can be shown in the side toolbar and can display apply/save/clear toasts. 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
  • --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.

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.

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.

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.
  • Capture shortcuts need external tools for best results (see Installation → Build from source if you are not using packages).

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

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.

Release Notes

These docs track the latest release only. Current source version: v0.9.21.

Recent user-facing updates:

  • The screen eyedropper samples a drawing color from the displayed desktop with a magnified pixel loupe. Press I, open it from either color interface, or use the command palette.

  • The toolbar overhaul adds a compact top strip, four-pane side palette, persistent customization, minimized restore tabs, width-aware overflow, and shortcut badges.

  • Default builds can use GTK4 toolbars on supported layer-shell compositors and fall back to the builtin Cairo frontend where GTK cannot run.

  • Light passthrough now defaults to F6 while the overlay has focus.

  • The command palette has broader action coverage plus improved keyboard navigation and query editing.

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.