---
name: hd-recording-mac
description: >
  macOS platform companion to hd-recording — the Apple-specific half of recording
  screen + window video from Hydrogen Desktop. The recorder ladder, codec choice,
  the max-duration cap, audio-only narration, and the "● Recording" indicator live
  in hd-recording (adom/hd-bootstrap); THIS skill carries only what's true on macOS:
  HD's native recorder is NOT available here (it's #![cfg(windows)]), so recording
  goes through the in-app getDisplayMedia recorder, pup per-tab, or the AD desktop
  relay — and the Screen Recording TCC grant gates the desktop paths. Mirror of
  hd-recording-windows (the native WGC/DXGI recorder). Trigger words — record macos,
  screen recording mac, record kicad mac, native recording windows-only,
  screencapturekit, avfoundation, getdisplaymedia mac, screen recording permission,
  tcc grant recording, desktop_record_start macos.
---

# hd-recording (macOS) — no native recorder; use getDisplayMedia / pup / AD

This is the **macOS half** of `hd-recording`. The recorder priority ladder, codec
tradeoffs (h264 vs h265), the `maxSeconds` cap + `reason`, audio-only narration
(`adom-cli hydrogen audio`), and the "● Recording" badge are cross-platform and live in
the generic **hd-recording** skill — read that first. This skill only documents what's
Apple-specific.

## ⭐ There is no native macOS recorder (be honest about this)

HD's native recorder — `crates/hd-control/src/recorder.rs` — is **`#![cfg(windows)]`**.
On macOS it is **not compiled in**:

- `POST /recording/native/start` returns `{ok:false, error:"native recording is
  Windows-only"}`, and `GET /recording/native/sources` has nothing to enumerate.
- `adom-cli hydrogen recording start --share …` routes to that endpoint, so it **fails
  on macOS** — it does not produce a file.
- **Per-window recording ("record kicad" scoped to one window) does not exist on
  macOS** — that capability is HD-native-only, hence Windows-only.

A ScreenCaptureKit / AVFoundation native recorder is the obvious macOS analog of the
Windows WGC/DXGI path, but **it is not yet built.** Do not claim HD has a
ScreenCaptureKit recorder.

## The macOS recording paths (what actually works here)

Per the source ladder, on macOS skip the native rungs and use:

1. **In-app `getDisplayMedia` recorder** — the Recording dropdown in the editor toolbar
   (`EditorNav.svelte` + `recordingStore.ts`/`audioCaptureStore.ts`). Records the HD
   workspace (and/or mic) → a single `.webm` uploaded to the workspace `recordings/`.
   This is the in-HD path. **It DOES assert a display wake-lock** while running (see
   [hd-screen-lock-mac]) — release it by stopping the recording.
2. **pup per-tab — `adom-desktop browser_record_start {sessionId}`** — a clean CDP
   screencast of one Chrome tab, no wake-lock, coexists with everything.
3. **AD host desktop — `adom-desktop desktop_record_start {confirmDesktopNotTabRecording:true}`**
   — the whole-desktop fallback on macOS. Whole-desktop ONLY (no per-window), Chrome
   `getDisplayMedia` → holds the wake-lock, writes a `.webm` into AD's bridges-cache
   (NOT `~/project/recordings/`). **Verify the cap first:** `adom-desktop status` must
   list the `record` capability.

## macOS gotcha — the Screen Recording TCC grant

The desktop-scoped paths (AD `desktop_record_start`, and any `getDisplayMedia` capture
of the screen) are gated by macOS **TCC: System Settings → Privacy & Security → Screen
Recording** must allow the recording app. Without that grant the capture is black /
empty even though the call "succeeds." If a desktop recording comes back blank, check
the Screen Recording grant first.

## NOT here (lives in the Windows companion)

The native WGC/DXGI recorder — `Windows.Graphics.Capture` per-window + DXGI Desktop
Duplication full-screen → Media Foundation hardware H.264/H.265 → mp4 in
`~/project/recordings/`, the `/recording/native/*` endpoints, `adom-cli hydrogen
recording start --share`, and per-window `{source:"window:X"}` scoping (no picker, no
"you're sharing" banner, no wake-lock) — are all Windows-only; see
`hd-recording-windows`. None of that machinery exists on macOS.