Adom Bridge

@@ -1,76 +1,106 @@-# Screen recording in Adom Bridge+# Screen recording in Adom Bridge (H.264 / H.265) -![The desktop recorder HUD](recorder.png)--Adom Bridge can record your screen to a video file (`.webm`). Recording is-built so that it can never happen behind your back: whenever an AI records-your desktop, a small recorder window (the HUD) is visible on screen the-whole time.--## What you see when an AI records--The recorder HUD is a small always-on-top window in the bottom-right corner-of your screen. It shows:--- the current recording status and a Start/Stop control-- live Screen / Microphone source toggles-- a **reason line**, right at the top--The reason is required. The AI must state why it is recording ("Recording-the KiCad export demo you asked for", for example) before a recording can-start, and that reason is displayed in the HUD for as long as the session is-open. It is also saved in a small metadata file next to each clip, so you can-check later why any recording was made.--## Why the HUD exists--Two guarantees, by design:--1. **You can always tell recording is on.** The HUD is visible and always on-   top for the entire session. There is no silent or hidden desktop-   recording mode.-2. **You can always tell who asked and why.** The reason line comes from-   whoever started the recording. A recording request without a reason is-   rejected.--There is one more deliberate safeguard on the AI side: starting a desktop-recording requires the AI to explicitly confirm that it wants the whole-desktop and not just a browser tab. This prevents an AI from accidentally-capturing everything on your screen when it only meant to record one page.--## How to stop a recording--Click **Stop** in the HUD at any time. Your click is honored exactly like a-stop request from the AI: the clip is finalized and the AI is expected to-treat it as complete. Closing the recorder ends the whole session; the HUD-also dismisses itself after 5 minutes of inactivity.--One HUD session can contain several short clips. The HUD stays open between-clips so you keep seeing that a recording session is in progress.--## Where your clips are saved and how long they are kept--- Each clip is a single `.webm` video file on your machine. The AI can list-  them for you (with the reason each was recorded) or copy them wherever you-  ask.-- Adom Bridge cleans up its recordings folder automatically so it never-  fills your disk: clips are kept for about 2 days, capped at 40 files and-  3 GB total. Cleanup always removes the oldest files first, so a recording-  you just made (or one still in progress) is never touched.-- If you want to keep a clip long-term, copy it out (or ask the AI to) soon-  after recording.--## Desktop recording vs tab recording--Adom Bridge has two different recording features:--- **Desktop recording** (this page): records everything on your monitor,-  with the visible HUD and the reason line described above.-- **Tab recording**: records the contents of a single automated browser tab-  (a Puppeteer bridge feature, `pup_record_start`). It captures only-  that tab, needs no HUD (you already see the tab), and keeps recording even-  if the window is covered by other apps.--If an AI is recording a browser demo, it is usually using tab recording. If-the HUD is on your screen, the whole desktop is being recorded, and the HUD-tells you why.+Adom Bridge records your screen — a whole monitor or a single window — to an+**MP4** file, on your machine, with the system audio mixed in. It is native:+Windows Graphics Capture for the pixels and Media Foundation for the encode,+with a **hardware encoder** (NVENC / Quick Sync / AMD) doing the work and the+frames staying on the GPU end to end. No browser, no screenshot loop, no extra+capture app.++![A frame from a desktop recording made by Adom Bridge](recording/scene.png)++*Every image on this page is a real frame from a recording Adom Bridge made+itself, driving an idle test PC.*++## It can never record you silently++Whenever an AI records your screen, a **caption sits on the screen for the+whole take** ("Recording your screen and system audio (Adom Bridge)…"), and+starting a desktop recording forces the AI to confirm it means the *whole+desktop* and not just one window. The clip is a normal MP4 you keep; Adom+Bridge prunes its own recordings folder (oldest first) so it never fills your+disk, and never touches a clip that is still being written.++## The verbs++| Verb | What it does |+|---|---|+| `desktop_record_start` | Start a take. `{monitor}` (or `"primary"`) for a screen; `{hwnd}` / `{titleContains}` for one window. Optional `fps` (default 30), `codec` (`h264` default, `h265`), `bitrate` (bits/s), `audio` (default on for a monitor). |+| `desktop_record_stop` | Stop and finalise. Answers within its budget; if the encoder is still closing the file it reports `state:"finalising"` and you poll status — the take is never dropped. |+| `desktop_record_status` | Live state: `frames`, `bytes`, `droppedFrames`, `encodeFps`, `state` (recording → finalising → finalised). |+| `desktop_record_list` | Finished clips on disk. |+| `desktop_record_encoders` | Which codecs this machine can hardware-encode (see below). |++## Choosing a codec: H.264 vs H.265++Ask the machine what it has:++```+desktop_record_encoders+→ { codecs: {+      h264: { available:true, hardware:true, encoders:[{name:"NVIDIA H.264 Encoder MFT", hardware:true}, …] },+      h265: { available:true, hardware:true, encoders:[{name:"NVIDIA HEVC Encoder MFT",  hardware:true}, …] } },+    default:"h264" }+```++- **H.264** is the default and plays everywhere.+- **H.265 (HEVC)** gives you the same picture in roughly **half the file** — or a+  visibly cleaner picture at the same size. It needs a reasonably modern player.++### The same clip, both ways++Adom Bridge recorded the same 23-second, high-motion animation (2560×1440, 30 fps)+three times, changing only the codec and the target bitrate. Measured with+`ffprobe`:++| | Codec | Bitrate | File size |+|---|---|---|---|+| **A** | H.264 | 3.8 Mbps | **11.2 MB** |+| **B** | H.265 | 3.8 Mbps | **11.3 MB** |+| **C** | H.265 | 1.9 Mbps | **5.6 MB** |++**A vs B — same bitrate, so the files are the same size; compare the picture.**+At a matched bitrate H.265 spends its bits more efficiently, so edges and+gradients on fast motion hold together a little better.++| A — H.264 @ 3.8 Mbps (11 MB) | B — H.265 @ 3.8 Mbps (11 MB) |+|---|---|+| ![H.264 at 3.8 Mbps](recording/crop-h264-3_8mbps.png) | ![H.265 at 3.8 Mbps](recording/crop-h265-3_8mbps.png) |++**A vs C — the size win.** This H.265 take is at half the bitrate and is+**half the size of the H.264 file** — yet on the same scene it still holds its+detail. That is the everyday reason to pick H.265: the same recording, half the+bytes to store and move.++| A — H.264, 11 MB | C — H.265, 5.6 MB (half the size) |+|---|---|+| ![H.264 11 MB](recording/crop-h264-3_8mbps.png) | ![H.265 5.6 MB](recording/crop-h265-1_9mbps.png) |++(Honest note: at a generous bitrate H.264 and H.265 both look great — the codec+gap is widest at low bitrates and, above all, in file size. Pick H.265 when you+care about storage or upload size and your player supports it; pick H.264 for+maximum compatibility.)++## Examples++```bash+# Record the primary monitor with system audio, H.264 (default)+desktop_record_start '{"monitor":"primary","audio":true,"reason":"capturing the export walkthrough"}'+desktop_record_stop  '{}'++# Record in H.265 to halve the file size+desktop_record_start '{"monitor":"primary","codec":"h265","reason":"…"}'++# Record one window in the background (no audio), pick the bitrate+desktop_record_start '{"titleContains":"KiCad","codec":"h265","bitrate":6000000,"reason":"…"}'+```++## Under the hood++- **GPU zero-copy:** the captured frame goes WGC surface → a pooled GPU texture →+  the hardware encoder through a shared Direct3D device. No copy to system memory.+- **H.265 path:** the hardware HEVC encoder wants NV12, so Adom Bridge runs a+  Direct3D VideoProcessor to convert each frame on the GPU, and writes HEVC into+  a standard MP4 (`hvc1`) alongside an AAC audio track.+- **Timestamps track a wall clock shared with the audio**, so a long screen+audio+  recording stays in sync and finalises quickly instead of stalling.