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. Runtime changes made from the overlay toolbar, such as toolbar visibility/order and section toggles, are saved back to the same config file.

Low-latency drawing

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

[performance]
enable_vsync = false
max_fps_no_vsync = 120

Use 120 as a strong default on common systems. 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.

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.

Toolbar visibility and order

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

[ui.toolbar.items]
hidden = [
  "top.utility.screenshot",
  "top.tool.blur",
  "side.group.presets",
]
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.

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.