capturekit 0.1.0__py3-none-any.whl

capturekit/sources.py

@@ -0,0 +1,124 @@
+"""Source specifications.
+
+Sources are immutable descriptions of *what* to capture. They hold no native
+resources; capture sessions and recorders open them.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+from .types import AudioDevice, Monitor, Rect, Window
+
+
+class MonitorBackend(enum.Enum):
+    AUTO = "auto"
+    #: Windows: DXGI Desktop Duplication (default).
+    DXGI = "dxgi"
+    #: Windows: Windows Graphics Capture of the whole monitor.
+    WGC = "wgc"
+    #: Linux: X11 GetImage/XShm.
+    X11 = "x11"
+
+
+@dataclass(frozen=True, slots=True)
+class MonitorSource:
+    """Capture a monitor, optionally cropped.
+
+    ``monitor`` may be a :class:`Monitor`, a monitor index, or ``None`` for the
+    primary monitor. ``region`` is relative to the monitor's top-left corner.
+    """
+
+    monitor: Monitor | int | None = None
+    region: Rect | None = None
+    include_cursor: bool = True
+    backend: MonitorBackend = MonitorBackend.AUTO
+    display: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class WindowSource:
+    """Capture one window's own content (never a crop of the desktop).
+
+    ``window`` may be a :class:`Window` or a native handle. ``region`` is
+    relative to the captured content: the whole window (including title bar)
+    or, with ``client_area_only=True``, the client area.
+
+    ``border``: Windows draws a yellow capture border by default. ``False``
+    asks the OS to omit it where the OS permits (Windows 11); ``None`` keeps
+    the OS default.
+    """
+
+    window: Window | int
+    region: Rect | None = None
+    client_area_only: bool = False
+    include_cursor: bool = False
+    border: bool | None = None
+    display: str | None = None
+
+    @property
+    def handle(self) -> int:
+        return self.window.handle if isinstance(self.window, Window) else int(self.window)
+
+
+VideoSource = MonitorSource | WindowSource
+
+
+@dataclass(frozen=True, slots=True)
+class MicrophoneSource:
+    """Audio input device (``None`` = system default input)."""
+
+    device: AudioDevice | str | None = None
+    name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SystemAudioSource:
+    """Everything played on an output device (``None`` = default output)."""
+
+    device: AudioDevice | str | None = None
+    name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessAudioSource:
+    """Audio rendered by one process (and, by default, its child processes).
+
+    Never falls back to whole-system audio: if per-process capture is not
+    available, opening the source raises :class:`CapabilityUnavailableError`.
+    On Linux ``stream_ids`` may pin specific PulseAudio sink-inputs.
+    """
+
+    pid: int
+    include_children: bool = True
+    name: str | None = None
+    stream_ids: tuple[str, ...] = ()
+
+    @classmethod
+    def for_window(cls, window: Window, *, include_children: bool = True) -> ProcessAudioSource:
+        """Audio of the process that owns ``window``.
+
+        Note: the window's process is not always the process that plays the
+        audio (launchers, browser helper processes, audio-server proxies).
+        ``include_children`` covers the common child-process case; use
+        :func:`capturekit.list_audio_sessions` to pick a PID explicitly.
+        """
+        if window.pid is None:
+            from .errors import TargetNotFoundError
+
+            raise TargetNotFoundError(f"process of window {window.handle:#x} is unknown")
+        return cls(window.pid, include_children=include_children, name=window.process_name)
+
+
+AudioSourceSpec = MicrophoneSource | SystemAudioSource | ProcessAudioSource
+
+
+def audio_source_label(src: AudioSourceSpec) -> str:
+    if src.name:
+        return src.name
+    if isinstance(src, MicrophoneSource):
+        return "microphone"
+    if isinstance(src, SystemAudioSource):
+        return "system"
+    return f"process {src.pid}"

capturekit/types.py

@@ -0,0 +1,211 @@
+"""Plain data types shared by all backends.
+
+All coordinates are physical pixels. Monitor rectangles are in virtual-desktop
+coordinates (may be negative). Crop regions are always relative to the
+selected source (monitor or window content).
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .errors import InvalidRegionError
+
+if TYPE_CHECKING:
+    import numpy as np
+    import numpy.typing as npt
+
+
+@dataclass(frozen=True, slots=True)
+class Rect:
+    """Axis-aligned rectangle ``(x, y, width, height)``."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+    @property
+    def right(self) -> int:
+        return self.x + self.width
+
+    @property
+    def bottom(self) -> int:
+        return self.y + self.height
+
+    @property
+    def size(self) -> tuple[int, int]:
+        return (self.width, self.height)
+
+    def is_empty(self) -> bool:
+        return self.width <= 0 or self.height <= 0
+
+    def intersect(self, other: Rect) -> Rect:
+        x = max(self.x, other.x)
+        y = max(self.y, other.y)
+        r = min(self.right, other.right)
+        b = min(self.bottom, other.bottom)
+        return Rect(x, y, max(0, r - x), max(0, b - y))
+
+    def contains(self, other: Rect) -> bool:
+        return (
+            other.x >= self.x
+            and other.y >= self.y
+            and other.right <= self.right
+            and other.bottom <= self.bottom
+        )
+
+    def translate(self, dx: int, dy: int) -> Rect:
+        return Rect(self.x + dx, self.y + dy, self.width, self.height)
+
+    @classmethod
+    def from_ltrb(cls, left: int, top: int, right: int, bottom: int) -> Rect:
+        return cls(left, top, right - left, bottom - top)
+
+
+def validate_region(region: Rect, bounds_size: tuple[int, int]) -> Rect:
+    """Validate a crop region against a source of ``bounds_size``.
+
+    Raises :class:`InvalidRegionError` for empty or out-of-bounds regions.
+    """
+    if region.is_empty():
+        raise InvalidRegionError(f"crop region {region} is empty")
+    w, h = bounds_size
+    if region.x < 0 or region.y < 0 or region.right > w or region.bottom > h:
+        raise InvalidRegionError(f"crop region {region} lies outside the source ({w}x{h})")
+    return region
+
+
+class PixelFormat(enum.Enum):
+    """Pixel layout of :attr:`Frame.data`. Only 8-bit BGRA is produced today."""
+
+    BGRA = "bgra"
+
+
+@dataclass(frozen=True, slots=True)
+class Monitor:
+    """A display output.
+
+    ``id`` is stable for the lifetime of the display configuration (Windows:
+    GDI device name such as ``\\\\.\\DISPLAY1``; X11: RandR monitor/output name).
+    """
+
+    id: str
+    index: int
+    name: str
+    rect: Rect
+    is_primary: bool
+    scale: float = 1.0
+    refresh_rate: float | None = None
+    display: str | None = None
+    native_handle: int = 0
+
+    @property
+    def width(self) -> int:
+        return self.rect.width
+
+    @property
+    def height(self) -> int:
+        return self.rect.height
+
+
+@dataclass(frozen=True, slots=True)
+class Window:
+    """A top-level window that can be targeted for exclusive capture.
+
+    ``handle`` is the native identifier (HWND on Windows, X11 window ID on
+    Linux). ``rect`` is the visible window bounds in desktop coordinates.
+    ``capture_excluded`` is True when the window asked the OS to exclude it
+    from capture (Windows display affinity); capturekit honours that.
+    """
+
+    handle: int
+    title: str
+    class_name: str | None
+    pid: int | None
+    process_name: str | None
+    rect: Rect
+    is_visible: bool
+    is_minimized: bool
+    display: str | None = None
+    capture_excluded: bool = False
+
+
+class AudioDeviceKind(enum.Enum):
+    INPUT = "input"  #: microphones / capture endpoints / Pulse sources
+    OUTPUT = "output"  #: speakers / render endpoints (loopback-capable)
+
+
+@dataclass(frozen=True, slots=True)
+class AudioDevice:
+    id: str
+    name: str
+    kind: AudioDeviceKind
+    is_default: bool
+    channels: int | None = None
+    sample_rate: int | None = None
+    backend: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class AudioSession:
+    """An application audio stream/session and its owning process.
+
+    One process may own several sessions (several streams, several devices).
+    ``stream_id`` identifies the native stream where one exists (PulseAudio
+    sink-input index); Windows sessions are identified by ``pid``.
+    """
+
+    pid: int | None
+    process_name: str | None
+    display_name: str
+    device_id: str | None
+    is_active: bool
+    stream_id: str | None = None
+    backend: str = ""
+
+
+@dataclass(slots=True)
+class Frame:
+    """A captured video frame.
+
+    ``data`` is a ``(height, width, 4)`` uint8 BGRA array owned by the caller.
+    ``timestamp_ns`` is on the capturekit clock (see :func:`capturekit.now_ns`).
+    ``content_size`` is the source content size when the frame was produced
+    (useful to detect window resizes when a fixed output size is used).
+    """
+
+    data: npt.NDArray[np.uint8]
+    timestamp_ns: int
+    index: int
+    content_size: tuple[int, int]
+    pixel_format: PixelFormat = PixelFormat.BGRA
+
+    @property
+    def width(self) -> int:
+        return int(self.data.shape[1])
+
+    @property
+    def height(self) -> int:
+        return int(self.data.shape[0])
+
+
+@dataclass(slots=True)
+class AudioChunk:
+    """Interleaved float32 audio, shape ``(frames, channels)``."""
+
+    data: npt.NDArray[np.float32]
+    timestamp_ns: int
+    sample_rate: int
+    source: str = ""
+    flags: frozenset[str] = field(default_factory=frozenset)
+
+    @property
+    def frames(self) -> int:
+        return int(self.data.shape[0])
+
+    @property
+    def channels(self) -> int:
+        return int(self.data.shape[1])

capturekit-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: capturekit
+Version: 0.1.0
+Summary: Python screen, exclusive-window and audio capture/recording for Windows and Linux X11
+Author: capturekit contributors
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: imageio-ffmpeg>=0.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: ffmpeg
+Requires-Dist: imageio-ffmpeg>=0.5; extra == 'ffmpeg'
+Description-Content-Type: text/markdown
+
+# capturekit
+
+Python library for **monitor capture**, **exclusive window capture** (the
+window's own pixels, even when covered by other windows) and **audio capture**
+(microphone, system audio, *individual applications*), with synchronised
+recording to H.264 MKV/MP4 through FFmpeg and hardware encoders.
+
+* Windows 10/11 — DXGI Desktop Duplication, Windows Graphics Capture, WASAPI
+  (including per-process loopback). **Implemented and tested.**
+* Linux X11 / Xvfb (explicit display strings such as `":99"`) — MIT-SHM,
+  XComposite, PulseAudio protocol (per-application capture via monitor
+  streams). **Implemented and tested on Xvfb**; native desktops/PipeWire
+  untested (see [capabilities](docs/capabilities.md)).
+* Wayland-only sessions are detected and rejected; macOS is out of scope.
+
+Pure Python + ctypes (no compiled extension). Runtime dependency: `numpy`.
+
+## Install
+
+```
+pip install capturekit            # library
+pip install capturekit[ffmpeg]    # + bundled FFmpeg binary (imageio-ffmpeg)
+```
+Recording needs an FFmpeg executable: `PATH`, `CAPTUREKIT_FFMPEG`,
+`EncoderConfig(ffmpeg_path=...)`, or the `[ffmpeg]` extra.
+
+## Quick start
+
+```python
+import capturekit as ck
+
+print(ck.get_capabilities().summary())
+
+# One frame of the primary monitor (BGRA numpy array)
+img = ck.screenshot()
+
+# Exclusive capture of a window, cropped relative to its client area
+win = next(w for w in ck.list_windows() if "Notepad" in w.title)
+with ck.ScreenCapture(ck.WindowSource(win, client_area_only=True,
+                                      region=ck.Rect(0, 0, 400, 300))) as cap:
+    for frame in cap.frames(fps=30, max_frames=60):
+        process(frame.data)                       # (300, 400, 4) uint8
+
+# Record the window + only that application's audio + the microphone
+rec = ck.Recorder(
+    ck.WindowSource(win),
+    [ck.ProcessAudioSource.for_window(win), ck.MicrophoneSource()],
+    "notepad.mkv",
+    ck.RecordingConfig(fps=60, audio_mix=ck.AudioMixMode.BOTH),
+    on_error=print,
+)
+rec.start()
+...
+rec.pause(); rec.resume()
+result = rec.stop()
+print(result.stats.video)          # slots, new/duplicated/dropped frames, timings
+```
+
+More: [examples/](examples/) · [API guide](docs/guide/api.md).
+
+## Documentation
+
+| Topic | |
+| --- | --- |
+| What works where | [docs/capabilities.md](docs/capabilities.md) |
+| Windows requirements & behaviour | [docs/guide/windows.md](docs/guide/windows.md) |
+| Linux X11 / Xvfb | [docs/guide/linux.md](docs/guide/linux.md) |
+| Audio sources, process selection | [docs/guide/audio.md](docs/guide/audio.md) |
+| Encoders & hardware encoding | [docs/guide/encoding.md](docs/guide/encoding.md) |
+| Performance numbers & tuning | [docs/guide/performance.md](docs/guide/performance.md) |
+| Troubleshooting | [docs/guide/troubleshooting.md](docs/guide/troubleshooting.md) |
+| Architecture / decisions | [docs/architecture.md](docs/architecture.md), [docs/decisions.md](docs/decisions.md) |
+| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
+
+## Responsible use
+
+Recording starts only through explicit API calls; capturekit has no
+background, hidden or persistent recording features. Windows asking to be
+excluded from capture (display affinity) and protected content are respected,
+never bypassed. Windows draws its capture border unless you request otherwise
+and the OS permits it.
+
+## Status
+
+Alpha. Windows and Linux X11 backends are implemented and covered by
+integration tests that run on real hardware (Windows) and private Xvfb
+servers (Linux). See [docs/PROGRESS.md](docs/PROGRESS.md).

capturekit-0.1.0.dist-info/RECORD

@@ -0,0 +1,41 @@
+capturekit/__init__.py,sha256=Iuk2ziTdnweiM_32k2Ook_s1FDeVWRp3J4PaVeXcx8g,4374
+capturekit/_platform.py,sha256=sz5IMyxhGR_Jxx5BDcddCWh5dBIYIV85jZypKbjI68c,717
+capturekit/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+capturekit/_worker.py,sha256=IUQzfQgadmaXLte-JJBO9poXacjd0Eropt9TIVBSsfg,3839
+capturekit/capabilities.py,sha256=mckGANBvdL2DyqPqLBY-_oyBk2xNMBYVxhKuoIJybm8,2511
+capturekit/capture.py,sha256=m6MgmaiaSjHzAV3v8Hqo_yULQYSWMmisMsL1LhPeLSQ,4925
+capturekit/config.py,sha256=1el9fs3E--c9BE9cJFLe0X-K-Ll2kn0isjYI_3SYaWE,2821
+capturekit/errors.py,sha256=52rpRLBjLOJPNMD4mK5MrgyoLiaaEpqXJDVtOOR-Bbg,3210
+capturekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+capturekit/recording.py,sha256=KtlUunoQtSzW4T9UkllMP7qNShUczfR03CrwKLtPeOo,36693
+capturekit/sources.py,sha256=SSYDbYkW_gujwOrXCBHEIZgByGjsJholi21TWz-H6T0,3877
+capturekit/types.py,sha256=y_fzVmptwy3NeVfv7ezwOIg9Wb-EbLv6-mFEveV46tY,5717
+capturekit/_backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+capturekit/_backends/base.py,sha256=Rgn2QAcISsyCPL4q6rsUH_lx74QPMVdNJ2yxsSxsmz0,2322
+capturekit/_backends/linux/__init__.py,sha256=6JrAOfzfs9bx3w5R9cyLsXnCekdDQqcDK2Iml8uxiVc,55
+capturekit/_backends/linux/_xlib.py,sha256=wz46UKohcwjg4fhHaaazDmbL4ckJ-G8aYsMNoSgRAms,20477
+capturekit/_backends/linux/api.py,sha256=XZgMu8Z4yDomrdGE-ut79RD6uNoaGW8KaZpcqGzdmuc,5246
+capturekit/_backends/linux/pulse.py,sha256=7sZ4nzto2XSyrIobKyzJ7qkdLZUNp52WKKCU37-cgxU,16713
+capturekit/_backends/linux/x11.py,sha256=BrAaruKgtHSLJGSiZRXuw27h2xaNjptXDSs1u7gBgQs,27526
+capturekit/_backends/windows/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+capturekit/_backends/windows/_com.py,sha256=J6o1EhdHTyhWp0UT56ofkglNiBnlnFKjhb_3_SyEIsc,11984
+capturekit/_backends/windows/_d3d11.py,sha256=q6aQhLDoUepbP-hc2ltUSta9nLuiX-ai4n_0Qs8kcrU,10432
+capturekit/_backends/windows/_win32.py,sha256=ALS2PY2tiOD4mQO7WX0uV1oQUkNdcOnglXoJHPLxF3g,14258
+capturekit/_backends/windows/_winrt.py,sha256=J-UyZfsq03-_1Gz1_9Wf0h85blec0fRtZz-wYDD8uJE,5387
+capturekit/_backends/windows/api.py,sha256=MfWkSpyCDtZnPHX_UX5D21cHLlIfoSchshSdhdLM54Y,7190
+capturekit/_backends/windows/cursor.py,sha256=PEbWhYCK-anGL4mC0AxnHykdNvUPycFxWJJOhRzcdQM,2579
+capturekit/_backends/windows/dxgi_duplication.py,sha256=XidQ0ra7ClOSGwq1w9eMt4lOSE2hzLE5EuVu015S0G4,12711
+capturekit/_backends/windows/wasapi.py,sha256=Y2f-mwZlYUmaQHFX_S5CIEyU2cDc1I0Vk5wxFj1-oQ8,20874
+capturekit/_backends/windows/wgc.py,sha256=ivjSW6S5IU8kcWsPAKHGVRfS8WQkgPTgbPin6dzQG9M,16566
+capturekit/_pipeline/__init__.py,sha256=hAvywCElbVfWzkksc5MJ43sqd8TE4ET68ZusDeKep4I,77
+capturekit/_pipeline/aligner.py,sha256=bqV9p-PTUt6uHugVxUG6aFLzJv-k5WFhSN_YiX5CSgs,6106
+capturekit/_pipeline/clock.py,sha256=4yzZo7uDKXRpOAA9UYrdxKRa70ewxwUdSSYECEG_tpk,1480
+capturekit/_pipeline/frame_queue.py,sha256=2ydgb51QKwfYC45tP6Lv7n6Koi0tfeJaUcRczYAsVIo,3606
+capturekit/_pipeline/mixer.py,sha256=e4HCScOy-YMCpnofwJiEcBrqSMumhzbY02oowuan8VE,2510
+capturekit/_pipeline/timeline.py,sha256=Exc8VPdHtGy-VFx2fOjSacN8KbjX72FWC7WstdO-Dvg,4840
+capturekit/encoding/__init__.py,sha256=HHISkvMsrPdVXgsfl7RLsXSDcjyaF9ijmUIF3WgG0m8,234
+capturekit/encoding/ffmpeg.py,sha256=whLjWrTPKh0WJU3Hw980DbKI0pj8eCCNWkMGhEGUzm8,12498
+capturekit/encoding/pipes.py,sha256=99YvLPuddpUaHiPScUKA_aLMoLjlG_nKTb-VqfHZIkI,7334
+capturekit-0.1.0.dist-info/METADATA,sha256=qMsdHurNeIvWTdw3UvL8AvQF2UF7u4V-gGd6gi2RiBY,4534
+capturekit-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+capturekit-0.1.0.dist-info/RECORD,,

capturekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any