wayscriber

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

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

Screenshots

Demo Video

View demo (wayscriber.com)

demo.mp4

Why wayscriber?

Annotate live over any app/window on any monitor without rearranging your workspace
Draw shapes, arrows, and text (with fill toggle) to explain steps, give demos, or build quick guides
Redact screen regions and capture screenshots with one keypress
Toggle instantly from a lightweight background daemon
Persist your work — canvases and tool state restore after restarts (CLI override + tray config toggle)
Presenter helpers — click highlights and screen freeze while apps keep running

Supported Compositors

Works on layer-shell compositors (wlroots, Smithay-based like Niri/Cosmic, Plasma KDE/KWin, Hyprland, Sway, Wayfire, River) with an xdg fallback for GNOME.

Tested environments

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

Features

Drawing & Editing

Freehand pen, translucent highlighter, eraser (circle/rect), straight lines, rectangles/ellipses with fill toggle, arrows, multiline text + sticky notes with smoothing; selection editing + properties panel; undo/redo; quick size/color changes via hotkeys or scroll; color picker + palettes.

Board Modes

Whiteboard, blackboard, and transparent overlays with isolated frames and auto pen contrast. Snap back to transparent with Ctrl+Shift+T. Use board pages (prev/next/new/duplicate/delete) for multi-step walkthroughs.

Capture & Screenshots

Full-screen saves, active-window grabs, and region capture to file or clipboard using grim, slurp, and wl-clipboard. Falls back to xdg-desktop-portal if missing.

Session Persistence

Opt-in per board/monitor storage that restores your canvas plus pen color & thickness. One-off overrides via --resume-session / --no-resume-session; the tray checkmark flips the config on disk.

Toolbars & UI

Floating toolbars (pin/unpin with F2/F9), preset slots, icon or text modes, color picker, extended palettes, status bar, page controls, and in-app help overlay (F1/F10).

Presets

Save tool + color + size (plus optional fill/opacity/text settings) into 3-5 slots for fast recall. Apply with 1-5, save with Shift+1-Shift+5.

Presenter Helpers

Click highlights with configurable colors/radius/duration. Presenter mode (Ctrl+Shift+M) hides UI chrome and forces click highlights for clean demos. Screen freeze (Ctrl+Shift+F) to pause what viewers see while apps keep running. Screen zoom (Ctrl+Alt + scroll) with lock/pan for callouts.

Zoom & Callouts

Zoom is built-in for spotlighting details during demos, with controls that match ZoomIt muscle memory:

Zoom in/out: Ctrl+Alt + scroll or Ctrl+Alt++/Ctrl+Alt+-
Reset zoom: Ctrl+Alt+0
Lock zoom view: Ctrl+Alt+L
Pan zoom view: middle drag or arrow keys

Quick Start

1. Install (Debian/Ubuntu repo, auto-updates):

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  # optional GUI: sudo apt install wayscriber-configurator

2. Run:

wayscriber --active

3. Draw — use your mouse. Press F1 or F10 for help, Escape to exit.

For other distros or running as a daemon, see Installation and Usage.

Installation

Debian / Ubuntu (repo – 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
# Optional GUI configurator
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 (optional):

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

Fedora / RHEL (repo – 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
# Optional GUI configurator
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 (optional):

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)

yay -S wayscriber        # from source
yay -S wayscriber-bin    # prebuilt binary
# Optional GUI configurator:
yay -S wayscriber-configurator

NixOS / Nix

Run without installing:

nix run github:devmobasa/wayscriber

Install to profile:

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

Add to NixOS configuration (flake-based):

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    wayscriber.url = "github:devmobasa/wayscriber";
  };

  outputs = { nixpkgs, wayscriber, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [{
        environment.systemPackages = [
          wayscriber.packages.x86_64-linux.default
        ];
      }];
    };
  };
}

Development shell:

nix develop github:devmobasa/wayscriber

From Source

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
# Binary: target/release/wayscriber

Optional install script:

./tools/install.sh

Optional Dependencies

For the best screenshot workflow, install:

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

See https://wayscriber.com/docs/ for the latest documentation.

Usage

One-Shot Mode

Launch wayscriber when you need it, exit when done:

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

Bind to a key (Hyprland example):

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

Press F1/F10 for help, F11 for configurator, Escape or Ctrl+Q to exit.

Daemon Mode

Run wayscriber in the background and toggle with a keybind:

systemctl --user enable --now wayscriber.service

Add keybinding (Hyprland):

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

Reload your config:

hyprctl reload

Use --no-tray or WAYSCRIBER_NO_TRAY=1 if you don't have a system tray; otherwise right-click the tray icon for options:

Toggle overlay visibility
Freeze/unfreeze the current overlay
Capture full screen / active window / region
Toggle the help overlay
Flip session resume on/off (writes to config)
Clear saved session data
Open the log folder
Open configurator / open config file / quit

Alternative — use compositor autostart instead of systemd:

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

Service commands:

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

Screenshot Shortcuts

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

Requires wl-clipboard, grim, slurp. Falls back to xdg-desktop-portal if missing. Use --exit-after-capture / --no-exit-after-capture to override whether the overlay closes after a capture. --about opens the About window.

Controls Reference

Press F1 or F10 at any time for the in-app cheat sheet.

Drawing Tools

Action	Key/Mouse
Freehand pen	Drag with left mouse button
Straight line	`Shift` + drag
Rectangle	`Ctrl` + drag
Ellipse/Circle	`Tab` + drag
Arrow	`Ctrl+Shift` + drag
Highlight brush	`Ctrl+Alt+H`
Text mode	`T`, `Click` to position, type, `Enter` to finish
Sticky note	`N`, `Click` to place, type, `Enter` to finish

Board Modes

Action	Key
Toggle Whiteboard	`Ctrl+W`
Toggle Blackboard	`Ctrl+B`
Return to Transparent	`Ctrl+Shift+T`

Colors

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

Size Adjustments

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

Selection & Arrange

Action	Key
Duplicate selection	`Ctrl+D`
Copy selection	`Ctrl+Alt+C`
Paste selection	`Ctrl+Alt+V`
Delete selection	`Delete`
Bring to front/back	`]` / `[`
Nudge selection	Arrow keys (large: `PageUp`/`PageDown`)
Move to edges	`Home`/`End` / `Ctrl+Home`/`Ctrl+End`
Selection properties	`Ctrl+Alt+P`

Pages

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

Editing & UI

Action	Key
Undo	`Ctrl+Z`
Redo	`Ctrl+Shift+Z` / `Ctrl+Y`
Select all	`Ctrl+A`
Eraser	`D`
Toggle eraser mode	`Ctrl+Shift+E`
Clear all	`E`
Cancel action	`Right-click` (while drawing) / `Escape`
Context menu	`Right-click` (idle) / `Shift+F10` / `Menu`, `Arrow keys` + `Enter`/`Space`
Edit selected text/note	`Enter` (single selection)
Toggle toolbars	`F2` / `F9`
Help overlay	`F1` / `F10`
Configurator	`F11`
Status bar	`F4` / `F12`
Apply preset slot	`1` - `5`
Save preset slot	`Shift+1` - `Shift+5`
Toggle click highlight	`Ctrl+Shift+H`
Toggle freeze	`Ctrl+Shift+F`
Zoom in/out	`Ctrl+Alt` + scroll / `Ctrl+Alt++` / `Ctrl+Alt+-`
Reset zoom	`Ctrl+Alt+0`
Toggle zoom lock	`Ctrl+Alt+L`
Pan zoom view	`Middle drag` / `Arrow keys`
Exit	`Escape` / `Ctrl+Q`

Preset slots can be saved/cleared from the toolbar; edit names and advanced fields in config.toml.

Configuration

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

Create from example:

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

Or use the GUI configurator:

wayscriber-configurator   # or press F11

Key Sections

[drawing]
default_color = "red"
default_thickness = 3.0

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

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

[performance]
buffer_count = 3
enable_vsync = true
max_fps_no_vsync = 60
ui_animation_fps = 30

[ui]
# status bar visibility and position

[board]
# whiteboard/blackboard presets

Session Persistence

Enable via configurator (F11 → Session tab), CLI flags, or the tray checkmark (writes to config).

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

Notes:

When restore_tool_state is enabled (default), the last-used tool settings (including arrow head placement) override config defaults on startup. Disable it in the Session tab or clear the session to force config values.

Tablet/Stylus Support

Tablet support (zwp_tablet_v2) ships in default builds but is disabled at runtime by default:

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

Enable it in config.toml and restart wayscriber. To build without tablet support: cargo build --release --no-default-features (or remove the tablet-input feature).

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

Troubleshooting

Daemon not starting after reboot

User services don't start at boot by default. Enable lingering:

loginctl enable-linger $USER

Or use compositor autostart instead:

exec-once = wayscriber --daemon

Service won't start

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

Overlay not appearing

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

Config issues

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

Environment variables

Common toggles:

WAYSCRIBER_TOOLBAR_DRAG_PREVIEW=0 disables inline toolbar drag preview (default: on)
WAYSCRIBER_TOOLBAR_POINTER_LOCK=1 enables pointer-lock drag path (default: off)
WAYSCRIBER_DEBUG_TOOLBAR_DRAG=1 enables toolbar drag logging (default: off)
WAYSCRIBER_FORCE_INLINE_TOOLBARS=1 forces inline toolbars on Wayland (default: off)
WAYSCRIBER_NO_TRAY=1 disables the tray icon (default: tray enabled)

See docs/CONFIG.md for the full list.

Performance tuning

[performance]
buffer_count = 2
enable_vsync = true
ui_animation_fps = 30

Contributing

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

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

Additional Information

Platform Support

Platform	Status	Notes
Wayland (layer-shell)	✅ Supported	Hyprland, Sway, River, Wayfire, Niri/Cosmic, Plasma/KWin
GNOME	⚠️ Partial	Portal fallback; overlay windowed
X11	❌	Not supported

Comparison with ZoomIt

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

Roadmap

See Satty for capture → annotate → save workflows. wayscriber is designed as an always-available drawing layer.

License & Credits

MIT License — see LICENSE

Acknowledgments

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

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

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

License

devmobasa/wayscriber

Folders and files

Latest commit

History

Repository files navigation

wayscriber

Table of Contents

Why wayscriber?

Supported Compositors

Features

Drawing & Editing

Board Modes

Capture & Screenshots

Session Persistence

Toolbars & UI

Presets

Presenter Helpers

Zoom & Callouts

Quick Start

Installation

Debian / Ubuntu (repo – recommended)

Fedora / RHEL (repo – recommended)

Arch Linux (AUR)

NixOS / Nix

From Source

Optional Dependencies

Usage

One-Shot Mode

Daemon Mode

Screenshot Shortcuts

Controls Reference

Drawing Tools

Board Modes

Colors

Size Adjustments

Selection & Arrange

Pages

Editing & UI

Configuration

Key Sections

Session Persistence

Tablet/Stylus Support

Troubleshooting

Daemon not starting after reboot

Service won't start

Overlay not appearing

Config issues

Environment variables

Performance tuning

Contributing

Additional Information

Platform Support

Comparison with ZoomIt

Roadmap

License & Credits

Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 35

Contributors 4

Uh oh!

Languages