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

> Discover how Omarchy handles screen capture and recording using Wayland tools like slurp and grim. Understand the technical implementation for seamless screen recording.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-18

---

**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:

```bash
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):

```bash
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):

```bash
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:

```bash
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`:

```bash
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`:

```bash
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

```bash
omarchy screenshot                    # smart mode, default editor

omarchy screenshot region slurp       # explicit mode and backend

```

### Screen Recording

```bash
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

```bash
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.