kwcapture 0.1.0__tar.gz

kwcapture-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libsystemd-dev libwayland-dev pkg-config
+
+      - name: Build the wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+
+      - name: Install it
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          python -c "import kwcapture; print('version', kwcapture.__version__)"
+          kwcapture --version
+          kwcapture screens || echo "(no Wayland session in CI, as expected)"
+
+      - name: Check the bundled helper
+        run: |
+          python - <<'PY'
+          from kwcapture import _native
+          p = _native.prebuilt_path()
+          print("wheel ships the helper:", p, p.is_file())
+          assert p.is_file(), "the wheel should contain the compiled helper"
+          PY

kwcapture-0.1.0/AGENTS.md

@@ -0,0 +1,170 @@
+# AGENTS.md — fast screen capture on Wayland (KDE Plasma 6 / KWin)
+
+Repo: **https://github.com/tjandrasg/kwcapture** (branch `main`, release `v0.1.0` with a
+prebuilt `linux_x86_64` wheel attached) and on PyPI as **`kwcapture`**
+(https://pypi.org/project/kwcapture/) — publish new versions with
+`.venv/bin/python -m twine upload -r pypi dist/*` (credentials in `~/.pypirc`; never
+commit or print them). Author: Tjandra Satria Gunawan <tjandra.satria@sci.ui.ac.id>.
+`origin` is SSH (`git@github.com:tjandrasg/kwcapture.git`). There is no `gh` CLI here, so
+repo/release admin (creating releases, uploading assets, topics) is done with the GitHub
+REST API via `curl` using whatever credential is configured for github.com — never commit
+or print a token.
+
+Working dir: `~/way_scr_cap`. **Read this first if you are a fresh session.**
+Status: **done and working** — ~40 fps real Wayland capture, Python API + CLI + tests.
+See `README.md` for user-facing docs; this file is the investigation log + gotchas.
+
+## Goal
+Make a **fast** full-screen capture program on Wayland. Original experiments
+(`probe/bench_original.py`, `bench_result.md`): `PIL.ImageGrab` shells out to `spectacle`
+(~2 fps); `mss` is 1100 fps but captures **XWayland** (black for native Wayland windows)
+and dies when `$DISPLAY` is unset. Both unusable.
+
+## What we ship (pip-installable package, v0.1.0)
+`make setup` (or just `pip install .`) then `.venv/bin/python tests/test_kwcapture.py`.
+
+| file | what |
+|---|---|
+| `kwcapture/native/kwcapture.c` | native helper: one-shot / `--bench` / `--list` / `serve` (daemon + shm ring), sd-bus + wayland-client |
+| `kwcapture/native/include/kwcapture_shm.h` | shm ring protocol (`KWC_HDR_STRUCT_SIZE` = 1776, `_Static_assert`ed) |
+| `kwcapture/__init__.py` | Python API: `Capture`, `grab/latest/shot/shot_jpeg/stats/bench`, ctypes mirror of the header, `to_rgb`/`resize`/`png_bytes`/`jpeg_bytes` |
+| `kwcapture/_native.py` | helper discovery: `$KWCAPTURE_BIN` → `kwcapture/bin/kwcapture` (wheel) → `~/.cache/kwcapture/…` → compile from the shipped source; ELF-arch check |
+| `kwcapture/_desktop.py` | writes/refreshes/prunes the KWin authorisation desktop entry |
+| `kwcapture/__main__.py` | CLI: `doctor [--fix --build] / setup / install-desktop [--uninstall] / screens / grab / demo / bench` (console script `kwcapture`) |
+| `pyproject.toml` + `setup.py` | packaging; `setup.py` compiles the helper during the wheel build (`build_py` → non-pure, `bdist_wheel.get_tag` → `linux_<arch>`), failure is non-fatal (runtime compile) |
+| `tests/test_kwcapture.py` | 27 functional tests, also `pytest tests/` |
+| `bench.py` | comparison table vs `mss` and `PIL.ImageGrab` |
+| `Makefile` | `make` `install-desktop` `setup` `doctor` `test` `bench` `demo` `wheel` `sdist` `dev-install` `clean` |
+| `probe/` | experiments: `globals.c` (dump compositor globals), Gio prototypes, scale/post micro-benchmarks |
+| `AGENTS.md`, `README.md`, `CHANGELOG.md`, `LICENSE` (MIT), `.github/workflows/ci.yml` | docs/CI |
+
+Install story: **self-configuring** — first `Capture()` finds/builds the helper, writes the
+desktop entry, retries while KDE's service cache notices it. Verified in a *fresh* venv
+(`pip install dist/*.whl`, numpy only, no desktop entry present): ready in ~150 ms, 37.9 fps,
+numpy-only fallback resize worked. Also verified installing straight from GitHub and from
+the release wheel URL. Published on PyPI: `pip install kwcapture`.
+
+## Results (2560x1440@164.69Hz, Plasma 6.6 / kwin 6.6.6, i9-13900K)
+```
+mss (XWayland)              1113.8 fps   0.9 ms   <-- BLACK/EMPTY, useless
+PIL.ImageGrab (spectacle)      2.7 fps 357.1 ms
+kwcapture raw BGRA view       38.4 fps  25.8 ms
+kwcapture RGB full res        37.9 fps  26.0 ms
+kwcapture RGB 1280 wide       38.0 fps  26.1 ms
+kwcapture JPEG 1280           35.6 fps  28.0 ms   (grab + downscale + encode)
+kwcapture latest()          551704   fps   0.0 ms   (view of already-published frame)
+```
+Breakdown at 1440p: KWin grab ≈ 18-25 ms (≈11 ms floor even for a 320x180 area), pipe drain
+≈5 ms (14 MB). Throughput ceiling ≈47 fps (KWin serialises screenshot jobs); `depth=2`
+reaches it, depth 3/4 only add latency (grab_ms 37/58/80 ms). Post-processing: cv2
+`INTER_AREA` 2560→1280 = 0.1 ms, `cvtColor` BGRA2RGB of the small frame ≈3 ms, cv2 JPEG
+1280 = 3.5 ms / 2560 = 4.5 ms, PNG 23 ms (avoid), PIL resize 17 ms (avoid → use cv2).
+Colour fidelity verified vs an independent Spectacle capture: MAD **0.0** (9.7 if R/B swapped).
+
+## THE TWO KEY FINDINGS
+
+### 1. KWin's D-Bus API `org.kde.KWin.ScreenShot2`
+service `org.kde.KWin.ScreenShot2`, path `/org/kde/KWin/ScreenShot2`, same interface, owned
+by `kwin_wayland`. Methods (all `(…, options a{sv}, pipe h) -> results a{sv}`):
+`CaptureScreen(name s)`, `CaptureActiveScreen`, `CaptureArea(x i,y i,width u,height u)`,
+`CaptureWorkspace`, `CaptureWindow(handle s)`, `CaptureActiveWindow`, `CaptureInteractive(kind u)`.
+* results: `type="raw"`, `format` (QImage::Format; **6 = ARGB32_Premultiplied = BGRA bytes**),
+  `width`, `height`, `stride` (bytes/line), `scale` (double), `screen` (e.g. `DP-1`).
+* options: `include-decoration` (def false), `include-shadow` (kwin default **true**),
+  `include-cursor` (def false), `native-resolution`, `hide-caller-windows` (def **true** —
+  hides the capture tool's own windows, which we want).
+* **KWin replies BEFORE the pixels are written**: `ScreenShotSinkPipe2::flush()` sends the
+  method return, then hands the fd to `ScreenShotWriter2` (QThreadPool) which sets
+  O_NONBLOCK and `poll(POLLOUT, 60s)`. So EOF on our pipe = frame boundary; read the reply
+  first for the geometry, then drain. (A memfd also works but you must poll for the size.)
+* errors: `org.kde.KWin.ScreenShot2.Error.{NoAuthorized,Cancelled,InvalidWindow,
+  NoActiveWindow,InvalidArea,InvalidScreen,FileDescriptor}`.
+* Source for reference (branch Plasma/6.6): `src/plugins/screenshot/screenshotdbusinterface2.cpp`
+  (`/tmp/sdbus2.cpp` held a copy), `src/utils/serviceutils.h`.
+
+### 2. Authorisation (the thing that blocked us first)
+`checkPermissions()` → `KWin::fetchRestrictedDBusInterfacesFromPid(pid)`:
+caller pid (from `GetConnectionUnixProcessID`) → canonical `/proc/<pid>/exe` →
+`KApplicationTrader` finds a **.desktop file whose `Exec=` first token canonicalises to that
+exe** → allowed only if `X-KDE-DBUS-Restricted-Interfaces` contains
+`org.kde.KWin.ScreenShot2`. Spectacle does exactly this.
+⇒ **A Python script can never be authorised**; a native binary + desktop file can.
+Installed by `make install-desktop`:
+`~/.local/share/applications/io.github.kwcapture.desktop` with
+`Exec=<abs path>/bin/kwcapture` + `X-KDE-DBUS-Restricted-Interfaces=org.kde.KWin.ScreenShot2`
+(+ `kbuildsycoca6`). **Re-run it after moving/rebuilding the binary.**
+Alternative (NOT used): start the session with `KWIN_SCREENSHOT_NO_PERMISSION_CHECKS=1` in
+*kwin's* environment — disables the check for everyone in the session.
+
+## Environment facts
+Ubuntu, Plasma **6.6**, kwin 6.6.6 (`kwin_wayland` + `kwin_wayland_wrapper`), Wayland session,
+single output `DP-1` 2560x1440@164.69Hz scale 1. `$XDG_RUNTIME_DIR=/run/user/1000` (tmpfs 13G).
+`grim` absent; `xdg-desktop-portal` main daemon NOT running (portal/PipeWire route avoided).
+KWin does **not** advertise `ext_image_copy_capture_manager_v1` (checked by dumping the
+Wayland registry — `probe/globals.c`, compiled `probe/globals`); its XML on disk comes from
+wlroots deps only. No `wlr-screencopy` (KWin is not wlroots). XWayland root window is black.
+Toolchain: gcc, `pkg-config libsystemd` (sd-bus 259), `wayland-client`, `wayland-scanner`.
+venv `~/way_scr_cap/.venv` (Python 3.14.4): numpy, pillow, mss, wxPython, dbus-fast, dasbus,
+opencv-python-headless; plus `.pth` → `/usr/lib/python3/dist-packages` so `import gi`
+(PyGObject 3.56 + Gst typelibs) also works inside the venv.
+
+## Gotchas (each cost real time — respect them)
+* **D-Bus fd passing**: `busctl`/`dbus-send` can't pass fds. Works with sd-bus
+  (`sd_bus_message_append(m,"h",fd)`), `dbus-fast` (`Message(..., unix_fds=[fd])`), or Gio
+  (`call_with_unix_fd_list`, **async-only**, arg order
+  `bus_name, path, iface, method, params, reply_type, flags, timeout, fd_list, cancellable,
+  callback`; `a{sv}` values must each be a `GLib.Variant`).
+* sd-bus: pkg-config name is **libsystemd**, include `<systemd/sd-bus.h>`, and the public
+  header has **no `_cleanup_`** macro — call `sd_bus_error_free()` manually.
+* `__atomic_store_n()` does **not** accept `double`; plain-assign it and rely on the release
+  store of the sequence counter to order it.
+* **shm request flag needs a wake-up**: the first `serve` implementation polled with a
+  250 ms timeout, so on-demand grabs took 273 ms. Fix = a FIFO `<shm>.req` opened O_RDWR by
+  the daemon (never EOF, never blocks) and O_WRONLY|O_NONBLOCK by the client; write 1 byte
+  per request.
+* Pipes handed to KWin must be **O_NONBLOCK on our read end** in the daemon (else one
+  in-flight drain stalls the whole loop and can deadlock at depth>1); handle EOF-before-size
+  (set `hdr->error=EIO`, mark done) so the ring cannot wedge.
+* Ring geometry: `KWC_HDR_STRUCT_SIZE` is asserted in **both** C (`_Static_assert`) and
+  Python (`assert ctypes.sizeof(_Hdr)`). Bump both if you edit the struct.
+* Keep the ring slot ≥ 5K frames (`5120*2880*4`) so a resolution change doesn't overflow;
+  the file is sparse (226 MB apparent → 15 MB resident at 1440p).
+* `np.frombuffer(mmap)` gives a read-only array; `setflags(write=copy)` in `_view()`.
+  `mmap.close()` raises `BufferError` while ctypes/numpy hold views (caught in `close()`).
+* Pillow: no `BGRA` mode — use `Image.frombuffer("RGBA", size, buf, "raw", "BGRA", 0, 1)`.
+  `Image.fromarray(a, "BGRA")` does not work.
+* `wl_output.geometry` width/height are **millimetres**; pixel size/refresh come from
+  `wl_output.mode`. Connector name (`DP-1`) is the `wl_output.name` event → needs binding v4.
+* `pkill -f kwcapture` from a shell command **matches that same shell command** and kills
+  itself; use `pkill -f 'bin/kwcaptur[e] serv[e]'` or a unique `--shm` path to match.
+* **The exec_shell tool caps out at 60 s** — `bench.py` (8 cases) and `tests.py` are close
+  to that; run them with fewer seconds (`bench.py 1`) or background them.
+* `PIL.ImageGrab` can leave a `spectacle` process holding your stdout pipe open (looks like
+  a hang); `bench.py` reaps the ones it started.
+
+## Packaging gotchas (v0.1.0)
+* The wheel contains a compiled binary, so it must **not** be tagged `py3-none-any`:
+  setting `root_is_pure = False` in `build_py.finalize_options` was NOT enough with the
+  PEP 517 flow — override `bdist_wheel.get_tag()` (see `setup.py`) to get
+  `py3-none-linux_x86_64`.
+* `_native.binary_matches_arch()` reads the ELF `e_machine` field so a helper that came
+  from a wheel built for another CPU is skipped (falls back to compiling here).
+* Do **not** import the `kwcapture` package from `setup.py` (it imports numpy, which is not
+  a build dependency) — the compile command is duplicated in `setup.py` on purpose.
+* Use portable `-O2` in `setup.py`; `-march=native` only in the dev `make` build (or
+  `KWCAPTURE_NATIVE=1`).
+* KDE picks up a new desktop entry **asynchronously**: right after writing it, KWin can
+  still answer `NoAuthorized` for a second or two → `Capture.start()` retries with backoff
+  (0.1/0.3/0.6/1.0/1.5 s) and re-runs `kbuildsycoca6` every other attempt.
+* One desktop entry per distinct helper path (`io.github.kwcapture-<sha1(path)[:10]>.desktop`)
+  so several venvs coexist; `_desktop.prune()` drops entries whose binary is gone.
+
+## Ideas not done yet
+* Per-window capture (`CaptureWindow` + window enumeration; KWin has `org.kde.KWin`/Windows?).
+* Multi-monitor: works via one `Capture` per screen name, but there is no combined-mode helper.
+* Auto-restart the daemon inside `grab()` on `DaemonDead` (currently the caller must
+  `restart()`; `kwcapture.grab()` singleton does re-create).
+* Re-size the ring in place on resolution change instead of erroring out.
+* Fractional scaling: `native-resolution` is set; behaviour with scale≠1 untested.
+* If a non-KDE compositor is ever needed: `ext-image-copy-capture-v1`/`wlr-screencopy` with
+  the XML in `/usr/share/wayland-protocols/` + `wayland-scanner` (KWin does not implement it yet).

kwcapture-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+First public release.
+
+- `bin/kwcapture` native helper (sd-bus, single file C): one-shot, `--bench`, `--list`,
+  and a `serve` daemon that keeps a D-Bus connection open and publishes frames into a
+  shared-memory ring.
+- Python API: `Capture` (`grab` / `shot` / `shot_jpeg` / `latest` / `stats` / `bench`),
+  `list_screens()`, zero-copy BGRA views, optional OpenCV-accelerated downscale+encode.
+- Automatic setup on first use: compiles the helper if the wheel did not ship one, and
+  writes the `~/.local/share/applications` desktop entry KWin requires to authorise
+  `org.kde.KWin.ScreenShot2`.
+- CLI: `kwcapture doctor|setup|install-desktop|screens|grab|demo|bench`.
+- Tested against KDE Plasma 6.6 / kwin 6.6.6 on X86-64; ~40 fps at 2560x1440.

kwcapture-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tjandra Satria Gunawan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kwcapture-0.1.0/MANIFEST.in

@@ -0,0 +1,23 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include AGENTS.md
+include pyproject.toml
+include setup.py
+include kwcapture/native/*.c
+include kwcapture/native/include/*.h
+include kwcapture/py.typed
+recursive-include tests *.py
+include bench.py
+include .github/workflows/*.yml
+
+prune kwcapture/bin
+prune probe
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude kwcapture/bin/kwcapture
+global-exclude .DS_Store
+prune **/__pycache__
+prune .venv
+exclude prompt.txt
+exclude bench_result.md

kwcapture-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: kwcapture
+Version: 0.1.0
+Summary: Fast Wayland screen capture for KDE Plasma (KWin): ~40 fps at 1440p with a zero-copy Python API
+Author: Tjandra Satria Gunawan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tjandrasg/kwcapture
+Project-URL: Repository, https://github.com/tjandrasg/kwcapture
+Project-URL: Issues, https://github.com/tjandrasg/kwcapture/issues
+Keywords: wayland,screenshot,screen-capture,kde,plasma,kwin,numpy,computer-use,vision
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: KDE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: fast
+Requires-Dist: opencv-python-headless; extra == "fast"
+Provides-Extra: pil
+Requires-Dist: pillow; extra == "pil"
+Dynamic: license-file
+
+# kwcapture — fast screen capture on Wayland (KDE Plasma)
+
+**`PIL.ImageGrab` runs at ~2 fps on Wayland** (it shells out to `spectacle`) and **`mss`
+captures XWayland**, which is black for native Wayland windows. `kwcapture` talks to the
+KWin compositor directly: **~40 fps at 2560×1440**, real pixels, ~26 ms from "give me a
+frame" to a JPEG ready for a vision model.
+
+```
+method                        fps      median latency
+mss (XWayland)              1113.8      0.9 ms   <-- BLACK, useless on Wayland
+PIL.ImageGrab (spectacle)      2.7    357.1 ms
+kwcapture raw BGRA view       38.4     25.8 ms   real pixels, zero copy
+kwcapture RGB full res        37.9     26.0 ms
+kwcapture JPEG 1280 wide      35.6     28.0 ms   includes downscale + encode
+```
+
+```python
+import kwcapture as K
+
+cap  = K.Capture()                      # starts the helper, first frame in ~50 ms
+arr  = cap.grab()                       # (H, W, 4) BGRA view into shared memory
+rgb  = cap.shot(width=1280)             # (720, 1280, 3) uint8, contiguous
+blob = cap.shot_jpeg(1280, quality=85)  # bytes for a vision API
+cap.stats()                             # {'grab_ms': 20.1, 'total_ms': 27.8, ...}
+cap.close()
+```
+
+## Install
+
+```bash
+pip install kwcapture                     # PyPI
+pip install "kwcapture[fast]"             # + OpenCV: ~8x faster resize/encode
+
+# straight from GitHub (builds the helper for your machine):
+pip install "kwcapture @ git+https://github.com/tjandrasg/kwcapture.git"
+
+# or the prebuilt linux x86-64 wheel from the release page (no compiler needed):
+pip install https://github.com/tjandrasg/kwcapture/releases/download/v0.1.0/kwcapture-0.1.0-py3-none-linux_x86_64.whl
+```
+
+Needs **KDE Plasma with KWin on Wayland** and a C compiler plus `libsystemd`/`wayland-client`
+headers (the wheel builds a small native helper; on Debian/Ubuntu:
+`sudo apt install build-essential libsystemd-dev libwayland-dev`). Only `numpy` is a
+runtime dependency.
+
+Then, in the graphical session:
+
+```bash
+kwcapture doctor          # checks session, helper, KWin authorisation, capture
+```
+
+The first `Capture()` writes the one file KWin needs to authorise us
+(`~/.local/share/applications/io.github.kwcapture-<hash>.desktop`) — no manual setup step.
+Extras: `pip install "kwcapture[fast]"` (OpenCV: ~8x faster resize/encode) or
+`"kwcapture[pil]"` (Pillow).
+
+## Why a native helper (the interesting bit)
+
+KWin exports `org.kde.KWin.ScreenShot2` over D-Bus: you hand it a file descriptor and it
+writes raw ARGB32-premultiplied (BGRA in memory) pixels into it. But it **authorises
+callers by `/proc/<pid>/exe`**: that binary must match the `Exec=` of a `.desktop` file
+declaring `X-KDE-DBUS-Restricted-Interfaces=org.kde.KWin.ScreenShot2` — the trick
+Spectacle uses. A Python interpreter can never satisfy that, so:
+
+```
+kwcapture.py  ──poke──▶  helper (serve)  ──D-Bus──▶  kwin_wayland
+      ◀──mmap ring────        ◀──pipe(fd)────────
+```
+
+The helper keeps one D-Bus connection open and publishes frames into a shared-memory ring,
+so a grab is a byte to a FIFO, a spin on a sequence counter, and a zero-copy numpy view:
+no process per frame, no serialisation, no PNG round trip. KWin sends the reply *before*
+the pixels land, so EOF on the pipe — not the reply — is the frame boundary.
+
+## CLI
+
+```bash
+kwcapture doctor [--fix] [--build]     # is everything OK? (--fix also authorises)
+kwcapture setup                        # build the helper + authorise it
+kwcapture install-desktop [--uninstall]# manage the KWin authorisation file
+kwcapture screens                      # DP-1 2560x1440 @164.69Hz pos 0,0 scale 1
+kwcapture grab -o shot.png --width 1280
+kwcapture grab -o frame.bgra --raw     # pure BGRA bytes
+kwcapture demo --frames 60 --save f.png
+kwcapture bench --frames 200
+```
+
+## Python API
+
+`Capture(...)` arguments:
+
+| argument | meaning |
+|---|---|
+| `screen="DP-1"` | which output (default: active screen) |
+| `area=(x, y, w, h)` | capture a region instead of a whole output |
+| `workspace=True` | capture the entire virtual desktop |
+| `cursor=True` | include the hardware cursor |
+| `decoration=True` | include window decorations and shadows |
+| `slots=4` | ring depth — how many frames until a returned view is overwritten |
+| `depth=2` | requests in flight to KWin (2 is optimal; more adds latency, not fps) |
+| `fps=30` | continuous capture mode; read with `latest()` for zero-latency access |
+| `idle_exit=300` | helper quits when untouched for this many seconds |
+| `binary=…`, `allow_build=…` | override / disable locating-or-building the helper |
+| `install_desktop=False` | don't touch `~/.local/share/applications` |
+| `verbose=True` | report build/authorisation steps |
+
+Methods: `grab(rgb=False, copy=False, fresh=True)`, `latest()`, `shot(width=…, resample=…)`,
+`shot_png()`, `shot_jpeg()`, `stats()`, `geometry()`, `screen_name`, `bench(frames)`,
+`restart()`, `close()` (also a context manager). Module helpers: `list_screens()`,
+`to_rgb()`, `resize()`, `png_bytes()`, `jpeg_bytes()`, `find_binary()`,
+`install_desktop_file()`.
+
+Notes:
+
+* `grab()` returns a **read-only view** of the shared ring, overwritten after `slots`
+  further frames — use `copy=True` (or `.copy()`) to keep a frame, or `shot()`/`to_rgb()`.
+* `latest()` returns the newest published frame **without** asking KWin for one.
+* `hide_caller_windows=True` by default: KWin hides the capturing process' own windows,
+  so your overlay/terminal does not end up in the shot (`--no-hide-caller` to disable).
+* Each `Capture` gets its own ring in `$XDG_RUNTIME_DIR`, so several can run at once
+  (e.g. one per monitor). The helper also dies with its client (`PR_SET_PDEATHSIG`).
+
+## Performance notes (2560×1440@165 Hz, Plasma 6.6, i9-13900K)
+
+* ~11 ms is a fixed cost inside KWin (a 320×180 grab still takes 11 ms); 1440p adds ~7 ms
+  of grab and ~5 ms to move 14 MB across the pipe.
+* **~47 fps is the hard ceiling** — KWin serialises screenshot jobs. `depth=2` reaches it;
+  `depth=3/4` only add latency (37/59/81 ms per frame).
+* Post-processing: OpenCV `INTER_AREA` 2560→1280 ≈ 0.1 ms, `cvtColor` ≈3 ms, JPEG
+  1280 ≈3.5 ms / 2560 ≈4.5 ms, PNG ≈23 ms (prefer JPEG), Pillow resize ≈17 ms.
+* Without OpenCV *or* Pillow, downscaling falls back to numpy (box-average on integer
+  factors, nearest otherwise) and image encoding raises a hint to install an extra.
+* The ring file looks like 226 MB but is sparse: 15 MB resident at 1440p.
+
+## Repo layout
+
+```
+kwcapture/
+  __init__.py            Python API (Capture, grab/shot, shm ctypes mirror)
+  __main__.py            CLI: doctor / setup / install-desktop / screens / grab / demo / bench
+  _native.py             find or compile the helper ($KWCAPTURE_BIN, wheel, cache, source)
+  _desktop.py            the KWin authorisation desktop entry
+  native/kwcapture.c     the capture daemon (sd-bus + shm ring + wl_output listing)
+  native/include/kwcapture_shm.h   shared-memory protocol (asserted on both sides)
+tests/test_kwcapture.py  27 functional tests (also `pytest tests/`)
+bench.py                 comparison against mss and PIL.ImageGrab
+probe/                   the reverse-engineering experiments (Wayland global dumper, etc.)
+AGENTS.md                investigation log — how the KWin API and its auth really work
+```
+
+Development:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install numpy pillow opencv-python-headless
+make setup          # build the helper into kwcapture/bin + authorise
+make test bench     # tests, then the comparison table
+make wheel          # dist/*.whl
+```
+
+## Troubleshooting
+
+| symptom | cause / fix |
+|---|---|
+| `The process is not authorized to take a screenshot` | `kwcapture install-desktop`, then retry (KDE's service cache notices the new file asynchronously — `Capture` already retries for a few seconds) |
+| `no frame within 2.0s` | helper died: `Capture.restart()`, or `Capture(daemon_stderr=sys.stderr)` to see its log; `kwcapture doctor` |
+| `failed to compile the kwcapture helper` | install `build-essential libsystemd-dev libwayland-dev`, or build it yourself and set `KWCAPTURE_BIN` |
+| `frame needs N bytes, slot has M` | resolution went above ~5K: restart the helper |
+| works in a terminal but not from cron/SSH | you need `WAYLAND_DISPLAY` **and** `DBUS_SESSION_BUS_ADDRESS` of the graphical session |
+| colours wrong somewhere | `grab()` is BGRA; `shot()`/`to_rgb()` are RGB |
+
+Non-KDE compositors need `ext-image-copy-capture-v1` / `wlr-screencopy-unstable-v1`
+instead (kwcapture does not implement those; `probe/globals.c` shows how to check what a
+compositor advertises).
+
+## License
+
+MIT — see `LICENSE`. `AGENTS.md` documents the reverse engineering behind it.

kwcapture-0.1.0/README.md

@@ -0,0 +1,177 @@
+# kwcapture — fast screen capture on Wayland (KDE Plasma)
+
+**`PIL.ImageGrab` runs at ~2 fps on Wayland** (it shells out to `spectacle`) and **`mss`
+captures XWayland**, which is black for native Wayland windows. `kwcapture` talks to the
+KWin compositor directly: **~40 fps at 2560×1440**, real pixels, ~26 ms from "give me a
+frame" to a JPEG ready for a vision model.
+
+```
+method                        fps      median latency
+mss (XWayland)              1113.8      0.9 ms   <-- BLACK, useless on Wayland
+PIL.ImageGrab (spectacle)      2.7    357.1 ms
+kwcapture raw BGRA view       38.4     25.8 ms   real pixels, zero copy
+kwcapture RGB full res        37.9     26.0 ms
+kwcapture JPEG 1280 wide      35.6     28.0 ms   includes downscale + encode
+```
+
+```python
+import kwcapture as K
+
+cap  = K.Capture()                      # starts the helper, first frame in ~50 ms
+arr  = cap.grab()                       # (H, W, 4) BGRA view into shared memory
+rgb  = cap.shot(width=1280)             # (720, 1280, 3) uint8, contiguous
+blob = cap.shot_jpeg(1280, quality=85)  # bytes for a vision API
+cap.stats()                             # {'grab_ms': 20.1, 'total_ms': 27.8, ...}
+cap.close()
+```
+
+## Install
+
+```bash
+pip install kwcapture                     # PyPI
+pip install "kwcapture[fast]"             # + OpenCV: ~8x faster resize/encode
+
+# straight from GitHub (builds the helper for your machine):
+pip install "kwcapture @ git+https://github.com/tjandrasg/kwcapture.git"
+
+# or the prebuilt linux x86-64 wheel from the release page (no compiler needed):
+pip install https://github.com/tjandrasg/kwcapture/releases/download/v0.1.0/kwcapture-0.1.0-py3-none-linux_x86_64.whl
+```
+
+Needs **KDE Plasma with KWin on Wayland** and a C compiler plus `libsystemd`/`wayland-client`
+headers (the wheel builds a small native helper; on Debian/Ubuntu:
+`sudo apt install build-essential libsystemd-dev libwayland-dev`). Only `numpy` is a
+runtime dependency.
+
+Then, in the graphical session:
+
+```bash
+kwcapture doctor          # checks session, helper, KWin authorisation, capture
+```
+
+The first `Capture()` writes the one file KWin needs to authorise us
+(`~/.local/share/applications/io.github.kwcapture-<hash>.desktop`) — no manual setup step.
+Extras: `pip install "kwcapture[fast]"` (OpenCV: ~8x faster resize/encode) or
+`"kwcapture[pil]"` (Pillow).
+
+## Why a native helper (the interesting bit)
+
+KWin exports `org.kde.KWin.ScreenShot2` over D-Bus: you hand it a file descriptor and it
+writes raw ARGB32-premultiplied (BGRA in memory) pixels into it. But it **authorises
+callers by `/proc/<pid>/exe`**: that binary must match the `Exec=` of a `.desktop` file
+declaring `X-KDE-DBUS-Restricted-Interfaces=org.kde.KWin.ScreenShot2` — the trick
+Spectacle uses. A Python interpreter can never satisfy that, so:
+
+```
+kwcapture.py  ──poke──▶  helper (serve)  ──D-Bus──▶  kwin_wayland
+      ◀──mmap ring────        ◀──pipe(fd)────────
+```
+
+The helper keeps one D-Bus connection open and publishes frames into a shared-memory ring,
+so a grab is a byte to a FIFO, a spin on a sequence counter, and a zero-copy numpy view:
+no process per frame, no serialisation, no PNG round trip. KWin sends the reply *before*
+the pixels land, so EOF on the pipe — not the reply — is the frame boundary.
+
+## CLI
+
+```bash
+kwcapture doctor [--fix] [--build]     # is everything OK? (--fix also authorises)
+kwcapture setup                        # build the helper + authorise it
+kwcapture install-desktop [--uninstall]# manage the KWin authorisation file
+kwcapture screens                      # DP-1 2560x1440 @164.69Hz pos 0,0 scale 1
+kwcapture grab -o shot.png --width 1280
+kwcapture grab -o frame.bgra --raw     # pure BGRA bytes
+kwcapture demo --frames 60 --save f.png
+kwcapture bench --frames 200
+```
+
+## Python API
+
+`Capture(...)` arguments:
+
+| argument | meaning |
+|---|---|
+| `screen="DP-1"` | which output (default: active screen) |
+| `area=(x, y, w, h)` | capture a region instead of a whole output |
+| `workspace=True` | capture the entire virtual desktop |
+| `cursor=True` | include the hardware cursor |
+| `decoration=True` | include window decorations and shadows |
+| `slots=4` | ring depth — how many frames until a returned view is overwritten |
+| `depth=2` | requests in flight to KWin (2 is optimal; more adds latency, not fps) |
+| `fps=30` | continuous capture mode; read with `latest()` for zero-latency access |
+| `idle_exit=300` | helper quits when untouched for this many seconds |
+| `binary=…`, `allow_build=…` | override / disable locating-or-building the helper |
+| `install_desktop=False` | don't touch `~/.local/share/applications` |
+| `verbose=True` | report build/authorisation steps |
+
+Methods: `grab(rgb=False, copy=False, fresh=True)`, `latest()`, `shot(width=…, resample=…)`,
+`shot_png()`, `shot_jpeg()`, `stats()`, `geometry()`, `screen_name`, `bench(frames)`,
+`restart()`, `close()` (also a context manager). Module helpers: `list_screens()`,
+`to_rgb()`, `resize()`, `png_bytes()`, `jpeg_bytes()`, `find_binary()`,
+`install_desktop_file()`.
+
+Notes:
+
+* `grab()` returns a **read-only view** of the shared ring, overwritten after `slots`
+  further frames — use `copy=True` (or `.copy()`) to keep a frame, or `shot()`/`to_rgb()`.
+* `latest()` returns the newest published frame **without** asking KWin for one.
+* `hide_caller_windows=True` by default: KWin hides the capturing process' own windows,
+  so your overlay/terminal does not end up in the shot (`--no-hide-caller` to disable).
+* Each `Capture` gets its own ring in `$XDG_RUNTIME_DIR`, so several can run at once
+  (e.g. one per monitor). The helper also dies with its client (`PR_SET_PDEATHSIG`).
+
+## Performance notes (2560×1440@165 Hz, Plasma 6.6, i9-13900K)
+
+* ~11 ms is a fixed cost inside KWin (a 320×180 grab still takes 11 ms); 1440p adds ~7 ms
+  of grab and ~5 ms to move 14 MB across the pipe.
+* **~47 fps is the hard ceiling** — KWin serialises screenshot jobs. `depth=2` reaches it;
+  `depth=3/4` only add latency (37/59/81 ms per frame).
+* Post-processing: OpenCV `INTER_AREA` 2560→1280 ≈ 0.1 ms, `cvtColor` ≈3 ms, JPEG
+  1280 ≈3.5 ms / 2560 ≈4.5 ms, PNG ≈23 ms (prefer JPEG), Pillow resize ≈17 ms.
+* Without OpenCV *or* Pillow, downscaling falls back to numpy (box-average on integer
+  factors, nearest otherwise) and image encoding raises a hint to install an extra.
+* The ring file looks like 226 MB but is sparse: 15 MB resident at 1440p.
+
+## Repo layout
+
+```
+kwcapture/
+  __init__.py            Python API (Capture, grab/shot, shm ctypes mirror)
+  __main__.py            CLI: doctor / setup / install-desktop / screens / grab / demo / bench
+  _native.py             find or compile the helper ($KWCAPTURE_BIN, wheel, cache, source)
+  _desktop.py            the KWin authorisation desktop entry
+  native/kwcapture.c     the capture daemon (sd-bus + shm ring + wl_output listing)
+  native/include/kwcapture_shm.h   shared-memory protocol (asserted on both sides)
+tests/test_kwcapture.py  27 functional tests (also `pytest tests/`)
+bench.py                 comparison against mss and PIL.ImageGrab
+probe/                   the reverse-engineering experiments (Wayland global dumper, etc.)
+AGENTS.md                investigation log — how the KWin API and its auth really work
+```
+
+Development:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install numpy pillow opencv-python-headless
+make setup          # build the helper into kwcapture/bin + authorise
+make test bench     # tests, then the comparison table
+make wheel          # dist/*.whl
+```
+
+## Troubleshooting
+
+| symptom | cause / fix |
+|---|---|
+| `The process is not authorized to take a screenshot` | `kwcapture install-desktop`, then retry (KDE's service cache notices the new file asynchronously — `Capture` already retries for a few seconds) |
+| `no frame within 2.0s` | helper died: `Capture.restart()`, or `Capture(daemon_stderr=sys.stderr)` to see its log; `kwcapture doctor` |
+| `failed to compile the kwcapture helper` | install `build-essential libsystemd-dev libwayland-dev`, or build it yourself and set `KWCAPTURE_BIN` |
+| `frame needs N bytes, slot has M` | resolution went above ~5K: restart the helper |
+| works in a terminal but not from cron/SSH | you need `WAYLAND_DISPLAY` **and** `DBUS_SESSION_BUS_ADDRESS` of the graphical session |
+| colours wrong somewhere | `grab()` is BGRA; `shot()`/`to_rgb()` are RGB |
+
+Non-KDE compositors need `ext-image-copy-capture-v1` / `wlr-screencopy-unstable-v1`
+instead (kwcapture does not implement those; `probe/globals.c` shows how to check what a
+compositor advertises).
+
+## License
+
+MIT — see `LICENSE`. `AGENTS.md` documents the reverse engineering behind it.