capturekit 0.1.0__py3-none-any.whl

capturekit/_backends/windows/api.py

@@ -0,0 +1,214 @@
+"""Windows backend facade used by the public API."""
+
+from __future__ import annotations
+
+import contextlib
+import platform
+from collections.abc import Iterator
+
+from ...capabilities import (
+    Capabilities,
+    Capability,
+    experimental,
+    supported,
+    unavailable,
+    unsupported,
+)
+from ...errors import (
+    CapabilityUnavailableError,
+    TargetNotFoundError,
+    UnsupportedDisplayServerError,
+)
+from ...sources import (
+    AudioSourceSpec,
+    MicrophoneSource,
+    MonitorBackend,
+    MonitorSource,
+    ProcessAudioSource,
+    SystemAudioSource,
+    WindowSource,
+    audio_source_label,
+)
+from ...types import AudioDevice, AudioSession, Monitor, Window
+from ..base import AudioBackend, VideoBackend
+from . import _win32, wasapi
+from ._winrt import RoApartment
+
+PLATFORM = "windows"
+WGC_WINDOW_MIN_BUILD = 18362  # CreateForWindow interop (1903)
+WGC_BORDER_MIN_BUILD = 20348
+
+
+def _no_display(display: str | None) -> None:
+    if display is not None:
+        raise UnsupportedDisplayServerError("display strings are only meaningful on Linux/X11")
+
+
+@contextlib.contextmanager
+def thread_context() -> Iterator[None]:
+    """Per-thread runtime initialisation for backend worker threads."""
+    with RoApartment():
+        yield
+
+
+def list_monitors(display: str | None = None) -> list[Monitor]:
+    _no_display(display)
+    return _win32.list_monitors()
+
+
+def list_windows(display: str | None = None, include_untitled: bool = False) -> list[Window]:
+    _no_display(display)
+    return _win32.list_windows(include_untitled)
+
+
+def get_window(handle: int, display: str | None = None) -> Window:
+    _no_display(display)
+    if not _win32.is_window(handle):
+        raise TargetNotFoundError(f"window {handle:#x} does not exist")
+    return _win32.describe_window(handle)
+
+
+def resolve_monitor(spec: Monitor | int | None, display: str | None = None) -> Monitor:
+    monitors = list_monitors(display)
+    if not monitors:
+        raise TargetNotFoundError("no monitors found")
+    if spec is None:
+        return next((m for m in monitors if m.is_primary), monitors[0])
+    if isinstance(spec, int):
+        if not 0 <= spec < len(monitors):
+            raise TargetNotFoundError(f"monitor index {spec} out of range (0..{len(monitors) - 1})")
+        return monitors[spec]
+    for m in monitors:
+        if m.id == spec.id or m.native_handle == spec.native_handle:
+            return m
+    raise TargetNotFoundError(f"monitor {spec.id} is no longer connected")
+
+
+def open_video(source: MonitorSource | WindowSource) -> VideoBackend:
+    """Create (not start) a video backend. Must be started on a thread inside
+    :func:`thread_context`."""
+    from .dxgi_duplication import DxgiDuplicationBackend
+    from .wgc import WgcBackend
+
+    if isinstance(source, WindowSource):
+        _no_display(source.display)
+        if _build() < WGC_WINDOW_MIN_BUILD:
+            raise CapabilityUnavailableError("window capture needs Windows 10 1903 or newer")
+        return WgcBackend(
+            hwnd=source.handle,
+            region=source.region,
+            client_area_only=source.client_area_only,
+            include_cursor=source.include_cursor,
+            border=source.border,
+        )
+    _no_display(source.display)
+    monitor = resolve_monitor(source.monitor)
+    if source.backend is MonitorBackend.WGC:
+        return WgcBackend(
+            monitor=monitor, region=source.region, include_cursor=source.include_cursor
+        )
+    if source.backend not in (MonitorBackend.AUTO, MonitorBackend.DXGI):
+        raise CapabilityUnavailableError(
+            f"monitor backend {source.backend.value} is not available on Windows"
+        )
+    return DxgiDuplicationBackend(monitor, source.region, source.include_cursor)
+
+
+def list_audio_devices() -> list[AudioDevice]:
+    return wasapi.list_devices()
+
+
+def list_audio_sessions() -> list[AudioSession]:
+    return wasapi.list_sessions()
+
+
+def _device_id(dev: AudioDevice | str | None) -> str | None:
+    if isinstance(dev, AudioDevice):
+        return dev.id
+    return dev
+
+
+def open_audio(spec: AudioSourceSpec, sample_rate: int, channels: int = 2) -> AudioBackend:
+    name = audio_source_label(spec)
+    if isinstance(spec, MicrophoneSource):
+        return wasapi.WasapiCapture(
+            "microphone",
+            device_id=_device_id(spec.device),
+            sample_rate=sample_rate,
+            channels=channels,
+            name=name,
+        )
+    if isinstance(spec, SystemAudioSource):
+        return wasapi.WasapiCapture(
+            "system",
+            device_id=_device_id(spec.device),
+            sample_rate=sample_rate,
+            channels=channels,
+            name=name,
+        )
+    if isinstance(spec, ProcessAudioSource):
+        if spec.stream_ids:
+            raise CapabilityUnavailableError(
+                "stream_ids selection is Linux-only; on Windows select the process by PID"
+            )
+        return wasapi.WasapiCapture(
+            "process",
+            pid=spec.pid,
+            include_tree=spec.include_children,
+            sample_rate=sample_rate,
+            channels=channels,
+            name=name,
+        )
+    raise TypeError(f"unknown audio source {spec!r}")
+
+
+def _build() -> int:
+    return wasapi.windows_build()
+
+
+def capabilities(display: str | None = None) -> Capabilities:
+    _no_display(display)
+    build = _build()
+    from .wgc import is_supported
+
+    with RoApartment():
+        wgc_ok = is_supported()
+    if not wgc_ok:
+        window: Capability = unavailable("Windows Graphics Capture not supported on this system")
+    elif build < WGC_WINDOW_MIN_BUILD:
+        window = unavailable("window capture requires Windows 10 1903 (build 18362)+")
+    else:
+        window = supported("Windows Graphics Capture (CreateForWindow)")
+    border = (
+        experimental("IsBorderRequired=false accepted on this build; OS may still enforce it")
+        if build >= WGC_BORDER_MIN_BUILD and wgc_ok
+        else unavailable(f"requires build {WGC_BORDER_MIN_BUILD}+")
+    )
+    proc = (
+        supported("WASAPI process loopback (includes child processes)")
+        if wasapi.process_loopback_supported()
+        else unavailable(f"requires build {wasapi.PROCESS_LOOPBACK_MIN_BUILD}+ (this: {build})")
+    )
+    return Capabilities(
+        platform=PLATFORM,
+        os_version=f"{platform.release()} build {build}",
+        display_server="dwm",
+        monitor_capture=supported("DXGI Desktop Duplication (WGC monitor capture optional)"),
+        window_capture=window,
+        window_capture_borderless=border,
+        window_capture_minimized=unsupported(
+            "minimized windows are not rendered by DWM; WGC delivers no new frames "
+            "(the recording repeats the last frame)"
+        ),
+        cursor_capture=supported("DXGI: software-composited; WGC: IsCursorCaptureEnabled"),
+        microphone_audio=supported("WASAPI capture endpoint"),
+        system_audio=supported("WASAPI endpoint loopback"),
+        process_audio=proc,
+        audio_session_enumeration=supported("IAudioSessionManager2"),
+        recording=supported("FFmpeg subprocess (requires an FFmpeg executable)"),
+    )
+
+
+__all__ = [
+    "audio_source_label",
+]

capturekit/_backends/windows/cursor.py

@@ -0,0 +1,66 @@
+"""Software cursor compositing for DXGI duplication (which excludes the cursor)."""
+
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+POINTER_MONOCHROME = 1
+POINTER_COLOR = 2
+POINTER_MASKED_COLOR = 4
+
+Buffer = npt.NDArray[np.uint8]
+
+
+class CursorShape:
+    def __init__(self, kind: int, width: int, height: int, pitch: int, data: bytes) -> None:
+        self.kind = kind
+        self.width = width
+        self.height = height
+        self.pitch = pitch
+        self.data = data
+        row_bytes = (width + 7) // 8 if kind == POINTER_MONOCHROME else width * 4
+        if width <= 0 or height <= 0 or pitch < row_bytes or pitch * height > len(data):
+            raise ValueError(f"malformed pointer shape {kind} {width}x{height} pitch {pitch}")
+        raw = np.frombuffer(data, dtype=np.uint8)
+        if kind == POINTER_MONOCHROME:
+            # height covers AND mask followed by XOR mask, 1 bpp
+            h = height // 2
+            bits = np.unpackbits(raw[: pitch * height].reshape(height, pitch), axis=1)[:, :width]
+            self.and_mask = bits[:h].astype(bool)
+            self.xor_mask = bits[h:].astype(bool)
+            self.height = h
+            self.bgra = None
+        else:
+            self.bgra = (
+                raw[: pitch * height]
+                .reshape(height, pitch)[:, : width * 4]
+                .reshape(height, width, 4)
+            )
+
+
+def composite(out: Buffer, shape: CursorShape, x: int, y: int) -> None:
+    """Draw ``shape`` with its top-left at ``(x, y)`` in ``out`` (clipped)."""
+    h, w = shape.height, shape.width
+    x0, y0 = max(0, x), max(0, y)
+    x1, y1 = min(out.shape[1], x + w), min(out.shape[0], y + h)
+    if x0 >= x1 or y0 >= y1:
+        return
+    dst = out[y0:y1, x0:x1, :3]
+    sy, sx = slice(y0 - y, y1 - y), slice(x0 - x, x1 - x)
+    if shape.kind == POINTER_MONOCHROME:
+        and_m = shape.and_mask[sy, sx]
+        xor_m = shape.xor_mask[sy, sx]
+        res = np.where(and_m[..., None], dst, 0).astype(np.uint8)
+        res = np.where(xor_m[..., None], res ^ 0xFF, res).astype(np.uint8)
+        dst[...] = res
+        return
+    assert shape.bgra is not None
+    src = shape.bgra[sy, sx]
+    if shape.kind == POINTER_COLOR:
+        a = src[..., 3:4].astype(np.uint16)
+        blended = (src[..., :3].astype(np.uint16) * a + dst.astype(np.uint16) * (255 - a)) // 255
+        dst[...] = blended.astype(np.uint8)
+    else:  # masked colour: alpha 0 → replace, 0xFF → XOR
+        mask = src[..., 3:4] == 0xFF
+        dst[...] = np.where(mask, dst ^ src[..., :3], src[..., :3])

capturekit/_backends/windows/dxgi_duplication.py

@@ -0,0 +1,310 @@
+"""Monitor capture with DXGI Desktop Duplication."""
+
+from __future__ import annotations
+
+import ctypes
+import logging
+import time
+from ctypes import Structure, byref, c_int64, c_long, c_uint, c_void_p
+from ctypes import wintypes as wt
+
+import numpy as np
+
+from ..._pipeline.clock import now_ns
+from ...errors import AccessDeniedError, CapabilityUnavailableError, NativeError
+from ...types import Monitor, Rect, validate_region
+from ..base import AcquiredFrame, Buffer, VideoBackendInfo, blit_clear, crop_box
+from . import _d3d11
+from ._com import ComPtr, check_hr, hr_u32
+from .cursor import CursorShape, composite
+
+log = logging.getLogger("capturekit.windows.dxgi")
+
+DXGI_ERROR_ACCESS_LOST = -2005270490  # 0x887A0026
+DXGI_ERROR_WAIT_TIMEOUT = -2005270489  # 0x887A0027
+DXGI_ERROR_UNSUPPORTED = -2005270524  # 0x887A0004
+DXGI_ERROR_NOT_CURRENTLY_AVAILABLE = -2005270494  # 0x887A0022
+DXGI_ERROR_SESSION_DISCONNECTED = -2005270492  # 0x887A0024
+E_ACCESSDENIED = -2147024891  # 0x80070005
+DXGI_MODE_ROTATION_IDENTITY = 1
+DXGI_MODE_ROTATION_UNSPECIFIED = 0
+
+# IDXGIOutputDuplication
+_DUP_GetDesc = 7
+_DUP_AcquireNextFrame = 8
+_DUP_GetFramePointerShape = 11
+_DUP_ReleaseFrame = 14
+# IDXGIOutput1
+_OUT1_DuplicateOutput = 22
+
+
+class _TransientUnavailableError(CapabilityUnavailableError):
+    """Duplication temporarily unavailable (exclusive full-screen app, too many
+    duplications); recovery retries. Other CapabilityUnavailableErrors (e.g. a
+    monitor rotated mid-capture) are permanent and propagate."""
+
+
+class DXGI_OUTDUPL_POINTER_POSITION(Structure):
+    _fields_ = [("Position", wt.POINT), ("Visible", wt.BOOL)]
+
+
+class DXGI_OUTDUPL_FRAME_INFO(Structure):
+    _fields_ = [
+        ("LastPresentTime", c_int64),
+        ("LastMouseUpdateTime", c_int64),
+        ("AccumulatedFrames", c_uint),
+        ("RectsCoalesced", wt.BOOL),
+        ("ProtectedContentMaskedOut", wt.BOOL),
+        ("PointerPosition", DXGI_OUTDUPL_POINTER_POSITION),
+        ("TotalMetadataBufferSize", c_uint),
+        ("PointerShapeBufferSize", c_uint),
+    ]
+
+
+class DXGI_OUTDUPL_POINTER_SHAPE_INFO(Structure):
+    _fields_ = [
+        ("Type", c_uint),
+        ("Width", c_uint),
+        ("Height", c_uint),
+        ("Pitch", c_uint),
+        ("HotSpot", wt.POINT),
+    ]
+
+
+class DXGI_MODE_DESC(Structure):
+    _fields_ = [
+        ("Width", c_uint),
+        ("Height", c_uint),
+        ("RefreshNumerator", c_uint),
+        ("RefreshDenominator", c_uint),
+        ("Format", c_uint),
+        ("ScanlineOrdering", c_uint),
+        ("Scaling", c_uint),
+    ]
+
+
+class DXGI_OUTDUPL_DESC(Structure):
+    _fields_ = [
+        ("ModeDesc", DXGI_MODE_DESC),
+        ("Rotation", c_uint),
+        ("DesktopImageInSystemMemory", wt.BOOL),
+    ]
+
+
+_kernel32 = ctypes.WinDLL("kernel32")
+_qpc_freq = c_int64()
+_kernel32.QueryPerformanceFrequency(byref(_qpc_freq))
+
+
+class DxgiDuplicationBackend:
+    """Captures one monitor. Rotated outputs are rejected (use the WGC backend)."""
+
+    def __init__(self, monitor: Monitor, region: Rect | None, include_cursor: bool) -> None:
+        self.monitor = monitor
+        self.region = region
+        self.include_cursor = include_cursor
+        self._adapter: ComPtr | None = None
+        self._output1: ComPtr | None = None
+        self._device: ComPtr | None = None
+        self._context: ComPtr | None = None
+        self._dup: ComPtr | None = None
+        self._reader: _d3d11.StagingReader | None = None
+        self._size = (monitor.width, monitor.height)
+        self._crop = crop_box(Rect(0, 0, *self._size), region)
+        self._have_image = False
+        self._cursor_shape: CursorShape | None = None
+        self._cursor_pos = (0, 0)
+        self._cursor_visible = False
+        self.protected_frames = 0
+        self.access_lost_count = 0
+        self.info = VideoBackendInfo("dxgi-duplication", self._crop.size)
+
+    # -- lifecycle ---------------------------------------------------------
+    def start(self) -> None:
+        outputs = _d3d11.enum_outputs()
+        try:
+            match = None
+            for adapter, output, odesc, adesc in outputs:
+                if int(odesc.Monitor or 0) == self.monitor.native_handle and match is None:
+                    match = (adapter, output, adesc)
+                else:
+                    adapter.release()
+                    output.release()
+            if match is None:
+                raise CapabilityUnavailableError(
+                    f"no DXGI output for monitor {self.monitor.id}; the display may be driven "
+                    "by an indirect/virtual driver — try MonitorBackend.WGC"
+                )
+            adapter, output, adesc = match
+            self._adapter = adapter
+            self.info.details["adapter"] = adesc.Description
+            self._output1 = output.query(_d3d11.IID_IDXGIOutput1, "IDXGIOutput1")
+            output.release()
+            self._device, self._context = _d3d11.create_device(self._adapter)
+            self._reader = _d3d11.StagingReader(self._device, self._context)
+            self._duplicate()
+        except BaseException:
+            self.close()
+            raise
+
+    def _duplicate(self) -> None:
+        assert self._output1 is not None and self._device is not None
+        out = c_void_p()
+        hr = self._output1.call(
+            _OUT1_DuplicateOutput, c_long, (c_void_p, c_void_p), self._device.as_param, byref(out)
+        )
+        if hr == DXGI_ERROR_UNSUPPORTED:
+            raise CapabilityUnavailableError(
+                "DXGI Desktop Duplication is not supported for this output/adapter "
+                "(hybrid-GPU or remote session) — try MonitorBackend.WGC"
+            )
+        if hr == DXGI_ERROR_NOT_CURRENTLY_AVAILABLE:  # transient: retried by _recover
+            raise _TransientUnavailableError(
+                "DXGI Desktop Duplication is currently unavailable (too many duplication "
+                "sessions or a full-screen exclusive application)"
+            )
+        if hr == E_ACCESSDENIED:
+            raise AccessDeniedError("desktop duplication denied (secure desktop / lock screen?)")
+        check_hr(hr, "IDXGIOutput1::DuplicateOutput")
+        dup = ComPtr(out.value, "IDXGIOutputDuplication")
+        try:
+            self._validate_duplication(dup)
+        except BaseException:
+            dup.release()
+            raise
+        self._dup = dup
+
+    def _validate_duplication(self, dup: ComPtr) -> None:
+        desc = DXGI_OUTDUPL_DESC()
+        dup.call(_DUP_GetDesc, None, (c_void_p,), byref(desc))
+        if desc.Rotation not in (DXGI_MODE_ROTATION_IDENTITY, DXGI_MODE_ROTATION_UNSPECIFIED):
+            raise CapabilityUnavailableError(
+                "rotated monitors are not supported by the DXGI backend; use MonitorBackend.WGC"
+            )
+        size = (int(desc.ModeDesc.Width), int(desc.ModeDesc.Height))
+        if size != self._size:
+            log.info("duplication size %s differs from monitor rect %s", size, self._size)
+            self._size = size
+        if self.region is not None:
+            validate_region(self.region, self._size)
+        self._crop = crop_box(Rect(0, 0, *self._size), self.region)
+        self.info.initial_size = self._crop.size
+        self.info.details["refresh"] = (
+            desc.ModeDesc.RefreshNumerator / desc.ModeDesc.RefreshDenominator
+            if desc.ModeDesc.RefreshDenominator else None
+        )  # fmt: skip
+
+    def close(self) -> None:
+        if self._reader is not None:
+            self._reader.release()
+            self._reader = None
+        for name in ("_dup", "_output1", "_context", "_device", "_adapter"):
+            p = getattr(self, name)
+            if p is not None:
+                p.release()
+                setattr(self, name, None)
+
+    # -- capture -------------------------------------------------------------
+    def _recover(self) -> None:
+        self.access_lost_count += 1
+        if self._dup is not None:
+            self._dup.release()
+            self._dup = None
+        try:
+            self._duplicate()
+        except (AccessDeniedError, _TransientUnavailableError, NativeError) as exc:
+            # Secure desktop / mode switch in progress: retry on next acquire.
+            log.debug("duplication not yet available: %s", exc)
+
+    def acquire(self, out: Buffer | None, timeout_s: float) -> AcquiredFrame | None:
+        # AcquireNextFrame may return pointer-only updates; keep waiting for an
+        # image until the timeout expires.
+        deadline = now_ns() + int(timeout_s * 1e9)
+        while True:
+            remaining = max(0.0, (deadline - now_ns()) / 1e9)
+            frame = self._acquire_once(out, remaining)
+            if frame is not None or remaining <= 0:
+                return frame
+
+    def _acquire_once(self, out: Buffer | None, timeout_s: float) -> AcquiredFrame | None:
+        if self._dup is None:
+            self._recover()
+            if self._dup is None:
+                if timeout_s > 0:
+                    time.sleep(min(timeout_s, 0.05))
+                return None
+        dup = self._dup
+        info = DXGI_OUTDUPL_FRAME_INFO()
+        res = c_void_p()
+        hr = dup.call(
+            _DUP_AcquireNextFrame, c_long, (c_uint, c_void_p, c_void_p),
+            max(0, int(timeout_s * 1000)), byref(info), byref(res),
+        )  # fmt: skip
+        if hr == DXGI_ERROR_WAIT_TIMEOUT:
+            return None
+        if hr in (DXGI_ERROR_ACCESS_LOST, E_ACCESSDENIED, DXGI_ERROR_SESSION_DISCONNECTED):
+            log.info("duplication lost (0x%08X); recreating", hr_u32(hr))
+            self._recover()
+            return None
+        check_hr(hr, "AcquireNextFrame")
+        resource = ComPtr(res.value, "IDXGIResource")
+        try:
+            assert self._reader is not None
+            # Frames with LastPresentTime == 0 carry only pointer/metadata updates;
+            # their texture is not a valid desktop image (verified: all-zero).
+            new_image = info.LastPresentTime != 0
+            cursor_changed = False
+            if self.include_cursor and info.LastMouseUpdateTime != 0:
+                pos = (info.PointerPosition.Position.x, info.PointerPosition.Position.y)
+                vis = bool(info.PointerPosition.Visible)
+                cursor_changed = pos != self._cursor_pos or vis != self._cursor_visible
+                self._cursor_pos, self._cursor_visible = pos, vis
+                if info.PointerShapeBufferSize:
+                    self._read_pointer_shape(info.PointerShapeBufferSize)
+                    cursor_changed = True
+            if info.ProtectedContentMaskedOut:
+                self.protected_frames += 1
+            if new_image:
+                with resource.query(_d3d11.IID_ID3D11Texture2D, "ID3D11Texture2D") as tex:
+                    c = self._crop
+                    self._reader.copy_box(tex, c.x, c.y, c.width, c.height)
+                self._have_image = True
+            if not (new_image or (cursor_changed and self._have_image)):
+                return None
+            w, h = self._crop.size
+            dest = out if out is not None else np.empty((h, w, 4), dtype=np.uint8)
+            # Map waits for the GPU copy; done before ReleaseFrame so DWM cannot
+            # overwrite the desktop surface while it is being copied.
+            self._reader.read_into(dest)
+            blit_clear(dest, min(w, dest.shape[1]), min(h, dest.shape[0]))
+            if self.include_cursor and self._cursor_visible and self._cursor_shape is not None:
+                composite(
+                    dest,
+                    self._cursor_shape,
+                    self._cursor_pos[0] - self._crop.x,
+                    self._cursor_pos[1] - self._crop.y,
+                )
+            ts = (info.LastPresentTime * 1_000_000_000 // _qpc_freq.value) if new_image else 0
+            return AcquiredFrame(dest, ts or now_ns(), self._size)
+        finally:
+            resource.release()
+            dup.call(_DUP_ReleaseFrame, c_long, ())
+
+    def _read_pointer_shape(self, size: int) -> None:
+        assert self._dup is not None
+        buf = (ctypes.c_ubyte * size)()
+        required = c_uint()
+        sinfo = DXGI_OUTDUPL_POINTER_SHAPE_INFO()
+        hr = self._dup.call(
+            _DUP_GetFramePointerShape, c_long, (c_uint, c_void_p, c_void_p, c_void_p),
+            size, buf, byref(required), byref(sinfo),
+        )  # fmt: skip
+        if hr < 0:
+            log.debug("GetFramePointerShape failed 0x%08X", hr_u32(hr))
+            return
+        try:
+            self._cursor_shape = CursorShape(
+                int(sinfo.Type), int(sinfo.Width), int(sinfo.Height), int(sinfo.Pitch), bytes(buf)
+            )
+        except ValueError as exc:
+            log.debug("ignoring cursor shape: %s", exc)