Platform Notes

Per-platform quirks, gotchas, and setup steps beyond what the Installation page covers.

Linux

Wayland

Screen capture under Wayland goes through the xcap crate, which uses PipeWire and the XDG Desktop Portal.

• First-capture permission prompt. The first hotkey press triggers a portal dialog asking which screen(s) Xenocept can capture. Choose your default monitor (or “All screens”). The selection is remembered.
• Compositor support. GNOME, KDE Plasma, Sway, Hyprland, and other major compositors implement the relevant portal interfaces. Older or fringe compositors may not — check that xdg-desktop-portal is installed and running.
• Global hotkeys. Wayland’s hotkey support varies by compositor. If Ctrl+Backquote fails to bind, try alternatives in Hotkeys.

X11

xcap falls back to XGetImage / XShm on X11.

• No permission prompt. X11 doesn’t gate capture per-app; whatever app can read the root window can capture it.
• DPMS / screen blanking. Capturing a blanked screen returns black pixels — that’s by design.
• HiDPI. Captured at native pixel resolution. The overlay scales appropriately.

System Tray Icon

Most modern Linux desktops support the StatusNotifier (Ayatana) protocol, which Xenocept uses for its tray icon. If your environment doesn’t:

• GNOME by default does not show a tray. Install the appindicator extension.
• Plain X11 with no panel: there’s nothing to show the icon in — Xenocept will still run and the hotkey still works.

The tray icon is a convenience, not a requirement. The hotkey is the primary entry point.

macOS

Screen Recording Permission

macOS gates screen capture per-app. The first time Xenocept tries to capture:

1. macOS prompts: “Xenocept would like to record this computer’s screen.”
2. Click “Open System Settings.”
3. Add Xenocept to the allowed apps list.
4. Restart Xenocept — the permission isn’t picked up until the next launch.

Without this permission, capture returns blank/black images.

Capture API

Screen capture uses the xcap crate, which picks the right native API for the running macOS version internally. Those API specifics are xcap’s implementation detail.

macOS Hotkey Defaults

The default global hotkey is Ctrl+Backquote on every platform, including macOS. There is no Cmd-based macOS variant in the current build. The Settings UI shows the current binding.

Tray Icon

The tray icon appears in the menu bar (top-right). Some menu-bar managers (like Bartender) may hide it by default — adjust if needed.

Windows

Capture API

Screen capture uses the xcap crate, which on Windows uses DXGI Desktop Duplication / Windows.Graphics.Capture under the hood. No special permission grants are needed — local capture is allowed by default.

Tray Icon

The tray icon appears in the system tray (bottom-right). Windows hides infrequently-used tray icons by default; pin Xenocept’s icon for easier access via the tray overflow menu.

Defender / SmartScreen Warnings

Unsigned development builds trigger Windows Defender SmartScreen warnings. Click “More info” → “Run anyway” to bypass.

Released builds will be code-signed; SmartScreen will accept them without the warning.

Path Separators

Throughout these docs, paths use forward slashes. On Windows, both \ and / work in most contexts (the Rust file APIs normalize), but if you’re hand-editing config files, prefer escaped backslashes (\\) in JSON strings:

{
  "path": "C:\\Users\\you\\Documents\\xenocept"
}

All Platforms

Firewall / Localhost

Xenocept’s HTTP server is hardcoded to 127.0.0.1:9500. Personal firewalls almost never block localhost-to-localhost traffic, but if you’ve installed something aggressive, double-check it allows 127.0.0.1:9500.

The bind is intentionally localhost-only and is not user-configurable.

Antivirus and Capture

Some endpoint-protection tools flag screen-capture APIs as suspicious. If Xenocept’s capture returns black frames or fails outright, check whether your AV has a quarantine entry for it.