How Screen Capture and Recording Work in Omarchy: A Technical Deep-Dive

Omarchy implements screen capture and recording as lightweight Bash wrappers around Wayland-native tools—using slurp, grim, and gpu-screen-recorder with optional MPV-based webcam overlay—coordinated through a shared region picker and environment-driven configuration.

Omarchy's approach to screenshots and screen recordings prioritizes composability and minimal latency. Rather than monolithic applications, the system exposes discrete command-line tools that integrate with the broader Omarchy ecosystem. This article examines the implementation details, configuration options, and extension points for developers and power users.

Architecture Overview: The Region Picker Pattern

At the heart of Omarchy's capture system lies region selection, implemented in bin/omarchy-capture-region. This script serves as the foundation for both screenshots and recordings, providing consistent geometry parsing across workflows.

The region picker supports four modes:

• smart – Automatically selects the most relevant region (window under cursor, then monitor)
• region – Free-form rectangle selection via slurp
• windows – Chooses from detected window rectangles
• fullscreen – Captures entire monitor without interaction

The underlying implementation uses hyprctl and slurp to freeze the compositor and return normalized geometry strings. In bin/omarchy-capture-region (lines 56–63), the core rectangle resolution logic handles monitor and window detection:

get_rectangles() { monitor_rects; window_rects; }
while IFS= read -r rect; do … done   # resolves best match

This shared foundation ensures that screenshot and recording workflows behave identically when selecting capture targets.

Screenshot Implementation: Grim with Clipboard Integration

The bin/omarchy-capture-screenshot script orchestrates the full screenshot pipeline. Its responsibilities span directory preparation, cursor management, image capture, clipboard synchronization, and notification delivery.

Execution Flow

1. Parse mode and backend – Defaults to smart mode with slurp processing
2. Freeze and select – Invoke omarchy-capture-region with --keep-freeze to maintain compositor pause
3. Disable hardware cursors – Prevent cursor artifacts via cursor:no_hardware_cursors
4. Capture with grim – Write PNG to configured directory
5. Clipboard copy – Pipe image to wl-copy --type image/png
6. Notify and editor launch – Display thumbnail with action to open in configured editor

From bin/omarchy-capture-screenshot (lines 32–66):

MODE="${1:-smart}"
PROCESSING="${2:-slurp}"
{ read -r FREEZE_PID; read -r SELECTION; } < <(omarchy-capture-region "$MODE" --keep-freeze)
grim -g "$SELECTION" "$FILEPATH"
wl-copy --type image/png <"$FILEPATH"
omarchy-notification-send "Screenshot saved…" --image "$FILEPATH" \
  --exec "$(printf '%q %q' "$SCREENSHOT_EDITOR" "$FILEPATH")"

Cursor and Compositor State Management

A critical implementation detail: the script temporarily disables hardware cursors during capture to prevent cursor movement from appearing in frozen frames. The original setting is restored via trap handlers that execute on script exit, ensuring cleanup even on interruption.

Screen Recording: GPU-Screen-Recorder with Audio Pipeline

Screen recording in Omarchy leverages gpu-screen-recorder for hardware-accelerated encoding, with bin/omarchy-capture-screenrecording handling orchestration. This script extends the region picker pattern with audio source multiplexing and optional webcam compositing.

Recording Workflow

1. Parse flags – Handle --with-desktop-audio, --with-microphone, --with-webcam, --fullscreen
2. Select target – Reuse omarchy-capture-region unless fullscreen or portal mode forced
3. Start webcam overlay – Launch MPV with av://v4l2 input if requested
4. Configure audio – Build pipe-separated device list for gpu-screen-recorder
5. Execute recorder – Spawn background process with 60fps CFR output
6. Post-process – Trim first frame, normalize audio, notify completion

From bin/omarchy-capture-screenrecording (lines 41–73):

for arg in "$@"; do
  case "$arg" in
    --with-desktop-audio) DESKTOP_AUDIO="true" ;;
    --with-webcam)        WEBCAM="true" ;;
    # …

  esac
done
target=$(select_capture_target)   # uses omarchy-capture-region

[[ $WEBCAM == "true" ]] && start_webcam_overlay "$target"
gpu-screen-recorder "${capture_args[@]}" -k auto -f 60 -fm cfr \
  -o "$filename" "${audio_args[@]}" &

Webcam Overlay Implementation

When --with-webcam is specified, the start_webcam_overlay function launches MPV with specialized parameters:

mpv --no-border --no-osc --ontop \
    --geometry="${width}x${height}+${pos_x}+${pos_y}" \
    --vf=crop="ih*3/4:ih" \
    "av://v4l2:${WEBCAM_DEVICE}"

The overlay is cropped to portrait aspect (3:4) and positioned in the bottom-right corner of the captured region. The script waits for the window to appear via hyprctl polling before proceeding with recording initiation.

Environment Configuration and Customization

Omarchy exposes multiple environment variables for capture customization. These are read at script invocation with sensible defaults:

Variable	Default	Purpose
OMARCHY_SCREENSHOT_DIR	$HOME/Pictures	Screenshot output directory
OMARCHY_SCREENRECORD_DIR	$HOME/Videos	Recording output directory
OMARCHY_SCREENSHOT_EDITOR	tensaku-edit	Image editor for notification action
OMARCHY_SCREENRECORD_USE_PORTAL	unset	Force XDG Desktop Portal backend
OMARCHY_WEBCAM_DEVICE	/dev/video0	V4L2 device for overlay

Example configuration in ~/.config/environment.d/omarchy.conf:

OMARCHY_SCREENSHOT_DIR="$HOME/Screenshots"
OMARCHY_SCREENSHOT_EDITOR=gimp
OMARCHY_SCREENRECORD_DIR="$HOME/Recordings"

The screenshot editor variable is read on line 19 of bin/omarchy-capture-screenshot:

SCREENSHOT_EDITOR="${OMARCHY_SCREENSHOT_EDITOR:-tensaku-edit}"

Portal Backend Alternative

When OMARCHY_SCREENRECORD_USE_PORTAL is set, Omarchy delegates to the XDG Desktop Portal API rather than direct gpu-screen-recorder invocation. This enables:

• Permission mediation for sandboxed applications
• PipeWire-based capture for applications requiring it
• Standardized interaction with diverse compositors

The portal path bypasses region selection entirely, using the portal's native picker UI. This tradeoff sacrifices Omarchy's smart region detection for broader compatibility.

Integration with Omarchy Ecosystem

Capture scripts leverage several Omarchy utilities for consistent behavior:

• omarchy-notification-send – Rich notifications with thumbnails and actionable buttons
• omarchy-toggle-indicator – Top-bar recording state visualization (implemented via /tmp file presence)
• hyprctl integration – Cursor warping, window detection, and compositor state queries

The toggle indicator enables visual feedback during recording: a script monitors gpu-screen-recorder process state and updates the top bar through the Omarchy panel system.

Command Reference

Basic Screenshot

omarchy screenshot                    # smart mode, default editor

omarchy screenshot region slurp       # explicit mode and backend

Screen Recording

omarchy screenrecord                                      # region, no audio

omarchy screenrecord --with-desktop-audio --with-webcam   # region with audio and camera

omarchy screenrecord --fullscreen --with-microphone       # fullscreen capture

Direct Region Picker Usage

target=$(omarchy-capture-region smart --match-monitor)
echo "$target"   # outputs: region:1920x1080+0+0

Summary

• Unified region selection – omarchy-capture-region provides consistent geometry parsing for both screenshots and recordings across smart, region, window, and fullscreen modes.
• Wayland-native tools – grim for screenshots, gpu-screen-recorder for hardware-accelerated encoding, with slurp handling interactive selection.
• State management – Temporary cursor and compositor modifications are trapped and restored to prevent capture artifacts.
• Extensible configuration – Environment variables control directories, editors, audio sources, and backend selection without script modification.
• Ecosystem integration – Notifications, toggle indicators, and editor launching leverage standard Omarchy utilities for cohesive UX.

Frequently Asked Questions

How do I change the default screenshot editor in Omarchy?

Set the OMARCHY_SCREENSHOT_EDITOR environment variable to your preferred executable. The default is tensaku-edit, but you can configure GIMP, Inkscape, or any image editor. Add export OMARCHY_SCREENSHOT_EDITOR=gimp to ~/.config/environment.d/omarchy.conf for persistent configuration.

Does Omarchy support recording with both desktop and microphone audio simultaneously?

Yes. Pass both --with-desktop-audio and --with-microphone flags to omarchy screenrecord. The script constructs a pipe-separated audio device list that gpu-screen-recorder mixes into the output. The source code in bin/omarchy-capture-screenrecording handles device enumeration and flag construction automatically.

Why does the screen freeze before I can select a region?

This is intentional behavior implemented via hyprpicker and slurp integration. The compositor freeze ensures the captured frame matches exactly what you see during selection, preventing cursor movement or animation changes from affecting the capture boundary. The freeze is released immediately after geometry selection or script interruption.

Can I use Omarchy's capture tools without the full desktop environment?

Yes. The core scripts (omarchy-capture-region, omarchy-capture-screenshot, omarchy-capture-screenrecording) depend only on standard Wayland tools (grim, slurp, gpu-screen-recorder, wl-clipboard) and hyprctl for Hyprland integration. Notifications and toggle indicators degrade gracefully when Omarchy-specific utilities are unavailable, though visual feedback will be limited.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}