Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Compositor Guides

Hyprland

For Hyprland Lua, put daemon autostart and the toggle keybind in the matching files:

-- ~/.config/hypr/autostart.lua
o.launch_on_start("wayscriber --daemon")

-- ~/.config/hypr/bindings.lua
o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

Traditional Hyprland config:

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

Reload Hyprland with hyprctl reload. Define the toggle binding only once. If Hyprland does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber.

Light passthrough should use compositor-level binds because the overlay passes normal input to the app underneath. Do not rely on the in-overlay F6 shortcut to get back out after passthrough starts.

Hyprland Lua (~/.config/hypr/bindings.lua):

local wayscriber = "wayscriber"

o.bind("F6", "Toggle Wayscriber light passthrough", wayscriber .. " --light-toggle")
o.bind("XF86Tools", "Toggle Wayscriber light passthrough", wayscriber .. " --light-toggle")
o.bind("SUPER + ALT + D", "Toggle Wayscriber light drawing", wayscriber .. " --light-draw-toggle")

Traditional Hyprland config:

$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
bind = , mouse:275, exec, $wayscriber --light-toggle

GNOME

Use Settings -> Keyboard -> Custom Shortcuts.

Choose one of these commands:

  • One shot: wayscriber --active
  • Daemon toggle: wayscriber --daemon-toggle (run the daemon first)

If you want fullscreen on GNOME, set WAYSCRIBER_XDG_FULLSCREEN=1. If GNOME renders fullscreen as opaque, leave it off or force it with WAYSCRIBER_XDG_FULLSCREEN_FORCE=1.

To target a specific monitor, set WAYSCRIBER_XDG_OUTPUT to a matching output name.

Freeze works on GNOME when the screenshot portal is available and responsive. The first freeze may show a desktop permission prompt, and portal capture can be slower than layer-shell compositor capture.

Light passthrough is not currently available on GNOME sessions that use Wayscriber’s xdg-shell fallback. The fallback cannot reliably pass keyboard input through, so wayscriber --light-toggle is intentionally disabled there.

KDE

Use System Settings -> Shortcuts -> Custom Shortcuts.

Choose one of these commands:

  • One shot: wayscriber --active
  • Daemon toggle: wayscriber --daemon-toggle (run the daemon first)

Light passthrough controls are manual for now: add global shortcuts that run wayscriber --light-toggle and wayscriber --light-draw-toggle. Draw-while-held needs a shortcut system that can run wayscriber --light-draw-on on press and wayscriber --light-draw-off on release; otherwise use the sticky draw toggle. Light passthrough requires layer-shell support.