wayscriber/docs/SETUP.md

Complete Setup Guide

Installation

Package installs (recommended when available)

If you installed wayscriber via a package (deb/rpm/aur), enable the user service:

systemctl --user enable --now wayscriber.service

The service keeps the daemon running in the background; you only need a keybind to toggle the overlay.

Configurator setup (no CLI)

If you installed wayscriber-configurator, you can set this up entirely in GUI:

1. Open wayscriber-configurator.
2. Go to the Daemon tab.
3. Click Install/Update Service.
4. Click Enable + Start.
5. Set your shortcut and click Apply Shortcut.

Desktop-specific shortcut handling:

• GNOME: creates/updates a GNOME custom shortcut that runs wayscriber --daemon-toggle.
• GNOME migrations: Install/Update Service and Apply Shortcut remove stale ~/.config/systemd/user/wayscriber.service.d/shortcut.conf files so old portal settings do not override GNOME behavior.
• KDE/Plasma: writes a systemd user drop-in with WAYSCRIBER_ENABLE_PORTAL_SHORTCUTS=1 and WAYSCRIBER_PORTAL_SHORTCUT for portal global shortcut handling.
• Hyprland: light passthrough controls use native Hyprland bindings, not the portal shortcut path.

Quick Install

Run the install script:

./tools/install.sh

This will:

1. Build the release binary
2. Copy it to ~/.local/bin/wayscriber
3. Tell you how to add Hyprland keybind

Manual Install

If you prefer manual installation:

# Build
cargo build --release

# Copy to user bin
mkdir -p ~/.local/bin
cp target/release/wayscriber ~/.local/bin/
chmod +x ~/.local/bin/wayscriber

# Make sure ~/.local/bin is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Hyprland Keybind Setup

Method 1: Systemd user service + toggle (preferred when available)

systemctl --user enable --now wayscriber.service

Add the toggle keybinding to ~/.config/hypr/hyprland.conf:

# wayscriber - Screen annotation daemon (Super+D to toggle)
bind = SUPER, D, exec, wayscriber --daemon-toggle

Use only one toggle binding. Duplicate SUPER+D entries 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.

Method 2: Daemon autostart via compositor (no systemd)

Add to ~/.config/hypr/hyprland.conf:

# wayscriber - Screen annotation daemon (Super+D to toggle)
exec-once = wayscriber --daemon
bind = SUPER, D, exec, wayscriber --daemon-toggle

Then reload:

hyprctl reload

Now press Super+D to toggle the overlay on/off!

Light passthrough controls on Hyprland

Light passthrough needs compositor/global shortcuts because Wayscriber deliberately passes keyboard and pointer input to the app below while passthrough is active. The default Ctrl+Shift+L binding is a Wayscriber in-overlay shortcut, not an OS-level shortcut; use the bindings below for reliable control after passthrough starts.

The configurator can install a native Hyprland include file for this. Manual equivalent for Arch + Hyprland:

# wayscriber - light passthrough controls
$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; verify on your mouse)
bind = , mouse:275, exec, $wayscriber --light-toggle

Use --light-draw-on on key/button press and --light-draw-off on release for draw-while-held. The unbind lines prevent duplicate manual bindings for these same keys from firing twice. If your shortcut environment does not resolve wayscriber, replace it with the absolute path from command -v wayscriber.

Light passthrough on KDE Plasma / Fedora KDE

Enable the daemon first:

systemctl --user enable --now wayscriber.service

The configurator can set up the main overlay toggle through the desktop portal. Light passthrough controls are manual for now: add global shortcuts in KDE System Settings that run these commands:

wayscriber --light-toggle
wayscriber --light-draw-toggle
wayscriber --light-draw-on
wayscriber --light-draw-off

Use --light-toggle for passthrough on/off and --light-draw-toggle for sticky drawing. Draw-while-held needs a shortcut system that can run one command on press and another on release; if your KDE shortcut UI only supports activation commands, use the sticky draw toggle instead.

Light passthrough still requires layer-shell support. If Wayscriber reports that light mode requires layer-shell, your session is using a fallback path where passthrough is not available.

GNOME: Fedora Workstation and Ubuntu GNOME

GNOME setup works for the normal overlay toggle:

systemctl --user enable --now wayscriber.service

Then use the configurator's Daemon tab, or create a GNOME custom shortcut that runs:

wayscriber --daemon-toggle

Light passthrough mode is not currently available on GNOME sessions where Wayscriber uses the xdg-shell fallback. In that fallback, keyboard passthrough cannot be made reliable, so --light-toggle is intentionally disabled instead of pretending to pass input through.

Method 3: One-Shot Mode (Alternative)

For quick one-time annotations without daemon:

# Run directly (not recommended - daemon mode is better)
wayscriber --active

This starts a fresh overlay each time. Exit with Escape.

Note: We recommend using daemon mode with Super+D instead as it preserves your drawings.

Usage Flow

Daemon Mode Workflow (Recommended)

1. Daemon starts automatically → Runs in background with system tray icon (systemd user service or compositor autostart)
2. Press Super+D → Drawing overlay appears
3. Draw your annotations → All tools available
4. Press Escape or Ctrl+Q → Overlay hides (daemon keeps running)
5. Press Super+D again → Overlay reappears with previous drawings intact

No system tray/StatusNotifier watcher? Start the daemon with wayscriber --daemon --no-tray (or set WAYSCRIBER_NO_TRAY=1) to skip the tray icon; the Super+D toggle still works.

One-Shot Mode Workflow (Alternative)

1. Run command → Fresh drawing overlay appears
2. Draw your annotations → All tools available
3. Press Escape → Drawing overlay closes completely
4. Run command again → New fresh overlay (previous drawings lost)

Note: Daemon mode with Super+D is recommended as it preserves your drawings when you toggle the overlay.

Verification

Test the setup:

# Test binary is accessible
which wayscriber

# Test daemon mode
systemctl --user status wayscriber.service || wayscriber --daemon &

# Test keybind
Press <kbd>Super+D</kbd> (should show overlay)
Press <kbd>Escape</kbd> (should hide overlay)

Autostart

• If you enabled wayscriber.service, systemd handles autostart.
• If you used compositor autostart, the exec-once line starts wayscriber on login.

Troubleshooting

Keybind not working?

• Check hyprctl reload was run
• Check for conflicts: hyprctl binds | grep "SUPER, D"
• Make sure you only defined the toggle once
• Try a different key combo
• If wayscriber is not found from the compositor, use the absolute path from command -v wayscriber

Binary not found?

• Check PATH: echo $PATH | grep .local/bin
• Add to PATH if missing (see Manual Install)
• Restart terminal after PATH change

Want different key?

• Edit hyprland.conf
• Examples:
  • SUPER, D → Super+D
  • ALT, D → Alt+D
  • CTRL SHIFT, 2 → Ctrl+Shift+2

Uninstall

rm ~/.local/bin/wayscriber
# Remove keybind from hyprland.conf

Recommended Setup

Best setup (daemon mode):

1. Install: ./tools/install.sh
2. Add to hyprland.conf:

   exec-once = wayscriber --daemon
   bind = SUPER, D, exec, wayscriber --daemon-toggle
   

3. Reload: hyprctl reload
4. Use: Press Super+D to toggle overlay

Done! Drawings persist, tray icon available. ✨