Screen Toolkit

A Noctalia v5 plugin for color picking, OCR, QR/barcode scanning, palette extraction, Google Lens search, annotation, pixel measuring, screen recording, and image sharing.

Attribution

Screen Toolkit was originally created for Noctalia v4 by the author(s) of the legacy screen-toolkit plugin. This repository is an independent Noctalia v5 remake/port by alexander; it is not the original implementation.

Plugin

Field	Value
ID	alexander/screen-toolkit
Entries	Bar widget: widget; control-center shortcut: toggle; panels: panel (tools), result (result view); service: service

Requirements

Install the tools used by the features you want on PATH. Missing tools are reported when that feature is started.

• slurp — region selection
• grim — screen capture
• hyprpicker — pixel color picking
• tesseract — OCR engine (plus your language packs, e.g. tesseract-data-eng)
• imagemagick — image processing
• zbar — QR / barcode scanning (zbarimg)
• curl + jq — image uploads (uguu.se / x02.me) and Google Lens
• ffmpeg + ffprobe — recording / GIF conversion and thumbnail generation
• bc — GIF duration and frame-rate calculations
• stat — recording file size
• pkill — stopping active recording backends
• xdg-open — opening URLs, OCR search results, and shared-link targets

Recording requires at least one backend:

• gpu-screen-recorder — recommended for fullscreen recording, especially on NVIDIA (NVENC)
• wl-screenrec — preferred for region recording and microphone audio
• wf-recorder — fallback recorder for region and fullscreen capture

Optional:

• swappy / satty — annotation editor (Markup tool)
• gimp — fallback annotation editor when swappy/satty are missing
• translate-shell (trans) — OCR translation
• hyprctl — annotate the focused window (Hyprland only)

Compositor support: region tools, measure, annotate and recording work on any Wayland compositor with wlroots protocols. Annotate Window requires Hyprland (hyprctl).

Usage

Add the Screen Toolkit widget to a bar, and/or the shortcut tile in Settings → Control Center shortcuts. Left-click either one opens the main panel (or stops a recording); right-clicking the bar widget quick-picks a color. While a recording is active, the widget and shortcut show a pulsing red dot.

Open the main tools panel:

noctalia msg panel-toggle alexander/screen-toolkit:panel

Open the result panel (shows the last capture/recording output):

noctalia msg panel-toggle alexander/screen-toolkit:result

The tools panel contains the capture actions. When a capture tool finishes, a result panel opens with the output and its actions; close it to return to the tools panel.

Region tools (Color, OCR, QR, Palette, Lens, Measure, GIF/MP4 record, Markup) draw a slurp crosshair — drag to select a region, then release. Recording starts immediately and the bar widget shows the pulsing dot; click the dot, the widget, the shortcut, or the panel's Stop button to end it. Unless "Skip Save Confirmation" is on, the panel then offers Save MP4, Save GIF, Copy, and Discard.

The hide-cursor setting excludes the cursor from recordings and screenshots (default: hidden). Grim excludes the cursor by default; when the setting is disabled, the plugin passes grim's -c flag to include it. gpu-screen-recorder and wl-screenrec receive their corresponding cursor options. wf-recorder does not expose a portable cursor flag, so its behavior depends on the compositor.

• Markup captures the region and opens it in swappy (or satty). Saving happens in that editor; satty saves to your screenshot path automatically. Markup Window shows a crosshair — click the window you want to annotate and it captures that window (Hyprland only).
• Measure reports the region's pixel size and copies it to the clipboard.
• OCR extracts text and copies it to the clipboard. The result includes the capture preview and an editable multiline text area, so you can correct, trim, or extend the OCR output before copying, searching, translating, or sharing it. Detected URLs can be opened directly and detected email addresses can open a mail composer.
• QR decodes a code and copies the text to the clipboard.
• Palette copies the extracted hex colors (one per line) to the clipboard.
• Share uploads the current capture and copies the link (uguu.se by default, or up.x02.me with an API key).

Results are delivered to the clipboard with a notification — the panel itself only holds the tools. Results persist across restarts in the plugin's data directory; the capture previews live in /tmp and are only kept for the session.

Settings

All settings live in Settings → Plugins (gear on the plugin's row).

Setting	Type	Default	Description
screenshot-path	folder	~/Pictures/Screenshots	Where satty saves annotations.
video-path	folder	~/Videos	Where recordings are saved.
filename-format	string	%Y-%m-%d_%H-%M-%S	Filename template; the extension is added automatically.
selected-ocr-lang	string	eng	Tesseract language code; combine with + (e.g. eng+fra).
search-engine-url	string	(Google)	Search URL prefix, or a URL containing {text}. The OCR text is URL-encoded.
x02-api-key	string	(empty)	up.x02.me key for longer-lived, larger uploads.
x02-expiry	select	7d	Link lifetime when an x02 key is set: 1h, 1d, 7d, 30d, or permanent.
share-skip-popover	bool	false	Compatibility setting retained from v4. The v5 result panel copies share links directly.
record-audio-out	bool	false	Record the desktop's audio output.
record-audio-in	bool	false	Record the default microphone.
hide-cursor	bool	true	Exclude the cursor from recordings and screenshots. On Hyprland, screenshots briefly move the pointer off-screen during capture.
record-codec	select	h264	Codec for gpu-screen-recorder fullscreen capture: h264, hevc, or av1. h264 is the safest NVIDIA NVENC default; av1 needs a recent GPU.
record-fps	int	60	Frame rate for gpu-screen-recorder fullscreen capture (15–240).
record-skip-confirmation	bool	false	Save automatically when a recording ends, skipping the save dialog.
record-copy-to-clipboard	bool	false	Finalize to MP4 and copy the file URI when recording ends.
gif-max-seconds	int	30	Cap for GIF recordings (1–600 s).

IPC

The service is a singleton with no output, so the IPC target is all:

noctalia msg plugin alexander/screen-toolkit:service all toggle
noctalia msg plugin alexander/screen-toolkit:service all colorPicker
noctalia msg plugin alexander/screen-toolkit:service all ocr
noctalia msg plugin alexander/screen-toolkit:service all qr
noctalia msg plugin alexander/screen-toolkit:service all palette
noctalia msg plugin alexander/screen-toolkit:service all lens
noctalia msg plugin alexander/screen-toolkit:service all measure
noctalia msg plugin alexander/screen-toolkit:service all annotate
noctalia msg plugin alexander/screen-toolkit:service all annotateFullscreen
noctalia msg plugin alexander/screen-toolkit:service all annotateWindow
noctalia msg plugin alexander/screen-toolkit:service all record
noctalia msg plugin alexander/screen-toolkit:service all recordMp4
noctalia msg plugin alexander/screen-toolkit:service all recordFullscreen
noctalia msg plugin alexander/screen-toolkit:service all recordFullscreenMp4
noctalia msg plugin alexander/screen-toolkit:service all recordStop
noctalia msg plugin alexander/screen-toolkit:service all recordSave
noctalia msg plugin alexander/screen-toolkit:service all recordDiscard

ocrTranslate takes a language code payload:

noctalia msg plugin alexander/screen-toolkit:service all ocrTranslate en

Notes

• This is a port of the legacy v4 screen-toolkit plugin. Tools that relied on freeform v4 QML overlays are adapted: region selection uses slurp, annotation hands off to swappy/satty, and measure reports region dimensions instead of drawing a line overlay. Pin (floating screen overlays) and Webcam Mirror could not be ported — the v5 plugin UI has no canvas or always-on-top surfaces — so they are not included.
• Recording auto-detects its backend: fullscreen uses gpu-screen-recorder when installed (NVENC hardware encoding — the best option on NVIDIA GPUs, where wl-screenrec's VAAPI path is unreliable), falling back to wl-screenrec then wf-recorder. Region capture uses wl-screenrec then wf-recorder, because gpu-screen-recorder cannot record an arbitrary sub-region. Microphone audio is only supported by wl-screenrec; with wf-recorder only system audio is available, and gpu-screen-recorder's audio follows its own source selection.
• Region coordinates are captured in physical pixels; recordFullscreen multiplies the focused output's logical geometry by its scale.
• Files are written to your configured screenshot/video directories and the plugin's persistent data directory (state, color history). Captures in /tmp are transient.
• Network calls: Google Lens upload (uguu.se), share uploads (uguu.se or up.x02.me), and xdg-open for search/URL results.

License

This remake is released under the MIT license. It is an independent v5 port of the original legacy plugin; see Attribution for the original project and source.