repository·main·Indexed 20 days ago
https://github.com/devmobasa/wayscriberA real-time screen annotation and presentation tool for Linux/Wayland, functioning as a lightweight daemon similar to ZoomIt on Windows. It allows users to draw, zoom, and highlight content over any running application. Key features include a variety of drawing tools (pen, highlighter, shapes, arrows), blur and spotlight effects, persistent drawing boards, click highlights, and screen freeze. It is written in Rust and supports Wayland compositors such as Hyprland, Sway, River, Wayfire, Niri/Cosmic, and Plasma/KWin, with partial support for GNOME.
wayscriber provides a comprehensive suite of presentation and annotation tools:
<kbd>Middle-click</kbd>, color picker with screen eyedropper, and selection via <kbd>Alt</kbd>-drag or the V tool.<kbd>Ctrl+Shift+1..9</kbd>.<kbd>Ctrl+Shift+M</kbd>): Hides UI and forces click highlights.<kbd>Ctrl+Shift+F</kbd>): Pauses the display while apps continue running.<kbd>Ctrl+Alt</kbd> + scroll or <kbd>+</kbd>/<kbd>-</kbd>. Reset zoom with <kbd>Ctrl+Alt+0</kbd>.grim, slurp, and wl-clipboard (automatically installed via package managers) or falls back to xdg-desktop-portal.Wayscriber is a feature-rich annotation and screen capture tool for Linux (Wayland). The following features are currently implemented and available for use:
Wayscriber offers two primary operational modes. Daemon Mode is highly recommended for most users.
In this mode, a background process manages the overlay. This allows your drawings to persist even when the overlay is hidden.
Workflow:
Super+D) to show the drawing overlay.Escape or Ctrl+Q to hide the overlay. The daemon remains running.Tip: If you don't use a system tray, start the daemon with wayscriber --daemon --no-tray or set the environment variable WAYSCRIBER_NO_TRAY=1.
This mode is for quick, one-time annotations where you do not need to save your work.
Workflow:
wayscriber --active.Escape. The process exits completely.# Daemon mode (background)
wayscriber --daemon
# One-shot mode (foreground)
wayscriber --activeWayscriber uses a strict configuration model where config.toml is treated as an immutable source of truth that is only modified through explicit user actions. The system distinguishes between authored configuration (what the user explicitly typed) and effective configuration (the validated, normalized, and clamped values actually used by the application).
Config, and authored Config to ensure that editing one setting never accidentally overwrites others.save_with_backup. This method creates a timestamped .bak file of the previous configuration and uses an atomic rename to ensure the file is never left in a corrupted state.config.toml via explicit user gestures.Config but are not written to disk. These settings are restored to their configured values upon restart.config.toml (written only by the configurator).In multi-monitor setups, you can cycle the overlay focus between different outputs:
Ctrl+Alt+Shift+← or Ctrl+Alt+Shift+→ (default) to move focus between outputs.monitor or display to find output actions.preferred_output key in your configuration or use the environment variable WAYSCRIBER_XDG_OUTPUT.Note: Output switching is blocked while a capture, freeze, or zoom operation is in progress. You must finish or exit those modes first.
Wayscriber uses an authenticated process broker to manage lifecycle and security. The broker is created by the Daemon, active-overlay, About, or explicit update-check runs before any locks are acquired or threads are started.
curl/wget for update checks).wl-paste prefix mode: Returns a bounded sample and stops the helper once the prefix is complete.wl-copy publication: Uses the same 256 MiB cap.Overlays use a CSPRNG generation passed to the candidate. After winning the overlay singleton lock, the candidate publishes a private readiness record containing its generation, PID, and process-start identity. The daemon only marks the child as ready when all three values match. Exit is monitored via pidfd.
Daemon mode provides a persistent background service. Its lifecycle follows these steps:
Daemon::run acquires a daemon lock, installs Unix signal listeners and queue watchers, and publishes a v2 runtime identity.--daemon-toggle publish generation-bound controls that atomically rename an ordered queue reference. The watched queue wakes directly in response.Wayscriber uses a decoupled architecture for toolbars to support multiple frontends (Wayland/Cairo and GTK4):
src/ui/toolbar/model/top_spec.rs defines a renderer-neutral contract. It specifies control IDs, strip/divider/chrome/overflow nodes, events, active/enabled states, labels, tooltips, and shortcut badges. It does not contain geometry or toolkit-specific types.src/backend/wayland/toolbar/view/top/ adapts the contract to the built-in WidgetTree, handling Cairo geometry, hit testing, and popover placement.src/toolbar_gtk/view/top_bar/ adapts the same contract to GTK widgets, managing CSS, drag gestures, and popover lifecycles.To build on or integrate with Wayscriber, it is helpful to understand the high-level lifecycle of the application:
InputState.InputState combined with draw and ui modules update the overlay contents and request renders.config module ensures user preferences are applied across all subsystems.When running in --active mode, Wayscriber uses a Wayland backend to create an overlay for drawing.
The Bootstrap Process:
backend::run_wayland creates a WaylandBackend.smithay-client-toolkit and binds essential protocols: compositor, layer shell, SHM, outputs, seats, and registry.InputState.The Main Loop:
CaptureManager for screenshots.InputState.should_exit is triggered (e.g., via Escape or tray close).Wayscriber separates core configuration from UI state. While config.toml provides the 'seeds' (initial values), direct user manipulations of the UI (like moving the toolbar or pinning a board) are stored as overrides in a separate runtime-state file.
top_position, side_position) and display modes (top_display_mode).config.toml with the overrides in the runtime-state file. Overrides take precedence.