# Screen recording verbs

Record the desktop/monitors to video; manage the recorder window.

_Part of the [Adom Desktop verb reference](VERB-REFERENCE.md). Invoke as `adom-desktop <verb> '<json>'`._

### `desktop_list_monitors`

List available monitors. v1 returns the primary only; full enumeration is v1.1.

**Returns:** monitors: [{index, name, x, y, width, height, primary}]


### `desktop_record_list`

List completed desktop recording .webm files on disk with their sidecar metadata.

**Returns:** recordings: [{recordingId, filePath, sizeKB, durationMs, reason, mtime}]


### `desktop_record_start`

Start a WHOLE-DESKTOP recording (every pixel on screen, including unrelated apps) via Chrome MediaRecorder + getDisplayMedia. Opens HUD if needed. Reason is REQUIRED. HUD persists across multiple clips in one session — use desktop_recorder_close to dismiss.

**Args:**
  - `audio` — optional bool (default false)
  - `confirmDesktopNotTabRecording` — REQUIRED bool — must be true. Acknowledges that you understand this is full-desktop recording, NOT pup tab recording. If user said 'record a pup' / 'record this Chrome window' / 'record the page', use browser_record_start instead. If user wants generic 'record my screen', Hydrogen's built-in `recording start --share screen` is usually preferable. desktop_record_* is mainly for parallel desktop video alongside Hydrogen tab recording (e.g. ralph-loop screenshot tests).
  - `fps` — optional int (default 30)
  - `maxDurationMs` — optional int (default 600000)
  - `monitor` — optional 'primary'|'all'|int (default 'primary')
  - `reason` — REQUIRED string — explain to the user why you're recording (renders in the HUD title and sidecar JSON)
  - `videoBitsPerSecond` — optional int (default 4000000)

**Returns:** recordingId, filePath (.webm), startedAt, monitor, reason

**Note:** PICK THE RIGHT VERB: 'record a pup' / 'record the tab' / 'record this Chrome page' => browser_record_start (tab-scoped, ~50fps, no foreground requirement). 'record my whole desktop' / 'record across multiple apps' => desktop_record_start with confirmDesktopNotTabRecording:true. Prefer Hydrogen's `recording start --share screen` for casual desktop recording — adom-desktop's desktop recording is mainly for the parallel-with-Hydrogen-tab-capture case.

**Error code:** desktop_record_needs_confirmation when confirmDesktopNotTabRecording is missing/false — read the error and decide if you really want full-desktop or pup-tab recording


### `desktop_record_status`

Status of the desktop recorder HUD and any active clip.

**Returns:** hudOpen, reason, currentRecording, clipsThisSession


### `desktop_record_stop`

Stop the active desktop clip. Finalizes the .webm. HUD stays open in Ready state for the next clip in this session.

**Args:**
  - `recordingId` — optional (active clip if omitted)

**Returns:** recordingId, filePath, sizeKB, durationMs, stopReason


### `desktop_recorder_close`

Close the desktop recorder HUD (ends the session). Auto-stops any active clip first.

**Returns:** sessionSummary: {clipCount, totalSizeKB, reason, clips}


### `desktop_recorder_open`

Open the WHOLE-DESKTOP recorder HUD (visible bottom-right always-on-top window) without starting a clip. Reason is REQUIRED. Same scope as desktop_record_start — the HUD will record the entire desktop, NOT a pup tab.

**Args:**
  - `reason` — required string explaining why you're recording

**Returns:** opened, reason

**Note:** PICK THE RIGHT VERB: for pup tab recording use browser_record_start (no HUD needed, tab-scoped). For generic 'record my screen' use Hydrogen's `recording start --share screen`. Use desktop_recorder_open only when you want a visible HUD on screen during a multi-clip session (e.g. parallel desktop video alongside Hydrogen tab capture).