capturekit 0.1.0__tar.gz

capturekit-0.1.0/.claude/agents/architecture-security-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: architecture-security-reviewer
+description: Architecture and security reviewer for capturekit — checks layering rules, public API typing and consistency, thread-safety, resource cleanup, native memory safety (ctypes pointers, buffer bounds, handle validation), subprocess safety, and absence of stealth/bypass behaviour. Use for reviewing significant changes or new public APIs.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You review capturekit for architecture and security. Rules come from `CLAUDE.md` and `docs/architecture.md`.
+
+Check:
+- Layering: public modules don't import backends at import time; platform specifics stay in `_backends/`.
+- Thread safety: shared state guarded; COM objects used on their owning thread; user callbacks never run on capture threads; shutdown joins threads with timeouts and cannot deadlock.
+- Native safety: argtypes/restype set, HRESULTs checked, no use-after-release, numpy views never outlive mapped memory, crop regions bounds-checked, handles validated.
+- Subprocess: list args, no shell, untrusted paths never interpreted as options (e.g. a filename starting with '-').
+- Ethics/security: recording only via explicit API calls, no persistence, no bypass of capture exclusion/DRM/OS permissions.
+- Errors are never swallowed.
+
+Read-only; do not edit or delegate. Output ranked findings with file:line, severity and a concrete fix.

capturekit-0.1.0/.claude/agents/audio-systems-specialist.md

@@ -0,0 +1,15 @@
+---
+name: audio-systems-specialist
+description: Audio systems specialist for capturekit — WASAPI (endpoint/process loopback, microphones, sessions), PulseAudio/PipeWire streams, sample formats, drift and resampling, device disconnection. Use for implementing or reviewing audio capture code and diagnosing audio glitches or isolation problems.
+tools: Read, Grep, Glob, Edit, Write, Bash, PowerShell, WebSearch, WebFetch
+model: inherit
+---
+
+You are the audio systems specialist for capturekit. Follow `.claude/skills/audio-capture-routing/SKILL.md` and `.claude/skills/av-sync/SKILL.md`.
+
+Rules:
+- Application audio capture must never silently fall back to system-wide audio. Unsupported → typed error.
+- Never change default devices, volumes, or persistent routing. Temporary routing changes require the caller's explicit opt-in.
+- Verify isolation with generated tones at distinct frequencies (e.g. 440 Hz target, 1000 Hz distractor) and spectral checks — not by listening.
+- Run tests with the project venv; report real results including skips with reasons.
+- Do not delegate to other agents. Keep final reports under 80 lines: changes, evidence, open issues.

capturekit-0.1.0/.claude/agents/linux-x11-specialist.md

@@ -0,0 +1,16 @@
+---
+name: linux-x11-specialist
+description: Linux X11/Xvfb and Linux audio (PulseAudio/PipeWire) specialist for capturekit — XShm, XRandR, XComposite/XDamage/XFixes window capture, EWMH enumeration, Xvfb test setups in WSL, Wayland detection, and per-application audio stream capture. Use for implementing/debugging/reviewing Linux backends or running Linux tests in WSL.
+tools: Read, Grep, Glob, Edit, Write, Bash, WebSearch, WebFetch
+model: inherit
+---
+
+You are the Linux/X11 specialist for capturekit. Follow `.claude/skills/linux-x11-backend/SKILL.md` and `.claude/skills/audio-capture-routing/SKILL.md`.
+
+Rules:
+- Window capture must use XComposite redirection — never root-window cropping presented as window capture. Document compositor/WM interactions you observe.
+- Always target an explicit display string; never assume $DISPLAY is the desired server.
+- Run Linux tests in WSL: `wsl -d Ubuntu -- bash -lc "..."`. Start private Xvfb servers on unused display numbers (e.g. :97-:99) with `-nolisten tcp` and kill them when done.
+- Do NOT use sudo, install packages, or modify system audio routing/configuration. If a package is missing, report the exact apt package name instead.
+- Do not delegate to other agents.
+- Report: files changed, commands run with real outputs (pass/fail/skip counts), remaining limitations. Never claim untested behaviour works.

capturekit-0.1.0/.claude/agents/performance-reviewer.md

@@ -0,0 +1,14 @@
+---
+name: performance-reviewer
+description: Independent performance reviewer for capturekit pipelines — reviews code for unnecessary copies, allocations, per-frame Python overhead, unbounded buffers, blocking calls and timing errors, and runs the benchmark scripts to measure. Use after significant changes to capture, pacing, encoding or audio paths.
+tools: Read, Grep, Glob, Bash, PowerShell
+model: inherit
+---
+
+You review capturekit for performance. Follow `.claude/skills/performance-profiling/SKILL.md`.
+
+- Read the changed code paths end to end (backend acquire → pacer → queue → encoder writer).
+- Identify: extra GPU/CPU copies, per-frame allocations of large buffers, Python loops over pixels/samples, locks held across I/O, unbounded queues/lists, sleep-based pacing without absolute deadlines.
+- Run benchmarks (`scripts/bench_capture.py`, `scripts/bench_record.py`) when hardware is available; report exact commands and measured output. Never estimate numbers and present them as measured.
+- Read-only: do not edit files. Do not delegate.
+- Output: ranked findings (impact, evidence, file:line, suggested fix), then measured results.

capturekit-0.1.0/.claude/agents/test-validation-reviewer.md

@@ -0,0 +1,14 @@
+---
+name: test-validation-reviewer
+description: Independent test and validation reviewer for capturekit — checks that tests actually verify the claimed behaviour (exclusive window capture under occlusion, process audio isolation, A/V sync), that skips are explicit, and that docs/capabilities claims match executed tests. Use before declaring a feature done.
+tools: Read, Grep, Glob, Bash, PowerShell
+model: inherit
+---
+
+You are a skeptical test reviewer for capturekit. Follow `.claude/skills/test-development/SKILL.md`.
+
+- For each capability in `docs/capabilities.md` marked Implemented, find the test(s) proving it and check the assertions are meaningful (e.g. the occlusion test also proves the occluder was really on top; the audio isolation test checks the distractor tone is absent).
+- Run the relevant tests with `-rs` and report pass/fail/skip counts with skip reasons. A skipped test is not evidence.
+- Flag: tests that cannot fail, mocked-away native behaviour presented as integration coverage, missing cleanup, timing-dependent flakiness.
+- Read-only: do not edit files. Do not delegate.
+- Output: claims → evidence status (proven / weak / unproven), then concrete missing tests.

capturekit-0.1.0/.claude/agents/windows-api-researcher.md

@@ -0,0 +1,17 @@
+---
+name: windows-api-researcher
+description: Researches and verifies Windows native APIs (DXGI, D3D11, Windows Graphics Capture/WinRT ABI, WASAPI, Application Loopback, DWM, Win32 windowing) for capturekit — signatures, vtable order, IIDs, minimum builds and undocumented behaviour — and runs small ctypes experiments to confirm. Use before implementing or changing a Windows binding, or when Windows behaviour is unclear.
+tools: Read, Grep, Glob, WebSearch, WebFetch, Bash, PowerShell, Write
+model: inherit
+---
+
+You are the Windows native API researcher for capturekit (Python, ctypes-only bindings).
+
+Follow `.claude/skills/native-api-research/SKILL.md`. Responsibilities:
+- Answer the specific question you were given with cited sources (Microsoft Learn, SDK headers, official samples). Mark anything unverified as UNVERIFIED.
+- When a fact can be tested, write a minimal experiment script in the session scratchpad (never in src/) and run it with the project venv `.venv/Scripts/python -X faulthandler`. Report the exact output.
+- For COM/WinRT interfaces give: IID, inheritance chain, full vtable slot list with indices, ctypes argtypes.
+- You may only write files under the scratchpad or `docs/research/`. Do not edit src/, tests/, or skills — report findings so the main session can apply them.
+- Never change system settings, install software, or disable security features. Do not delegate to other agents.
+
+Final report: findings (with sources), experiment commands + outputs, and recommended code-level actions. Keep it under 80 lines.

capturekit-0.1.0/.claude/skills/audio-capture-routing/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: audio-capture-routing
+description: Procedures for capturekit audio sources — WASAPI microphone, endpoint loopback and process loopback on Windows; PulseAudio/PipeWire devices, monitor sources and per-application streams on Linux; window-to-process-to-stream mapping. Use when touching audio backends or audio source selection.
+---
+
+# Audio capture and stream routing
+
+## Uniform internal format
+Every backend delivers `AudioPacket(data: float32[frames, 2], timestamp_ns,
+flags)` at 48 kHz stereo. Conversion happens in the OS where possible
+(WASAPI `AUTOCONVERTPCM | SRC_DEFAULT_QUALITY`; Pulse/PipeWire stream format).
+Never resample in Python except the tiny drift correction in `av-sync`.
+
+## Windows (WASAPI, `_backends/windows/wasapi.py`)
+| Source | Activation | Flags |
+| --- | --- | --- |
+| Microphone | `IMMDevice::Activate(IAudioClient)` on eCapture endpoint | `EVENTCALLBACK` |
+| System audio | eRender endpoint | `LOOPBACK | EVENTCALLBACK` |
+| Process audio | `ActivateAudioInterfaceAsync("VAD\\Process_Loopback", IAudioClient, VT_BLOB AUDIOCLIENT_ACTIVATION_PARAMS)` | `LOOPBACK | EVENTCALLBACK` |
+
+Quirks (verified — keep this list current):
+- Endpoint loopback delivers **no packets while nothing is playing**. The
+  aligner heartbeat must fill silence; never treat the gap as a stall.
+- Process loopback `IAudioClient::GetMixFormat` returns `E_NOTIMPL`; pass an
+  explicit WAVEFORMATEX (float32, 48 kHz, 2 ch). Requires build ≥ 20348.
+- Process loopback completion handler must implement `IAgileObject`
+  (it is called on an MTA worker thread).
+- `INCLUDE_TARGET_PROCESS_TREE` captures the target and its descendants —
+  needed for browsers whose audio comes from a child process. A PID with no
+  audio produces silence, not an error; report "no active session" via
+  `list_audio_sessions()` so callers can detect it.
+- Process loopback must never fall back to endpoint loopback on failure:
+  raise `CapabilityUnavailableError`.
+- `AUDCLNT_BUFFERFLAGS_SILENT` (0x2): treat buffer as zeros.
+  `DATA_DISCONTINUITY` (0x1): count a glitch; aligner realigns by timestamp.
+- `u64QPCPosition` is in 100 ns units of QPC → `* 100` to ns.
+- Device invalidation: `AUDCLNT_E_DEVICE_INVALIDATED (0x88890004)` → raise
+  `AudioDeviceDisconnectedError` via the error channel.
+
+- Sessions report the *rendering* PID. The venv `python.exe` launcher spawns
+  the real interpreter as a child, so a fixture's PID differs from its
+  session PID; use `_win32.process_tree(pid)` when matching (tested).
+
+Window → audio: `Window.pid` → `ProcessAudioSource(pid, include_tree=True)`.
+Ambiguity (launcher processes, shared audio hosts) is resolved by the caller
+choosing a PID from `list_audio_sessions()` (IAudioSessionManager2 sessions
+with their owning PIDs).
+
+## Linux
+See `docs/research/linux-x11-and-audio.md` for verified API details.
+- Enumerate via `pactl -f json list sinks|sources|sink-inputs` (works on
+  PulseAudio ≥ 16 and pipewire-pulse) — fallback to text parsing.
+- System audio: record the default sink's `.monitor` source.
+- App audio: per sink-input capture (`parec --monitor-stream=<idx>`); multiple
+  sink-inputs from one PID → one capture per stream, mixed by `AudioMixer`.
+  New streams appearing mid-recording are polled and attached.
+- Never move user streams or change default devices without explicit opt-in.
+- Xvfb has no audio; audio availability is independent of the X display.
+
+## Tests
+`pytest -m audio`. Process-loopback test plays a generated tone from a child
+process (`tests/fixtures/tone_player.py`) and asserts tone energy at the
+expected frequency in the captured track and absence of a second tone played
+by another process.

capturekit-0.1.0/.claude/skills/av-sync/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: av-sync
+description: Audio/video synchronization design and verification for capturekit — shared clock, pause-aware timeline, CFR frame pacing, audio gap filling, overlap trimming, drift correction and how to measure A/V offset in recorded files. Use when changing _pipeline/ timing code or investigating sync drift.
+---
+
+# Audio/video synchronisation
+
+Code: `src/capturekit/_pipeline/` — `clock.py`, `timeline.py`, `pacer.py`,
+`aligner.py`, `mixer.py`.
+
+## Model
+- One clock (`now_ns`). Every frame/packet timestamp is converted to it at the
+  backend boundary.
+- `Timeline.media_ns(wall_ns)` maps wall time to media time, excluding paused
+  intervals; returns `None` while paused.
+- Video: slot `n` covers media time `[n*P, (n+1)*P)`; pacer fires at
+  `wall(t0) + n*P` (absolute). FFmpeg rawvideo timestamps = slot index.
+- Audio: sample `k` ↔ media time `k / 48000`. Aligner computes expected
+  position `p = media_ns(packet.ts) * 48000 / 1e9`, compares with samples
+  written `w`:
+  - `p - w > gap_threshold (20 ms)` → insert silence `p - w`.
+  - `w - p > overlap_threshold (20 ms)` → trim overlap from packet head.
+  - otherwise → drift correction: resample packet to `n + c` samples where
+    `c = clamp(k_p * (p - w), ±0.5% n)` (proportional controller).
+- Heartbeat: if no packet for > 100 ms, fill silence up to
+  `media_now - 60 ms` (loopback silence, device stall).
+
+## Invariants to test
+1. Total audio samples ≈ total video slots × 48000 / fps (± one packet).
+2. Pause of D seconds adds 0 to both durations.
+3. A clock running 100 ppm fast for 1 h stays within ±20 ms
+   (`tests/unit/test_aligner.py` simulates).
+
+## Measuring sync in a real file
+1. Record a flash+beep fixture (`tests/fixtures/av_sync_beacon.py`: window
+   flips black→white and plays a 1 kHz beep at the same QPC instant).
+2. Extract: `ffprobe -show_frames` for video luminance (or decode with FFmpeg to
+   rawvideo gray and find the step), audio onset by envelope threshold.
+3. Offset = audio_onset − video_onset; report mean and drift over time.
+Acceptable: |offset| ≤ 1 frame period + 10 ms, drift ≤ 5 ms/min.

capturekit-0.1.0/.claude/skills/bug-investigation/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: bug-investigation
+description: Root-cause analysis procedure for capturekit bugs — crashes in ctypes/COM code, hangs/deadlocks in pipelines, black or stale frames, A/V desync, encoder failures and resource leaks. Use when something fails and the cause is not immediately obvious.
+---
+
+# Bug investigation and root-cause analysis
+
+## Procedure
+1. **Reproduce** minimally (script in scratchpad or a failing test). Record
+   exact command, environment (OS build, GPU, FFmpeg version).
+2. **Classify** and follow the matching playbook below.
+3. **Hypothesise → test one variable at a time.** Write down what each
+   experiment rules out.
+4. **Fix the cause, not the symptom** (no retries/sleeps to hide races).
+5. **Regression test** that fails before and passes after.
+6. **Capture the lesson** in the owning skill's quirks section.
+
+## Playbooks
+### Interpreter crash (access violation, no traceback)
+- Run `python -X faulthandler`; the native stack points at the call.
+- Check: vtable index, `argtypes` (pointer vs value struct, 64-bit handles
+  as `c_void_p` not `c_int`), lifetime (released COM object, numpy view of
+  unmapped memory, ctypes callback garbage-collected while native code still
+  holds it — keep a strong reference on the owning object).
+
+### Hang / deadlock
+- `faulthandler.dump_traceback_later(30)` or `py-spy dump --pid`.
+- Typical: FFmpeg waiting on an unconnected pipe; writer blocked on full pipe
+  while FFmpeg blocks on stderr (must be drained); queue `put()` without
+  timeout during shutdown; joining a thread from itself.
+
+### Black / stale frames
+- WGC: protected window (display affinity), minimized window, wrong HWND
+  (host vs content window), DRM. DXGI: wrong adapter, ACCESS_LOST not handled,
+  frame with `LastPresentTime == 0` (pointer-only update — no new image).
+
+### Desync
+- Compare video slot count vs audio sample count in `stats`; check
+  `audio_silence_inserted_ms` / `trimmed_ms`; see av-sync skill.
+
+### Leaks
+- Run the capture open/close loop test (`tests/windows/test_lifecycle.py`)
+  watching handle count (`psutil.Process().num_handles()`) and GPU memory.

capturekit-0.1.0/.claude/skills/docs-release/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: docs-release
+description: Documentation conventions and release preparation for capturekit — which docs to update for which change, capability-matrix honesty rules, changelog, versioning, packaging checks (build, twine check, wheel contents). Use when updating docs or preparing a release. Publishing requires explicit user approval.
+---
+
+# Documentation and release preparation
+
+## Doc map
+| File | Update when |
+| --- | --- |
+| `README.md` | install / quickstart / feature summary changes |
+| `docs/capabilities.md` | any feature status change (implemented / experimental / untested / unsupported) |
+| `docs/architecture.md` | design changes |
+| `docs/decisions.md` | new decision or dependency |
+| `docs/guide/*.md` | user-facing API or platform setup changes |
+| `docs/PROGRESS.md` | every working session |
+| `CHANGELOG.md` | every user-visible change (Keep a Changelog format) |
+
+## Capability honesty rules
+- **Implemented**: real backend + tests executed on that platform.
+- **Experimental**: works in manual/limited tests; known gaps listed.
+- **Untested**: code exists but not executed on that platform/config.
+- **Unsupported**: not implemented or out of scope (raises a typed error).
+A stub or interface alone is never "implemented".
+
+## Examples
+Every code example in docs must be runnable; keep them in `examples/` and
+reference them from docs. Run `python examples/<x>.py --help` (or a smoke
+mode) before release.
+
+## Release checklist (do NOT publish without user approval)
+1. `ruff check . && ruff format --check . && mypy src`
+2. Full test run on Windows + Xvfb (WSL); paste the summary (passed/skipped/
+   failed counts and skip reasons) into `docs/PROGRESS.md`.
+3. Bump `src/capturekit/_version.py`; update CHANGELOG.
+4. `python -m build` → `twine check dist/*`; inspect wheel contents
+   (`python -m zipfile -l dist/*.whl`) — no tests, no scratch files.
+5. Install wheel in a fresh venv, run `examples/list_sources.py`.
+6. Ask the user before `twine upload` / tagging.

capturekit-0.1.0/.claude/skills/ffmpeg-encoding/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ffmpeg-encoding
+description: FFmpeg discovery, hardware encoder probing (NVENC/QSV/AMF/x264/MediaFoundation), command construction, named-pipe audio inputs, process lifecycle and failure handling for capturekit recordings. Use when editing src/capturekit/encoding/ or diagnosing encoder failures.
+---
+
+# FFmpeg and hardware encoding
+
+Code: `src/capturekit/encoding/ffmpeg.py` (discovery, probe, command builder,
+`FFmpegProcess`), `encoding/pipes.py` (named pipes / FIFOs).
+
+## Discovery order
+explicit `EncoderConfig.ffmpeg_path` → `$CAPTUREKIT_FFMPEG` → `PATH` →
+`imageio_ffmpeg.get_ffmpeg_exe()` (optional dep). Record version via
+`ffmpeg -version`.
+
+## Encoder validation (never trust `-encoders` alone)
+```
+ffmpeg -hide_banner -loglevel error -f lavfi -i color=c=black:s=256x256:r=30
+       -frames:v 3 -c:v <encoder> -f null -
+```
+Exit 0 → usable. Cache per (ffmpeg path, mtime). Measured 2026-10-11 on RTX
+4050 laptop: `h264_nvenc` OK; `h264_qsv`, `h264_amf` listed but fail.
+NVENC minimum size is ~145x49 on some generations — probe at 256x256 and
+reject smaller recordings for NVENC (fall back to libx264).
+
+## Command shape
+```
+ffmpeg -hide_banner -nostdin -loglevel warning -stats_period 1 -progress pipe:2?
+  -f rawvideo -pix_fmt bgra -video_size WxH -framerate FPS -i pipe:0
+  [-f f32le -ar 48000 -ac 2 -i \\.\pipe\capturekit-<uuid>-a0]...
+  -map 0:v [-map 1:a ...] -c:v <enc> <enc opts> -c:a aac -b:a 192k
+  -metadata:s:a:i title=<track name> <out.mkv>
+```
+- Hardware encoders take BGRA directly (GPU colour conversion). libx264 needs
+  `-pix_fmt yuv420p` output (swscale on CPU — measure cost).
+- Always `-pix_fmt yuv420p` (or nv12 for hw) on output for player compatibility.
+- Rate control: NVENC `-rc vbr -b:v B -maxrate 1.5B -bufsize 2B -preset p4`;
+  x264 `-preset veryfast -b:v B -maxrate -bufsize`; or CQP/CRF when bitrate=None.
+- MKV is the default (survives crashes). MP4 gets `-movflags +faststart`? No:
+  faststart rewrites the whole file at the end — omit by default for long
+  recordings; offer fragmented MP4 (`+frag_keyframe+empty_moov`) as option.
+
+## Process handling
+- `subprocess.Popen(list_args, stdin=PIPE, stderr=PIPE, stdout=DEVNULL,
+  creationflags=CREATE_NO_WINDOW)` — never `shell=True`.
+- Drain stderr on a thread into a bounded deque (last 200 lines).
+- Shutdown: close stdin and audio pipes → wait(timeout) → on timeout send
+  `q`? (stdin closed so no) → `terminate()` → `kill()`. Report exit code and
+  stderr tail in `EncoderError`.
+- `BrokenPipeError` on write = FFmpeg died: collect stderr, raise EncoderError.
+
+## Named pipes (Windows)
+`CreateNamedPipeW(r"\\.\pipe\capturekit-<uuid4>", PIPE_ACCESS_OUTBOUND,
+PIPE_TYPE_BYTE|PIPE_WAIT, 1, 1 MiB, 1 MiB, 0, NULL)` → start FFmpeg →
+`ConnectNamedPipe` in the writer thread (blocks until FFmpeg opens it). FFmpeg
+opens inputs in order, so every writer thread must be running before FFmpeg
+starts probing. Linux: `os.mkfifo` in a private temp dir (mode 0600).
+
+## Troubleshooting
+| Symptom | Cause |
+| --- | --- |
+| hangs at start | an input pipe never connected/written; check writer threads started |
+| `Invalid argument` with nvenc | odd width/height → we round crop to even dimensions |
+| A/V offset constant | wrong timeline start for audio; see av-sync skill |
+| file unplayable after crash | MP4 without fragmentation; use MKV |

capturekit-0.1.0/.claude/skills/linux-x11-backend/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: linux-x11-backend
+description: How to develop and test capturekit's Linux X11/Xvfb video backend — explicit display selection, XRandR monitor discovery with fallbacks, XShm capture, XComposite exclusive window capture, EWMH enumeration, X error handling, Wayland/XWayland detection, and running tests against private Xvfb servers in WSL. Use when editing src/capturekit/_backends/linux/.
+---
+
+# Linux X11 / Xvfb backend
+
+Reference (sources + API sequences): `docs/research/linux-x11-and-audio.md`.
+
+## Display selection rules
+- Every public call accepts `display: str | None`. `None` → `$DISPLAY`, but
+  only after Wayland checks; an explicit string (`":99"`) bypasses the host
+  session check and targets that server directly.
+- Wayland-only (`WAYLAND_DISPLAY` set, no usable X server requested) →
+  `UnsupportedDisplayServerError`. If the default `$DISPLAY` is XWayland
+  (server has the `XWAYLAND` extension) → also unsupported for desktop
+  capture; say so in the message. WSLg sets `WAYLAND_DISPLAY=wayland-0` and
+  `DISPLAY=:0` (XWayland) — tests must always pass explicit Xvfb displays.
+
+## Monitors
+RRGetMonitors (RandR ≥ 1.5) → CRTC enumeration (RandR ≥ 1.2) → Xinerama →
+root window geometry. Xvfb exposes one CRTC/output named "screen"; with no
+CRTCs GetMonitors returns empty — fall back, never crash.
+
+## Capture
+- Monitor/region: `XShmGetImage` on the root window when MIT-SHM is present
+  (local connections only), else `XGetImage`. Mark the SHM segment
+  `IPC_RMID` immediately after attach; set `image.data = NULL` before
+  `XDestroyImage`.
+- Window: `XCompositeRedirectWindow(dpy, w, CompositeRedirectAutomatic)`
+  (never Manual — a compositor may own it), then `XCompositeNameWindowPixmap`
+  → capture from the pixmap. Re-name the pixmap after every ConfigureNotify
+  (resize) and MapNotify. Use the top-level *frame* or the client window per
+  `client_area_only`.
+- Unmapped/iconified windows: pixmap is not available (BadMatch). Report
+  `TargetUnavailable`-style state; never substitute desktop pixels.
+- FFmpeg x11grab `-window_id` is NOT exclusive capture (plain GetImage on the
+  window; obscured areas undefined). Do not use it as a window backend.
+
+## Verified quirks (Xvfb 21.x / libX11 1.8.13, Ubuntu 26.04, 2026-10-11)
+- `XShmGetImage`/`XGetImage` on a **pixmap** return an XImage with zero
+  colour masks (the reply has no visual for pixmaps). Validate the pixel
+  layout from the `Visual` struct at grabber creation, never from the image.
+- Xvfb (stock Ubuntu build) offers Composite, DAMAGE, MIT-SHM, RANDR (one
+  monitor named `screen`), X-Resource (PIDs work), XFIXES, XINERAMA.
+- WSLg PulseAudio 17 (`PULSE_SERVER=unix:/mnt/wslg/PulseServer`) supports
+  `pactl -f json`; its sink is `RDPSink` (audible on the Windows host).
+
+## Xlib safety
+- Install `XSetErrorHandler` (default handler calls `exit()`); handler is
+  process-global — record errors per-display, check after `XSync`.
+- One `Display*` per capture thread; libX11 ≥ 1.8 auto-calls `XInitThreads`.
+- 32-bit format properties come back as C `long` (8 bytes on x86-64).
+
+## Enumeration
+`_NET_CLIENT_LIST` (EWMH) → title `_NET_WM_NAME` (UTF8_STRING) / `WM_NAME`,
+pid `_NET_WM_PID` or XRes `XResQueryClientIds`, `WM_CLASS`. No WM (bare
+Xvfb): `XQueryTree(root)` children that are mapped InputOutput windows.
+
+## Testing in WSL
+Packages needed (ask user before installing):
+`xvfb x11-utils x11-apps ffmpeg pulseaudio-utils libpulse0`.
+```
+wsl -d Ubuntu -- bash -lc "Xvfb :99 -screen 0 1280x720x24 -nolisten tcp & sleep 1; cd '/mnt/d/User/Documents/Projects/Python Projects/Cross-Platform Python Screen and Audio Capture Library' && python3 -m pytest -m xvfb -rs; kill %1"
+```
+Tests start their own Xvfb via the `xvfb_display` fixture on a free display
+number; never reuse :0 in WSL.

capturekit-0.1.0/.claude/skills/native-api-research/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: native-api-research
+description: Procedure for researching and verifying Windows/X11/PipeWire native API behaviour (signatures, vtable order, GUIDs, minimum OS builds, undocumented behaviour) before implementing it in capturekit. Use before writing any new ctypes binding or relying on a platform behaviour.
+---
+
+# Native API research and verification
+
+Goal: every native fact the code relies on is either (a) cited from an
+authoritative source or (b) verified by an experiment on this machine — and
+recorded so nobody re-derives it.
+
+## Source priority
+1. Microsoft Learn API reference (`learn.microsoft.com/windows/win32/api/...`,
+   `learn.microsoft.com/uwp/api/...`) — signatures, minimum builds, contracts.
+2. Windows SDK headers (vtable order is the declaration order in the header,
+   including inherited interfaces). Mirror: `github.com/tpn/winsdk-10`, or
+   the `windows-rs`/`win32metadata` repos.
+3. Official samples: `microsoft/Windows-classic-samples`
+   (ApplicationLoopback), `robmikh/Win32CaptureSample` (WGC, by the WGC
+   owner), `microsoft/Windows-universal-samples` (ScreenCaptureforHWND).
+4. X.org protocol specs (`gitlab.freedesktop.org/xorg/proto/xorgproto`),
+   libX11/libXcomposite man pages, PipeWire/PulseAudio docs.
+5. OBS Studio sources (libobs-winrt, win-capture, linux-capture) — reference
+   for real-world quirks, not authority.
+
+Blog posts / StackOverflow are leads only. Mark unverified claims
+`UNVERIFIED` in docs until tested.
+
+## Procedure for a new COM / WinRT binding
+1. Find the interface IID and full inheritance chain in the header.
+2. Count vtable slots: IUnknown = 0..2; IInspectable adds 3..5; then the
+   interface's own methods in declaration order (WinRT property getters
+   `get_X`, setters `put_X`, events `add_X`/`remove_X` each take a slot).
+3. Write the binding in `_backends/windows/` using `ComPtr.call(index,
+   restype, argtypes, *args)` and add the index to
+   `windows-capture-backend/reference/vtables.md`.
+4. Experiment: minimal script in the scratchpad that calls the method and
+   checks HRESULT == 0 and plausible output. Never trust an index untested —
+   a wrong index usually returns garbage or crashes the interpreter.
+5. Parameterised WinRT interfaces (e.g. `TypedEventHandler<A,B>`): compute
+   the IID with `capturekit._backends.windows._winrt.pinterface_iid`
+   (UUIDv5 of the signature string, namespace
+   `11f47ad5-7b73-42c0-abae-878b1e16adee`) and cross-check with a known value.
+
+## Procedure for an OS-version-dependent feature
+1. Record the minimum build from Learn's Requirements table.
+2. Implement runtime detection by *trying* the API (QI for the interface,
+   `ApiInformation`-style checks) — build numbers are a hint only.
+3. Expose the result in `get_capabilities()` with a human-readable reason.
+
+## Recording findings
+- Verified facts and quirks → the relevant backend skill's reference file.
+- Design-affecting facts → `docs/decisions.md`.
+- Unknown/unverifiable behaviour → `docs/capabilities.md` "untested" column.
+
+## Verified facts log (append; include date + build)
+- 2026-10-11, Win11 26200: `time.perf_counter_ns()` == QPC ns (delta ~1 µs);
+  QPC frequency 10 MHz.
+- `AUDIOCLIENT_PROCESS_LOOPBACK_PARAMS` min client: Windows 10 build 20348
+  (Learn). Mode 0 = include target process tree, 1 = exclude.
+- `GraphicsCaptureSession` 1803; `IsCursorCaptureEnabled` 2004 (19041);
+  `CreateForWindow` interop 1903. `IsBorderRequired`: 20348/Win11.
+- Microsoft does not document WGC behaviour for minimized windows → measured
+  2026-10-11: no frames while minimized, resume on restore
+  (`tests/windows/test_video.py::test_window_minimized_behaviour`).
+- Guessing IIDs from memory failed once (IDXGIOutput1). Always copy IIDs from
+  headers (MinGW-w64 `mingw-w64-headers/include/*.idl` is fetchable as raw text).

capturekit-0.1.0/.claude/skills/performance-profiling/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: performance-profiling
+description: How to measure and optimise capturekit capture/encode throughput — benchmark scripts, per-stage timing, py-spy/cProfile usage, known hot spots (GPU readback, memcpy, pipe bandwidth, swscale), and rules for reporting numbers honestly. Use when evaluating FPS targets (24/30/60+) or optimising a pipeline stage.
+---
+
+# Performance profiling and optimisation
+
+## Rules
+- Numbers in docs must include: command, git commit, machine (CPU/GPU),
+  resolution, fps, encoder, date. Never estimate and present as measured.
+- Measure first with `scripts/bench_capture.py` and the `Recorder.stats`
+  counters before changing code. Optimise the dominant stage only.
+
+## Commands
+```
+.venv/Scripts/python scripts/bench_capture.py --source monitor --fps 60 --seconds 10
+.venv/Scripts/python scripts/bench_capture.py --source window --hwnd <id> --fps 60
+.venv/Scripts/python scripts/bench_record.py --fps 60 --encoder auto --seconds 20
+python -X importtime -c "import capturekit"
+py-spy record -o profile.svg -- python scripts/bench_record.py ...   (if installed)
+```
+`stats` fields to watch: `capture_ms_p50/p99` (acquire+copy), `pacer_jitter_ms`,
+`frames_late`, `frames_dropped`, `queue_depth_max`, `encoder_write_ms`.
+
+## Known cost centres (1080p BGRA = 8.3 MB/frame)
+| Stage | Notes |
+| --- | --- |
+| GPU→staging copy + Map | Map stalls until copy done; staging ring of 2–3 textures hides latency |
+| numpy row copy | ~1–2 ms/frame; unavoidable single copy |
+| pipe to FFmpeg | 60 fps × 8.3 MB ≈ 500 MB/s; use large writes (whole frame) |
+| colour conversion | hw encoders take BGRA (GPU CSC); libx264 needs swscale (CPU) |
+| Python per-frame overhead | keep per-frame Python ops O(1), no per-pixel loops |
+
+## Optimisation backlog (evaluate with measurements before doing)
+1. Staging texture ring to avoid Map stalls.
+2. GPU BGRA→NV12 via D3D11 VideoProcessor (halves pipe bandwidth).
+3. Shared-memory transport instead of pipe.
+4. Skip readback entirely when the frame is unchanged (duplicate slot).

capturekit-0.1.0/.claude/skills/test-development/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: test-development
+description: How to write, organise, run and interpret capturekit tests — unit vs platform integration vs performance tests, pytest markers and skip rules, deterministic fixture windows and tone players, pixel verification for exclusive window capture, and regression triage. Use when adding tests or analysing test failures.
+---
+
+# Test development and regression analysis
+
+## Layout
+```
+tests/unit/            pure Python, run everywhere (timeline, aligner, config,
+                       ffmpeg command builder, region validation)
+tests/windows/         marker windows (+gpu/audio/ffmpeg as needed)
+tests/linux/           markers x11 / xvfb
+tests/perf/            marker slow; prints measured numbers, asserts loose floors
+tests/fixtures/        helper programs run as subprocesses
+```
+
+## Markers (pyproject `[tool.pytest.ini_options]`)
+`windows, x11, xvfb, gpu, audio, ffmpeg, slow, interactive`.
+`conftest.py` auto-skips when requirements are missing **with a reason**.
+Report skipped counts explicitly: a skip is not a pass.
+
+## Commands
+```
+.venv/Scripts/python -m pytest                       # all available
+.venv/Scripts/python -m pytest tests/unit -q         # fast
+.venv/Scripts/python -m pytest -m "windows and not slow" -rs
+.venv/Scripts/python -m pytest -m slow -s            # perf, shows numbers
+wsl -d Ubuntu -- bash -lc 'cd /mnt/d/... && python3 -m pytest -m xvfb -rs'
+```
+Always use `-rs` when reporting so skip reasons are visible.
+
+## Exclusive-window-capture verification pattern
+1. Spawn `tests/fixtures/color_window.py --color 0,200,0 --title <uuid>` (target).
+2. Spawn an occluder window (`--color 200,0,0 --topmost`) overlapping it.
+3. Find target by title, capture via `WindowCapture`.
+4. Assert ≥ 99% of client-area pixels equal the target colour (±2 per channel)
+   and 0% match the occluder colour.
+5. Also verify a *desktop* capture of the same area does show the occluder —
+   proves the test is meaningful (the occluder really covers the target).
+
+## Regression analysis procedure
+1. Re-run the failing test alone with `-x -vv -s`.
+2. Determine flakiness: `pytest --count`-style loop (`for i in 1..10`).
+3. Bisect with `git bisect run python -m pytest <test>` when history exists.
+4. Write the regression test first, then fix (bug-investigation skill).
+5. Record root cause in `docs/PROGRESS.md` test log if non-obvious.