---
name: hd-captions-mac
description: >
  macOS platform companion to hd-captions — the Apple-specific note on HD's on-screen
  captions. The two caption surfaces, the SECONDS-vs-MILLISECONDS unit trap, ids,
  positions, and the adom-cli / HTTP commands all live in hd-captions
  (adom/hd-bootstrap) and are platform-neutral; THIS skill carries only the one macOS
  difference: the full-DESKTOP overlay (adom-desktop desktop_caption) is a Win32
  click-through window and is NOT implemented on macOS yet (the non-Windows build is a
  stub). The workspace caption (adom-cli hydrogen caption) works the same on macOS.
  Mirror of hd-captions-windows. Trigger words — caption macos, desktop_caption macos,
  desktop overlay mac, screen overlay mac, caption not showing mac, click-through caption mac.
---

# hd-captions (macOS) — only the desktop overlay differs

This is the **macOS half** of `hd-captions`, and it is deliberately short: **almost
nothing about captions is macOS-specific.** The two surfaces, the units (workspace =
SECONDS, desktop overlay = MILLISECONDS), positions/ids/sizes, the `adom-cli hydrogen
caption` command and the raw-HTTP `.../current/caption` fallback all live in the generic
**hd-captions** skill and behave identically here — read that first. There is exactly
**one** macOS-distinct fact, below.

## (1) Workspace caption — fully platform-neutral on macOS

`adom-cli hydrogen caption show/hide` renders **inside the HD workspace webview** via the
workspace-events server → SSE → the frontend `captionStore`. That path has no host-native
code, so it works on macOS exactly as documented in hd-captions (same SECONDS unit, 30s
default / 300s cap, newest-wins, the HTTP fallback). **This is your default on a Mac.**

## (2) ⚠️ Desktop overlay — NOT implemented on macOS

`adom-desktop desktop_caption` (the always-on-top, click-through, whole-screen overlay)
is **Windows-only**. The implementation in `src-tauri/crates/hd-app/src/caption.rs` is a
Win32 layered-window stack (`WS_EX_LAYERED | WS_EX_TOPMOST | WS_EX_TRANSPARENT` popups,
`EnumWindows`-keyed by id) gated entirely behind `#[cfg(windows)]`. The non-Windows
`show_caption_window` is a **stub** that logs *"Caption overlay is only supported on
Windows"* and returns `created=false`. So on macOS:

- `adom-desktop desktop_caption` will fail to actually paint a desktop overlay (the
  command returns, but `visible:false` / no window appears). **Do NOT rely on it for a
  full-screen recording on macOS** — there is no native overlay layer yet.
- For a whole-desktop / other-app (KiCad, Fusion, browser) recording on macOS, there is
  currently **no on-screen caption** equivalent. Caption the **HD workspace** instead
  (surface 1), or narrate via TTS — don't claim a desktop overlay you can't render.

This is an honest gap, not a different mechanism: HD has **no macOS-native desktop
caption overlay** at this time. (The `caption` capability that `adom-desktop status`
advertises reflects the Windows host overlay; treat it as Windows-only until a macOS
overlay ships.)

## NOT here (lives in the Windows companion)

The Win32 always-on-top click-through layered-window implementation — `caption.rs`'s
`#[cfg(windows)]` `show_caption_window` / `destroy_captions`, the `AdomCaptionOverlay`
window class, and the id-as-window-title routing that backs `adom-desktop
desktop_caption` — is the **Windows** delivery; see `hd-captions-windows`.