Config File Overview

The config file lives at:

~/.config/wayscriber/config.toml

To start from the defaults:

mkdir -p ~/.config/wayscriber
cp /usr/share/doc/wayscriber/config.example.toml ~/.config/wayscriber/config.toml

If you built from source, use the repo file at config.example.toml. Some distros may install the example under /usr/share/doc/wayscriber/ (path can vary by package).

Applying changes

Use the configurator when you want validation and backups:

wayscriber-configurator

Or edit TOML directly and restart the running overlay or daemon:

systemctl --user restart wayscriber.service

For one-shot mode, close Wayscriber and start it again.

Configured defaults and runtime UI preferences

config.toml is the authored source for configured defaults. The configurator edits those defaults. Wayscriber stores some direct overlay customizations separately so a pin, collapse, or reorder action does not rewrite unrelated configuration:

top and side toolbar pin and minimized state;
the active legacy side pane and collapsed side sections;
individual toolbar item visibility and toolbar item order; and
per-board pin state.

The generated file is $XDG_DATA_HOME/wayscriber/runtime-ui.toml, normally ~/.local/share/wayscriber/runtime-ui.toml. Treat it as application state, not as a second configuration file, and do not hand-edit it. The configured values act as startup seeds; retained runtime overrides are applied on top. Toolbar drag positions and authored choices such as toolbar layout and section visibility still update their corresponding fields in config.toml.

Open the overlay’s Settings… popover to see the complete runtime-state path and status, reset runtime preferences, or recover from a failed save. A newer file version is kept read-only. Resetting a newer or invalid file requires confirmation and first preserves its exact bytes in a recovery artifact whose path is shown in Settings.

Writes are conditional on the exact file and parent directory that Wayscriber inspected. If another process changes or retargets the path, Wayscriber does not overwrite it; it blocks further runtime preference changes until you retry or adopt the freshly inspected disk state. If runtime-state persistence cannot start, overlay changes remain process-only and Settings reports that they will not survive restart.

Low-latency drawing

For live demos, teaching, and screen annotation, use low-latency mode when input responsiveness matters more than tear-free presentation:

[performance]
buffer_count = 3
enable_vsync = false
max_fps_no_vsync = 240
ui_animation_fps = 60

This is a high-refresh example. max_fps_no_vsync controls the drawing redraw cap when vsync is off; use 120 (the default) on common systems, or try 144, 165, 240, or higher if it matches your display and the machine handles the extra rendering work. Use max_fps_no_vsync = 0 only for profiling, because uncapped rendering can spin CPU/GPU hard.

ui_animation_fps controls toolbar and UI effects, not the drawing FPS cap. 60 makes those effects smoother than the default 30, at the cost of extra redraws while animations are active.

Keep buffer_count = 3 unless you have a specific reason to tune it. It is the balanced default: 2 uses less render-buffer memory, while 4 uses more. Buffer count affects how many render buffers are available; it does not raise the FPS cap by itself.

If tear-free presentation matters more than input latency, turn vsync back on:

[performance]
enable_vsync = true

Disabling vsync improves input latency but may allow tearing and higher CPU/GPU usage. Enabling vsync gives smoother tear-free synchronization, but usually adds a frame-cadence floor, especially on 60 Hz displays.

Wayscriber’s perf logging can be enabled with:

WAYSCRIBER_PERF_LOG=1 wayscriber

The relevant line is:

perf.input_to_paint_latency proxy=input_to_wayland_commit

This is an input-to-Wayland-commit proxy metric: it measures from input sample receipt inside the app to Wayland surface commit. Wayland compositor scheduling, display scanout, and hardware can add more latency outside the app. In local continuous-drawing measurements, 120 FPS low-latency mode held p95 around 8-9 ms and p99 around 8-9 ms for this proxy metric; isolated max spikes existed, but p99 stayed under 16 ms.

Interface layout and motion

The redesigned interface is configured under [ui] and [ui.toolbar]:

[ui]
theme = "auto"              # auto, dark, or light; auto currently resolves to dark
reduced_motion = "auto"     # auto, on, or off; on disables UI animation
status_bar_interactive = true

[ui.toolbar]
layout_mode = "regular"     # simple, regular, or advanced complexity
side_layout = "pill"        # pill (default) or deprecated panel
top_display_mode = "full"   # full or micro at startup
show_presets = true
show_zoom_actions = true      # Canvas Zoom section + bottom-right zoom chip
show_tool_preview = false

side_layout and layout_mode solve different problems. The default pill side layout removes the standalone side palette: drawing properties move into the contextual style pill; canvas management moves into the Canvas… overflow popover, bottom-right zoom chip, and chip-HUD board picker; presets move into the top strip; and Session / Settings move into overflow popovers. panel restores the legacy four-pane side palette and shows a once-per-session map to these replacement surfaces.

The Canvas popover’s Boards, Pages, Advanced, Zoom, and Step Undo/Redo sections reuse the existing show_* toggles. In particular, show_zoom_actions controls both the popover’s Zoom row and the persistent ⊖ NN% ⊕ Fit chip; Lock appears while zoomed. No new configuration key is required.

layout_mode changes only the baseline complexity of visible sections. Explicit item visibility choices survive switching between Simple, Regular, and Advanced. Changes made in the configurator are authored defaults; item visibility changes made from the overlay are runtime overrides stored in runtime-ui.toml.

F9 toggles toolbar visibility. F2 cycles the top strip through full, a 44px active- tool micro chip, and hidden. The full/micro choice persists; the hidden cycle step does not. When show_tool_preview = true, the cursor preview uses the active color and width, adds the tool glyph, and outlines itself for contrast.

Hide individual toolbar items or whole side sections with stable IDs:

[ui.toolbar.items]
hidden = [
  "top.utility.screenshot",
  "top.tool.blur",
  "top.group.quick-colors",
]
shown = []

Checked in the configurator means shown. IDs in hidden are explicitly hidden; IDs in shown stay visible against the Simple/Regular/Advanced layout baseline. These explicit choices survive layout-mode changes. Unknown future IDs are preserved across saves so newer configs do not get destroyed by an older binary.

The same controls in the overlay’s Customize view create runtime overrides instead of rewriting these lists. Use Reset runtime preferences in overlay Settings to return to the configured visibility and order defaults.

top.group.quick-colors controls the quick swatches in the contextual style pill. The current-color chip stays visible so the full picker remains reachable. The 3–5-slot presets island follows show_presets rather than a per-slot item ID.

Reorder the supported groups with ui.toolbar.items.order:

[ui.toolbar.items.order]
top_tools = [
  "top.tool.select",
  "top.tool.pen",
  "top.tool.marker",
  "top.tool.eraser",
]

top_controls = [
  "top.utility.text",
  "top.utility.sticky-note",
  "top.utility.screenshot",
  "top.utility.clear-canvas",
]

side_sections = [
  "side.group.colors",
  "side.group.thickness",
  "side.group.actions",
  "side.group.pages",
  "side.group.boards",
  "side.group.settings",
]

Empty lists use the built-in order. Known IDs omitted from a non-empty list are appended in their default order. Side section ordering uses runtime section blocks; detailed tool-option sections such as eraser mode, polygon sides, and font can be hidden but are not independently orderable.

Named sessions

Default persistence is configured under [session]:

[session]
persist_transparent = true
persist_history = true
restore_tool_state = true
per_output = true
storage = "auto"
max_file_size_mb = 50

Use --session-file when you want a named session for a lecture, meeting, or project:

wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session
wayscriber --session-info --session-file ~/Documents/lecture-04.wayscriber-session
wayscriber --clear-session --session-file ~/Documents/lecture-04.wayscriber-session

--session-file uses the exact selected file and implies persistence for that run. It does not create missing parent directories, rejects directories/symlinks/special files for foreground Open/Save As flows, and conflicts with --no-resume-session.

See Sessions and Session Manager for CLI, overlay, and configurator workflows.

Keyboard shortcuts