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

Config Reference

This is a compact map of the config file. For the full list of settings, see config.example.toml in the repo.

drawing

Defaults for pen color/thickness, eraser behavior, marker opacity, fill, font options, hit testing, and undo limits. Use drawing.drag_tools to customize drag mappings per left, right, or middle mouse button, including optional colors for each modifier binding.

presets

Quick tool slots for saving full per-tool profile snapshots. Current presets can include tool_settings and drag bindings; legacy presets with only tool/color/size still work.

arrow

Arrowhead length, angle, and head placement.

performance

Buffer count, vsync, max fps, and UI animation fps.

  • buffer_count = 3 is the balanced default. 2 uses less render-buffer memory and 4 uses more; increasing it does not increase the FPS cap.
  • enable_vsync = false enables low-latency drawing by avoiding the compositor frame-callback/vsync cadence floor.
  • max_fps_no_vsync = 120 caps no-vsync rendering. Use 144, 165, 240, or higher only when it matches the display and the machine handles it.
  • max_fps_no_vsync = 0 is uncapped and is mostly for profiling; avoid it as a normal default because it can spin CPU/GPU hard.
  • ui_animation_fps = 30 is the default for toolbar and UI effects. Raise it to 60 for smoother effects at the cost of more redraws; it does not change the drawing FPS cap.
  • Set enable_vsync = true when tear-free presentation matters more than input latency.

With WAYSCRIBER_PERF_LOG=1, the perf.input_to_paint_latency proxy=input_to_wayland_commit line reports an input-to-Wayland-commit proxy metric. It is not end-to-end display latency; compositor scheduling and display scanout can add more latency outside Wayscriber.

history

Undo/redo playback delays and the optional Step toolbar section.

ui

Theme/motion preferences, status HUD toggles, badges, help overlay filtering, and GNOME output/fullscreen hints.

  • theme = "auto" | "dark" | "light" selects overlay and toolbar chrome. auto currently resolves to dark.
  • reduced_motion = "auto" | "on" | "off" controls UI animation. on disables motion; auto currently behaves like off until system-preference integration lands.
  • status_bar_interactive = true lets the board, page, color, tool, and Help chips open their corresponding surfaces. Set it to false for display-only, click-through HUD. Includes multi-monitor controls:
  • ui.multi_monitor_enabled (output focus cycling)
  • ui.active_output_badge (show active output in status bar)
  • ui.preferred_output (pin GNOME fallback output)

ui.status_bar_style

Font size, padding, and colors for the chip HUD. The HUD degrades to fit 80% of the viewport, while frozen/zoom/pan/editing states stack as badge pills above it.

ui.click_highlight

Click highlight colors, radius, outline thickness, duration, pen-color sync, and the optional persistent ring while the highlight tool is active.

ui.input_hud

The on-screen keystroke/click HUD: enabled, the capture mode (auto | overlay | system), the position anchor (a 3x3 grid from top-left to bottom-right), show_mouse, show_bare_modifiers, combine_repeats, display_ms, fade_ms, max_entries, and font_size. Chips use the status-bar style tokens, so they match the rest of the overlay chrome.

overlay mode shows only what Wayscriber itself receives and needs no permissions. system mode reads /dev/input through libinput to report everything on your seat — including input going to the app underneath during light passthrough — and needs a build with the input-monitor feature plus read access to the input devices, which normally means input group membership:

sudo usermod -aG input "$USER"   # then log out and back in

When that is unavailable, the HUD falls back to overlay mode; auto does so silently, while an explicit system request explains what stopped it. System mode sees every keystroke on the seat, including passwords typed into other applications, so it is off by default and chip labels are never logged or saved.

presenter_mode.enable_input_hud forces the HUD on while presenting.

ui.context_menu

Enable/disable right-click menus.

ui.toolbar

Frontend selection, side-layout placement, layout complexity, full/micro display, section visibility, presets, marker opacity slider, delay sliders, ink preview, minimized state, legacy side-pane state, offsets, and force-inline behavior.

  • ui.toolbar.backend = "auto" | "gtk" | "builtin": select the toolbar frontend.
  • ui.toolbar.side_layout = "pill" | "panel": pill is the default and removes the standalone side palette. panel restores the deprecated four-pane palette.
  • ui.toolbar.layout_mode = "simple" | "regular" | "advanced": choose the baseline section complexity independently of side_layout (full remains an alias for regular).
  • ui.toolbar.top_display_mode = "full" | "micro": choose the persisted top-strip form. F2 also reaches a runtime-only hidden step; F9 directly toggles visibility.
  • ui.toolbar.show_presets: show the 3–5-slot presets island. It drops before other islands under width pressure.
  • ui.toolbar.show_zoom_actions: show both the Zoom section in the Canvas… overflow popover and the persistent bottom-right zoom chip. The chip shows the live percentage with zoom-out, zoom-in, Fit, and (while zoomed) Lock controls.
  • ui.toolbar.show_boards_section, show_pages_section, show_actions_advanced, show_step_section, and show_delay_sliders: control the corresponding sections inside Canvas… under pill mode and the classic Canvas pane under panel mode.
  • ui.toolbar.show_tool_preview: show the active tool glyph beside an ink dot using the current drawing color and width with an automatic contrast outline.
  • ui.toolbar.items.hidden: stable IDs for hidden toolbar buttons, actions, or side sections.
  • ui.toolbar.items.shown: explicit items that remain visible against the selected layout preset.
  • ui.toolbar.items.order.top_tools: saved order for top toolbar tool buttons.
  • ui.toolbar.items.order.top_controls: saved order for top utility controls.
  • ui.toolbar.items.order.side_sections: saved order for side toolbar section blocks.

The screenshot button (top.utility.screenshot) is hidden by default. top.group.quick-colors hides the contextual pill’s swatches but keeps its current-color chip. The configurator writes authored visibility and order defaults to config.toml. The overlay Customize view treats those values as seeds and stores direct item visibility and order overrides in the generated runtime-ui.toml file. Authored section-visibility toggles continue to update config.toml. Supported groups can be moved up/down; the overlay also supports drag reorder. Unknown future IDs and fields are preserved across supported-version saves.

Simple, Regular, and Advanced provide non-destructive visibility baselines; explicit shown/hidden choices survive a mode switch. Canvas, Session, and Settings live in top-strip overflow popovers under the default pill layout. See Toolbars.

Generated runtime UI preferences

This is application state, not a config.toml section. Wayscriber writes toolbar pin/minimized state, the active legacy pane and collapsed sections, individual item visibility/order, and per-board pins to $XDG_DATA_HOME/wayscriber/runtime-ui.toml (normally ~/.local/share/wayscriber/runtime-ui.toml). Inspect, recover, or reset it from the overlay Settings popover; do not hand-edit it. See Config File Overview.

ui.help_overlay_style

Font and color styling for the help overlay.

presenter_mode

Hide UI chrome, force click highlights, tool behavior, and presenter toasts.

boards

Named boards, backgrounds, default board, max count, auto-create, pan settings, badges, and persistence.

  • boards.pan_enabled: enable Space + left-drag panning on solid-color boards.
  • boards.show_pan_badge: show the pan hint in the status bar or as a floating badge.
  • Panned solid boards expose Reset Canvas Position and a Zoom submenu from the right-click menu.

board

Legacy whiteboard/blackboard settings (kept for compatibility and configurator support).

tablet

Stylus support when built with the tablet feature flag.

capture

Screenshot enablement, save directory, filename templates, and clipboard behavior. Clipboard paste also accepts copied PNG/JPEG image data and local image files from file managers.

session

Persistence settings, autosave, storage location, per-output, compression, and backups.

  • restore_tool_state saves the last pen color, thickness, font size, arrow placement, and status bar state.
  • per_output keeps separate default sessions per monitor when enabled.
  • storage = "auto" | "config" | "custom" selects the default session directory.
  • max_file_size_mb, compression, and backup settings protect large or corrupt session files.

Named sessions are selected with --session-file <PATH>, not by adding a path under [session]. The top-strip Session popover can Open, Save As, Info, Clear, reopen recent sessions, and jump to the configurator. The configurator Session tab can rename/reveal/ forget catalog entries and can duplicate, move, or clear inactive session files when no overlay or daemon is running.

updates

Update notifications only — Wayscriber never installs anything.

  • check = true lets the daemon ask wayscriber.com once per interval whether a newer release exists. WAYSCRIBER_DISABLE_UPDATE_CHECK=1 overrides this for a run.
  • notify = true shows one desktop notification per release. With it off, the notice still appears in the About window and the tray menu.
  • interval_hours = 24 sets the gap between checks (minimum 1, maximum 720).

See Updating for what is sent, where the result is cached, and how packagers remove the check at build time.

keybindings

Full keyboard shortcut map, including board/page navigation, selection editing, step markers, arrow label resets, light passthrough (toggle_light_mode), output focus (focus_prev_output / focus_next_output), the command palette, toolbar visibility (toggle_toolbar, default F9), the top-strip cycle (cycle_toolbar_display, default F2), and the screen eyedropper (pick_screen_color).

The screen eyedropper defaults to I and is also available from the toolbar, color picker, and command palette. Rebind it if you prefer another key:

[keybindings.colors]
pick_screen_color = ["I"]

Selection copy/paste defaults to Ctrl+Alt+C / Ctrl+Alt+V; the context menu defaults to Shift+F10 and Menu as keyboard alternatives to right-click.

toggle_light_mode defaults to F6, but that is a Wayscriber in-overlay shortcut. Once light passthrough is active, do not rely on that in-overlay shortcut to get back out; use compositor/global shortcuts that call wayscriber --light-toggle and the light-draw commands.

Full reference: https://github.com/devmobasa/wayscriber/blob/main/config.example.toml