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

Quick Start
Installation
First Run and Keybinds
The Gift Exchange

What you can do

Draw on top of any screen
Switch between named boards with custom backgrounds (transparent, whiteboard, blackboard, and more)
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
Create multi-line text and sticky notes
Drop numbered step markers and auto-numbered arrows
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, presenter mode, and click highlights
Select/move shapes with Alt-drag or V, then edit in the properties panel
Use the command palette to search and run actions quickly
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, step marker, text, sticky note, marker, and eraser tools
Named boards with custom backgrounds, quick slots, and per-board pages
Session persistence across runs (toggle in tray or config)
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, freeze, click highlights, auto-numbered arrows, and presenter mode for clean callouts
Context menu, selection tools (Alt-drag or V), duplicate/delete shapes, properties panel, and command palette for editing
Radial menu at cursor (middle-click) for quick tool/color picks and size adjustments

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. 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, 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
Middle-click opens the radial menu at cursor for quick tool/color selection
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

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)

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.

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:

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)
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
Ctrl+Shift+H toggles click highlights
Ctrl+K opens the command palette
Ctrl+Shift+B opens the board picker
Ctrl+Alt+Shift+Left/Right moves overlay focus to previous/next output
V toggles the selection tool
Hold Alt and drag to select/move shapes
Ctrl+D duplicates selected shapes
Delete removes selected shapes
Escape or Ctrl+Q exits the overlay

Guided tour and quick help

First launch shows a short guided tour. Space/Enter advances, Backspace goes back, Escape skips.
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

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

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)

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 opens the context menu.
Ctrl+Alt+P toggles the selection properties panel (fill, arrow heads, text background, size).
Duplicate: Ctrl+D
Copy/paste: Ctrl+Alt+C / Ctrl+Alt+V
Nudge: Arrow keys (Shift for larger steps)

Quick controls

Colors: R/G/B/Y/O/P/W/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

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.

Default capture keys

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

Clipboard and file variants

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

Presenting and Teaching

Recommended setup

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

Before you present

Start the daemon ahead of time and do a quick toggle test.
Pick a thicker pen size for visibility on streams and recordings.
If you rely on click highlights, enable them in the configurator or toggle with Ctrl+Shift+H.
Presenter mode hides UI chrome and can force click highlights, so test it once before going live.

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

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

Troubleshooting

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

Compositor Guides

Hyprland

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, marker opacity, fill, 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 (including highlight ring), frozen badge, context menu
UI toolbar: layout mode, section visibility (pages, presets, actions, step controls), marker opacity slider, preset toasts
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
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).

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

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 config.example.toml in the repo.

drawing

Defaults for pen color/thickness, eraser behavior, marker opacity, fill, font options, hit testing, and undo limits.

presets

Quick tool slots for saving tool + color + size, plus optional fill, opacity, font, and arrow tweaks.

arrow

Arrowhead length, angle, and head placement.

performance

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

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

Layout mode, section visibility, presets, marker opacity slider, delay sliders, tool preview, offsets, and force-inline behavior.

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, pinned boards, and persistence.

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.

session

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

keybindings

Full keyboard shortcut map, including board/page navigation, selection editing, step markers, arrow label resets, output focus (focus_prev_output / focus_next_output), and the command palette.

Full reference: https://github.com/devmobasa/wayscriber/blob/main/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 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
--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_TRAY_FORCE_PIXMAP=1 disables themed tray icons (useful for Noctalia/Quickshell).
WAYSCRIBER_RESUME_SESSION=1 forces session resume on.
WAYSCRIBER_CONFIGURATOR=/path/to/wayscriber-configurator sets the configurator path.

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_DRAG_PREVIEW=0 disables inline toolbar drag preview.
WAYSCRIBER_TOOLBAR_POINTER_LOCK=1 enables pointer-lock drag path (experimental).
WAYSCRIBER_DEBUG_DAMAGE=1 enables debug damage output.
WAYSCRIBER_DEBUG_TOOLBAR_DRAG=1 enables toolbar drag 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 pkill -SIGUSR1 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].

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.
Requires wlr-layer-shell or the xdg-shell fallback.
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

Release Notes

These docs track the latest release only.

Release history is maintained on GitHub:

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

Contributing (Short)

Contributions are welcome when they fit the project direction.

Start here:

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

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

Architecture (Short)

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

Keyboard shortcuts

Wayscriber