Adom Bridge (macOS)

@@ -1,131 +1,94 @@ --- name: adom-bridge-recording-description: Record the user's screen with Adom Bridge's consent-gated desktop recorder. Use when the user says "record my screen", "record my desktop", "desktop recording", "record a demo", "make a webm clip", "start recording", "stop recording", or asks about the recorder HUD. Covers desktop_recorder_open, desktop_record_start/stop/status/list, desktop_recorder_close, where .webm files land, and how long they are kept. Recording a browser TAB is the Puppeteer bridge's feature (browser_record_start), not this skill.+description: Record the user's Mac screen or one window to an MP4 with Adom Bridge's native recorder (ScreenCaptureKit + the Apple media engine). Use when the user says "record my screen", "record my desktop", "record this window", "record a demo", "make a video of", "screen recording", or when an AI needs a video of what it is driving. Covers desktop_record_start / _stop / _status / _list / _encoders and the window-mode spellings, every argument (display or window target, fps, h264/h265, system audio, cursor, bitrate / quality / maxBitrate, maxDurationMs, keep), the reply fields, and how to pull the file. Tab recording inside a pup browser is the pup bridge's own browser_record_* instead. --- -# Adom Bridge: Screen Recording+# Adom Bridge: screen recording on macOS (1.9.229+) -Adom Bridge (Adom Bridge) records the whole desktop to a `.webm` file through a-**visible, consent-gated recorder HUD**. This skill covers that desktop-recorder. Recording a single browser tab is a different feature owned by the-Puppeteer bridge (see "Tab recording is NOT this" at the bottom).+Adom Bridge records a whole **display** or **one window** to a real `.mp4` on the+user's Mac, natively: ScreenCaptureKit captures, the Apple media engine encodes+(H.264 High or HEVC Main), and the system audio mix rides along as AAC. No+browser, no picker, no HUD. macOS shows its own screen-recording indicator in+the menu bar for the whole take, which is the user's signal that recording is on.+The same verbs and fields work on the Windows line, so one caller covers both. -## The model: consent by transparency+Needs the **Screen Recording** permission for Adom Bridge (System Settings >+Privacy & Security > Screen Recording). Without it, start fails with+`errorCode: "permission_required"`. -The recorder is a visible Chrome window in the bottom-right corner of the-user's screen, always on top. It shows:--- the recording status and a manual Stop button-- the **reason** you supplied, rendered right in the HUD title--`reason` is REQUIRED on both `desktop_recorder_open` and-`desktop_record_start`. A recording can never start silently: the user always-sees that recording is happening and why. The reason is also written to a-sidecar `.json` next to each clip.--The HUD persists across multiple short clips (a "session"). Only-`desktop_recorder_close` (or 5 minutes idle) dismisses it.--## Pick the right verb first--| User said | Use |-|---|---|-| "record a pup" / "record the tab" / "record this Chrome page" | `browser_record_start` (Puppeteer bridge, tab-scoped, no HUD) |-| "record my screen" and Hydrogen is available | Hydrogen's built-in `recording start --share screen` |-| "record everything on screen including KiCad / Fusion / OS dialogs / multiple apps switching" | `desktop_record_start` with `confirmDesktopNotTabRecording: true` |-| "record a pup tab AND a parallel desktop video at the same time" | Both at once: `browser_record_start` on the tab and `desktop_record_start` on the desktop |--Wrong verb means wrong content: the desktop recorder captures whatever is on-the monitor at frame time. If the target window is occluded behind the IDE or-Slack, the clip shows those apps, not the target.--## The guardrail: confirmDesktopNotTabRecording--`desktop_record_start` REQUIRES `confirmDesktopNotTabRecording: true`.-Without it, the call fails with `errorCode: desktop_record_needs_confirmation`-and an error string explaining the alternatives (browser_record_start,-Hydrogen, or pass the confirm). This is intentional friction: acknowledge-that you understand this captures the WHOLE desktop, not a tab. The confirm-must be passed on every `desktop_record_start` call, even within one session.--## Verb flow+## The verbs  ```bash-# 1. (Optional) Open the HUD without starting a clip, so the user knows-#    ahead of time you are about to record.-adom-bridge desktop_recorder_open '{"reason":"About to record the KiCad export demo"}'-# -> { "opened": true, "reason": "..." }--# 2. Start a desktop clip. HUD opens if not already open; recording begins.-adom-bridge desktop_record_start '{-  "reason":"Parallel desktop angle alongside Hydrogen ralph-loop tab capture",-  "confirmDesktopNotTabRecording": true,-  "monitor":"primary",-  "fps":30,-  "audio":false-}'-# -> { "ok":true, "recordingId":"rec-1", "filePath":"...\\rec-desktop-....webm", ... }--# 3. Drive KiCad / Fusion / whatever you are demoing.--# 4. Stop this clip. The HUD stays open, ready for the next clip.-adom-bridge desktop_record_stop '{"recordingId":"rec-1"}'-# -> { "ok":true, "filePath":"...", "sizeKB":4231, "durationMs":18432 }--# 5. Check state at any time.-adom-bridge desktop_record_status-# -> { "hudOpen": true, "reason": "...", "currentRecording": ..., "clipsThisSession": ... }--# 6. List completed clips with sidecar metadata (including reason).-adom-bridge desktop_record_list-# -> { "recordings": [{recordingId, filePath, sizeKB, durationMs, reason, mtime}] }--# 7. When done: close the HUD (auto-stops any active clip first).-adom-bridge desktop_recorder_close-# -> { "ok":true, "sessionSummary":{"clipCount":3, "totalSizeKB":12390, "reason":"...", "clips":[...]} }+adom-bridge desktop_record_encoders                       # what this Mac can encode (hardware first)+adom-bridge desktop_record_start '{"monitor":0}'          # main display, system audio on+adom-bridge desktop_record_start '{"titleContains":"KiCad","codec":"h265"}'   # one window+adom-bridge desktop_record_status '{"recordingId":"rec-..."}'                 # live counters+adom-bridge desktop_record_stop '{"recordingId":"rec-..."}'                   # finalise (sub-second)+adom-bridge desktop_record_list                           # finished files, newest first+adom-bridge pull_file '{"filePaths":["<path from stop>"]}'                    # fetch the MP4 ``` -### Argument reference (desktop_record_start)--- `reason` (REQUIRED string): why you are recording; renders in the HUD title-  and the sidecar JSON-- `confirmDesktopNotTabRecording` (REQUIRED bool): must be `true`, see above-- `monitor` (optional): `'primary'` | `'all'` | int, default `'primary'`-- `fps` (optional int, default 30)-- `audio` (optional bool, default false)-- `videoBitsPerSecond` (optional int, default 4000000)-- `maxDurationMs` (optional int, default 600000)--For monitor selection data, `desktop_list_monitors` enumerates all monitors-with physical and logical bounds, DPI, scale, and the primary flag.--## The user can stop you--The HUD has a manual Stop button. A user click converges through the same-code path as your `desktop_record_stop` call. Do not fight it: if the user-stops manually, treat the clip as complete and react accordingly.--## Where files land, and retention--- Each finished clip is a single `.webm` (VP9). The exact on-disk path comes-  back in `filePath` on start/stop and in `desktop_record_list`.-- Pull clips to your container with `pull_file`:--```bash-adom-bridge pull_file '{"filePaths":["C:\\...\\rec-desktop-....webm"], "saveTo":"/tmp"}'-```--- Adom Bridge's disk janitor auto-prunes its recordings directory-  (`%TEMP%\adom-bridge-recordings`) with generous caps: 2 days age,-  40 files, 3 GB total. Pruning is oldest-first, so the newest files-  (including an in-progress recording) always survive. Still: pull anything-  the user wants to keep promptly rather than treating the desktop as-  long-term storage.+`desktop_record_window_start` / `_stop` / `_status` are the window-mode+spellings of the same verbs (hwnd or titleContains required).++## Arguments to desktop_record_start++| Arg | Default | Meaning |+|---|---|---|+| `monitor` | 0 | Display index: 0 = main display, then left to right. `"primary"` works too. Ignored when a window target is given. |+| `hwnd` | none | Record ONE window by id (the CGWindowID `desktop_list_windows` returns as `hwnd`). |+| `titleContains` | none | Record the first window whose title or app name contains this (case-insensitive). |+| `fps` | 30 | 1..60. The capture rate ceiling; a still screen sends fewer frames. |+| `codec` | `h264` | `h264` (High profile, plays everywhere) or `h265` (HEVC Main, about half the size). |+| `audio` | display: true, window: false | The system audio mix (macOS 13+), AAC 48 kHz stereo, on the same clock as the video. |+| `cursor` | true | `false` hides the pointer, so a window the AI drives is not shown with the user's mouse crossing it. |+| `bitrate` | none | Bits/s. Constant bitrate at this rate. |+| `quality` | none | 1..100. Constant quality instead of bitrate targeting. |+| `maxBitrate` | 2x the mean | Bits/s peak for the default VBR or for `quality`. |+| `maxDurationMs` | display: 30 min, window: none | Auto-stop. Hard cap 2 h. |+| `keep` | false | Keep the file out of the recordings janitor (otherwise 2 days / 40 files / 3 GB, oldest first). Also accepted on stop. |++Default rate control is peak-constrained VBR sized to the resolution (about 33+Mbit/s mean for a 1440p display at 30 fps, peak twice that): a still screen costs+almost nothing, fast motion gets up to the peak.++## Window takes record the WINDOW++A window target captures the window itself, not a rectangle of the screen. It keeps+recording when other windows cover it or when it moves, and the frame is the+window's own size. A window minimised to the Dock cannot be captured+(`window_not_found`); a window that closes mid-take ends the take cleanly+(`captureItemClosed: true`, the file up to that point is kept).++## What comes back++Start: `recordingId`, `kind` (desktop|window), `path`, `title`, `width`, `height`,+`fps`, `codec`, `audio`, `encoder` (e.g. `com.apple.videotoolbox.videoencoder.ave.avc`),+`hardwareEncoder`, `framePath: "gpu"`, `rateControl` (vbr|cbr|quality),+`bitrate`, `maxBitrate`, `quality`, `cursorCaptured`.++Status (and stop): `state` (recording|stopping|finalised|failed), `running`,+`elapsedMs`, `frames` (written), `capturedFrames`, `captureFps`, `repeatedFrames`+(keepalive frames written while the screen was still, so the timeline stays real),+`audioFrames`, `droppedFrames`, `lastFrameAgoMs`, `bytes`, `durationMs`,+`autoStopped`, `captureItemClosed`, `kept`.++A take that auto-stopped stays registered until `desktop_record_stop` collects it;+`desktop_record_status` with no id lists every registered take.++## Errors++| errorCode | Meaning |+|---|---|+| `permission_required` | Screen Recording is not granted to Adom Bridge. |+| `window_not_found` / `missing_target` | The window id or title matched nothing / window mode got no target. |+| `bad_codec` / `bad_monitor` | Unsupported codec / display index out of range. |+| `no_active_recording` / `ambiguous_recording` | Stop without an id when zero / several takes are running. |+| `recording_not_found` | Unknown or already-collected id. |+| `record_failed` | The recorder could not start or finalise; `error` says why. |  ## Tab recording is NOT this -Recording a BROWSER TAB (a pup window, a Chrome page, "record this tab") is-the Puppeteer bridge's feature: `browser_record_start` / `browser_record_stop`.-It is tab-scoped, needs no HUD, runs concurrently per tab, and captures the-tab regardless of OS foreground state. Its documentation ships in the pup-bridge's own skill; install it with `sync_skills`.+Recording one tab inside a pup browser session is the Puppeteer bridge's own+`browser_record_start` / `_stop` (CDP screencast, works with the browser in the+background). Use this skill for the screen or a native app window.