Skip to content

SETUP.md

Latest commit

 

History

History
256 lines (179 loc) · 8.68 KB

SETUP.md

File metadata and controls

256 lines (179 loc) · 8.68 KB

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 F6 binding is a Wayscriber in-overlay shortcut, not an OS-level shortcut; do not rely on it to exit after passthrough starts. Use the bindings below for reliable control.

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 requires compositor overlay support through layer-shell. If Wayscriber reports that passthrough is unavailable, your session is using a fallback path where regular app windows cannot provide a reliable click-through overlay.

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

Freeze works on GNOME when the screenshot portal is available and responsive; the first use may show a desktop permission prompt. Portal capture can be slower than compositor screencopy, and mixed-DPI or multi-monitor setups may depend on client-side crop behavior.

Light passthrough mode is not available in the regular app on stock GNOME Wayland. GNOME's xdg-shell fallback does not expose the shell-level overlay behavior needed to keep annotations visible while input goes to apps underneath, so --light-toggle is intentionally disabled instead of pretending to pass input through. A GNOME Shell extension companion would be the real path for that workflow.

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