wayscriber

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

Screenshots

Demo Video

View demo (wayscriber.com)

demo.mp4

---

Table of Contents

• Why wayscriber?
• Features
• Quick Start
• Installation
• Usage
• Controls Reference
• Configuration
• Troubleshooting
• Contributing
• Additional Information

---

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 with smoothing; 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.

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), icon or text modes, color picker, extended palettes, status bar, and in-app help overlay (F1/F10).

Presenter Helpers

Click highlights with configurable colors/radius/duration. Screen freeze (Ctrl+Shift+F) to pause what viewers see while apps keep running.

---

Quick Start

1. Install (Debian/Ubuntu):

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

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

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

GUI configurator (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

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

GUI configurator (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

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 docs/SETUP.md for detailed walkthroughs.

---

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/runtime folder
• Open configurator / 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+C	Copy entire screen to clipboard
Ctrl+S	Save entire screen as PNG
Ctrl+Shift+C	Select region → clipboard
Ctrl+Shift+S	Select region → save PNG
Ctrl+Shift+O	Capture active window

Requires wl-clipboard, grim, slurp. Falls back to xdg-desktop-portal if missing.

---

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

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

Editing & UI

Action	Key
Undo	Ctrl+Z
Redo	Ctrl+Shift+Z / Ctrl+Y
Eraser	D
Clear all	E
Cancel action	Right-click / Escape
Toggle toolbars	F2 / F9
Help overlay	F1 / F10
Configurator	F11
Status bar	F4 / F12
Toggle click highlight	Ctrl+Shift+H
Toggle freeze	Ctrl+Shift+F
Exit	Escape / Ctrl+Q

---

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

[performance]
buffer_count = 3
enable_vsync = true

[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

Tablet/Stylus Support

Tablet support (zwp_tablet_v2) is enabled by default:

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

To build without tablet support: cargo build --release --no-default-features

See docs/CONFIG.md 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

1. Verify Wayland session: echo $WAYLAND_DISPLAY
2. Ensure compositor supports wlr-layer-shell
3. 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

Performance tuning

[performance]
buffer_count = 2
enable_vsync = true

---

Contributing

Pull requests and bug reports welcome. Priority areas:

• Compositor compatibility testing
• Multi-monitor support
• New drawing tools

Development

cargo fmt
cargo clippy
cargo test
cargo run -- --active

Use ./tools/fetch-all-deps.sh to prefetch crates before offline builds.

Architecture

Project structure

wayscriber/
├── src/
│   ├── main.rs           # Entry point, CLI parsing
│   ├── daemon.rs         # Daemon mode with signal handling
│   ├── ui.rs             # Status bar and help overlay
│   ├── backend/
│   │   └── wayland.rs    # Wayland wlr-layer-shell implementation
│   ├── config/           # Configuration loader and types
│   ├── draw/             # Drawing, shapes, rendering (Cairo/Pango)
│   └── input/            # Input handling, state machine
├── tools/                # Helper scripts
├── packaging/            # Distribution files
├── docs/                 # Documentation
└── config.example.toml

---

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

• Native Wayland layer-shell
• Daemon mode with system tray
• Whiteboard/blackboard modes
• Session persistence (with CLI override + tray config toggle)
• Highlighter & eraser tools
• Additional shapes (filled shapes)
• Color picker
• Multi-monitor support
• Save annotations to image
• Color picker integration with captures/export

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 Hyprland by vaxry
• Similar ideas from Gromit-MPX
• Uses Cairo and smithay-client-toolkit

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