Vellum

Vellum is a small native Wayland overlay for drawing directly over the live desktop.

demo.mp4

Vellum began as a fork of Chameleos by Thomas Lindae.

Compatibility

Vellum requires a Wayland compositor that implements wlr-layer-shell. This includes niri, Sway, Hyprland, river, Wayfire, labwc, KDE Plasma, and COSMIC, though niri is the only compositor currently tested.

Installation

NixOS and Home Manager

Add Vellum to your flake inputs:

inputs.vellum.url = "github:greyxp1/vellum";

Import and enable the module in your NixOS or Home Manager configuration:

{inputs, ...}: {
  # Use homeModules.default for Home Manager.
  imports = [inputs.vellum.nixosModules.default];
  services.vellum.enable = true;

  # Optionally add cache settings for pre-built binaries.
  nix.settings = {
    substituters = ["https://vellum.cachix.org"];
    trusted-public-keys = ["vellum.cachix.org-1:gUB2bSe5JrLoUCOhwM/VwiIKJBwRTBQ5HVhCLaw9vKk="];
  };
}

Building and installing from source

Install the dependencies for your distribution:

Arch dependencies

sudo pacman -S --needed base-devel git rust wayland libxkbcommon fontconfig vulkan-icd-loader

For a PKGBUILD:

depends=('wayland' 'libxkbcommon' 'fontconfig' 'vulkan-icd-loader')
makedepends=('cargo')

Debian 13+ dependencies

sudo apt install build-essential git pkg-config rustup libwayland-dev libxkbcommon-dev libfontconfig-dev libvulkan1
rustup default stable

Fedora dependencies

sudo dnf install cargo gcc git pkgconf-pkg-config wayland-devel libxkbcommon-devel fontconfig-devel vulkan-loader

Then build and install Vellum:

git clone https://github.com/greyxp1/vellum
cd vellum
cargo xtask install

Usage

Start Vellum manually with vellum & or run it as a service:

systemd

Save this as ~/.config/systemd/user/vellum.service:

[Unit]
Description=Vellum screen annotation overlay
After=graphical-session.target
PartOf=graphical-session.target

[Service]
Type=exec
ExecStart=%h/.local/bin/vellum
Restart=on-failure

[Install]
WantedBy=graphical-session.target

Enable the service and start it now:

systemctl --user enable --now vellum.service

Then bind vellum toggle to a compositor shortcut. For example, in niri:

Mod+A { spawn "vellum" "toggle"; }

Controls

Mouse, trackpad, and pen

Action	Mouse	Trackpad	Pen
Draw or manipulate the selection	Left drag	One-finger drag	Drag with the pen tip
Open the radial picker	Right-click	Two-finger click	Briefly press the barrel button while hovering
Choose a tool or color	Hold the right mouse button, move, then release	Open the picker, move, then one-finger click	Hold the barrel button while hovering, move, then release
Erase	Middle drag, or middle-click then left drag	Three-finger tap to toggle, then one-finger drag	Hold the barrel button while drawing or drag with the eraser tip
Change size	Mouse wheel	Two-finger scroll	Mouse wheel or trackpad scroll

Shortcuts and modifiers

Input	Action
Ctrl+Z	Undo
Ctrl+Shift+Z or Ctrl+Y	Redo
Mouse back button	Undo
Mouse forward button	Redo
Ctrl+A	Select all annotations
Backspace or Delete	Delete selected annotations
Escape	Cancel, clear the selection, or leave drawing mode
Ctrl + click in selection mode	Add or remove an annotation from the selection
Double-click selected text	Edit it
Shift while drawing	Constrain the shape
Alt while drawing	Draw triangles, rectangles, and ellipses from their center
F	Toggle shape fill or text background
Space	Freeze or resume the desktop background
Ctrl + scroll	Change opacity
Shift + scroll	Change roundness
Drag a selection handle	Reshape the selection or stretch text
Shift + drag a text handle	Resize text without stretching

While editing text:

Input	Action
Arrow keys	Move the caret. Ctrl+Left/Right moves by word
Home / End	Move to the line's start / end. Add Ctrl for the whole annotation
Shift + navigation key	Extend the text selection
Ctrl+A	Select all text in the annotation
Click / drag	Position the caret / select text. Shift + click extends the selection
Double-click / triple-click	Select a word / line
Typing, Backspace, or Delete	Replace or delete selected text
Shift+Enter	Insert a newline
Enter / Escape	Finish / cancel editing

Configuration

Vellum looks for vellum/config.toml in $XDG_CONFIG_HOME (default ~/.config), then $XDG_CONFIG_DIRS (default /etc/xdg). Use --config PATH to load a specific file or --no-config to skip configuration.

Options

Global

Option	Type	Description
draw_on	string	Where drawing can start: all monitors or only the current monitor
default_tool	string	Startup tool: pen, line, arrow, triangle, rectangle, ellipse, text, eraser, or select
remember_last_tool	boolean	Keep the selected tool when drawing mode is reopened
stroke_size	number	Initial size shared by pen, line, arrow, and shape tools
size_range	table	Optional min and max for scrolling through sizes
steps	table	Optional size, opacity, and roundness scroll increments
stops	table	Optional size, opacity, and roundness scroll stops
default_color	string	Initial CSS color. It must be present in palette
palette	array of strings	Between 2 and 12 CSS colors
feedback_duration_ms	integer	How long property feedback remains visible, from 0 to 60000 milliseconds
clear_on_escape	boolean	Clear annotations when Escape deactivates drawing mode
freeze_on_activate	boolean	Capture a fresh frozen background each time drawing mode is activated
default_fill_shapes	boolean	Initially fill triangles, rectangles, and ellipses
cursor	table	Optional visible cursor override for all tools

Per-tool

Set these properties under [tools.<tool>].

Property	Type	Supported tools	Description
size	number	All except select	Initial logical-pixel size. Pen, line, arrow, and shapes inherit stroke_size
size_range	table	All except select	Overrides the matching global fields
steps	table	See size, opacity, and roundness	Overrides each matching global increment
stops	table	See size, opacity, and roundness	Overrides each matching global list. [] clears it
opacity	number	All except eraser and select	Initial opacity from 0.05 to 1.0. Overrides default_color alpha
roundness	number	pen, line, arrow, triangle, rectangle, text	Initial roundness from 0.0 to 1.0
filled	boolean	triangle, rectangle, ellipse	Initial fill state
background	boolean	text	Whether text starts with an automatic black or white background
cursor	table	All	Overrides the global cursor.visible setting for this tool
font.family	string	text	Ordered CSS font-family list
font.weight	number	text	Weight from 1 to 1000
font.style	string	text	Font style: "normal", "italic", or "oblique"
font.features	table	text	OpenType feature tags (0 disables, 1 enables). For example: zero = 1, tnum = 1, liga = 0

Defaults

See the complete default configuration. The source installer also places a copy under ~/.local/share/doc/vellum.