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]
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.

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.