capturekit 0.1.0__py3-none-any.whl

capturekit/__init__.py

@@ -0,0 +1,164 @@
+"""capturekit — monitor, exclusive-window and audio capture for Windows and Linux X11.
+
+Quick start::
+
+    import capturekit as ck
+
+    print(ck.get_capabilities().summary())
+    win = next(w for w in ck.list_windows() if "Notepad" in w.title)
+    with ck.ScreenCapture(ck.WindowSource(win)) as cap:
+        frame = cap.grab()                      # BGRA numpy array in frame.data
+
+    rec = ck.Recorder(ck.WindowSource(win), [ck.ProcessAudioSource.for_window(win)],
+                      "notepad.mkv", ck.RecordingConfig(fps=30))
+    rec.start(); ...; rec.stop()
+"""
+
+from __future__ import annotations
+
+from . import _platform
+from ._pipeline.clock import now_ns
+from ._version import __version__
+from .capabilities import Capabilities, Capability, Support
+from .capture import ScreenCapture, screenshot
+from .config import AudioMixMode, Container, EncoderConfig, RecordingConfig, TargetLostPolicy
+from .errors import (
+    AccessDeniedError,
+    AudioDeviceDisconnectedError,
+    AudioDeviceError,
+    CapabilityUnavailableError,
+    CaptureError,
+    CaptureTimeoutError,
+    EncoderError,
+    EncoderNotAvailableError,
+    InvalidRegionError,
+    NativeError,
+    RecorderStateError,
+    TargetLostError,
+    TargetNotFoundError,
+    UnsupportedDisplayServerError,
+    UnsupportedPlatformError,
+    WindowClosedError,
+)
+from .recording import (
+    AudioTrackStats,
+    Recorder,
+    RecorderState,
+    RecordingResult,
+    RecordingStats,
+    VideoStats,
+)
+from .sources import (
+    MicrophoneSource,
+    MonitorBackend,
+    MonitorSource,
+    ProcessAudioSource,
+    SystemAudioSource,
+    WindowSource,
+)
+from .types import (
+    AudioChunk,
+    AudioDevice,
+    AudioDeviceKind,
+    AudioSession,
+    Frame,
+    Monitor,
+    PixelFormat,
+    Rect,
+    Window,
+)
+
+
+def list_monitors(display: str | None = None) -> list[Monitor]:
+    """Enumerate monitors (``display`` selects an X server on Linux, e.g. ``":99"``)."""
+    result: list[Monitor] = _platform.backend().list_monitors(display)
+    return result
+
+
+def list_windows(display: str | None = None, *, include_untitled: bool = False) -> list[Window]:
+    """Enumerate capturable top-level windows."""
+    result: list[Window] = _platform.backend().list_windows(display, include_untitled)
+    return result
+
+
+def get_window(handle: int, display: str | None = None) -> Window:
+    """Describe the window with native ``handle`` (raises TargetNotFoundError)."""
+    result: Window = _platform.backend().get_window(handle, display)
+    return result
+
+
+def list_audio_devices() -> list[AudioDevice]:
+    """Enumerate audio input and output devices."""
+    result: list[AudioDevice] = _platform.backend().list_audio_devices()
+    return result
+
+
+def list_audio_sessions() -> list[AudioSession]:
+    """Enumerate application audio sessions/streams with owning process IDs."""
+    result: list[AudioSession] = _platform.backend().list_audio_sessions()
+    return result
+
+
+def get_capabilities(display: str | None = None) -> Capabilities:
+    """Describe what this machine/display server supports."""
+    result: Capabilities = _platform.backend().capabilities(display)
+    return result
+
+
+__all__ = [
+    "AccessDeniedError",
+    "AudioChunk",
+    "AudioDevice",
+    "AudioDeviceDisconnectedError",
+    "AudioDeviceError",
+    "AudioDeviceKind",
+    "AudioMixMode",
+    "AudioSession",
+    "AudioTrackStats",
+    "Capabilities",
+    "Capability",
+    "CapabilityUnavailableError",
+    "CaptureError",
+    "CaptureTimeoutError",
+    "Container",
+    "EncoderConfig",
+    "EncoderError",
+    "EncoderNotAvailableError",
+    "Frame",
+    "InvalidRegionError",
+    "MicrophoneSource",
+    "Monitor",
+    "MonitorBackend",
+    "MonitorSource",
+    "NativeError",
+    "PixelFormat",
+    "ProcessAudioSource",
+    "Recorder",
+    "RecorderState",
+    "RecorderStateError",
+    "RecordingConfig",
+    "RecordingResult",
+    "RecordingStats",
+    "Rect",
+    "ScreenCapture",
+    "Support",
+    "SystemAudioSource",
+    "TargetLostError",
+    "TargetLostPolicy",
+    "TargetNotFoundError",
+    "UnsupportedDisplayServerError",
+    "UnsupportedPlatformError",
+    "VideoStats",
+    "Window",
+    "WindowClosedError",
+    "WindowSource",
+    "__version__",
+    "get_capabilities",
+    "get_window",
+    "list_audio_devices",
+    "list_audio_sessions",
+    "list_monitors",
+    "list_windows",
+    "now_ns",
+    "screenshot",
+]

capturekit/_backends/base.py

@@ -0,0 +1,89 @@
+"""Internal backend protocols (not public API)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import numpy as np
+import numpy.typing as npt
+
+from ..types import Rect
+
+Buffer = npt.NDArray[np.uint8]
+Samples = npt.NDArray[np.float32]
+
+
+@dataclass(slots=True)
+class AcquiredFrame:
+    data: Buffer
+    timestamp_ns: int
+    content_size: tuple[int, int]
+
+
+@dataclass(slots=True)
+class VideoBackendInfo:
+    name: str
+    #: Output size when ``acquire(out=None)`` is used right after start.
+    initial_size: tuple[int, int]
+    details: dict[str, object] = field(default_factory=dict)
+
+
+class VideoBackend(Protocol):
+    """Pull-model video source. All methods are called from one thread."""
+
+    info: VideoBackendInfo
+
+    def start(self) -> None: ...
+
+    def acquire(self, out: Buffer | None, timeout_s: float) -> AcquiredFrame | None:
+        """Return the newest frame since the last call, or ``None``.
+
+        With ``out`` the frame is written at its top-left corner; the rest of
+        ``out`` is cleared. Raises ``TargetLostError`` when the target is gone.
+        """
+        ...
+
+    def close(self) -> None: ...
+
+
+@dataclass(slots=True)
+class AudioPacket:
+    data: Samples  # (frames, channels) float32
+    timestamp_ns: int
+    discontinuity: bool = False
+
+
+AudioCallback = Callable[[AudioPacket], None]
+
+
+class AudioBackend(Protocol):
+    """Push-model audio source running its own capture thread."""
+
+    name: str
+    sample_rate: int
+    channels: int
+
+    def start(
+        self, on_packet: AudioCallback, on_error: Callable[[BaseException], None]
+    ) -> None: ...
+
+    def stop(self) -> None: ...
+
+
+def blit_clear(out: Buffer, copied_w: int, copied_h: int) -> None:
+    """Clear the parts of ``out`` not covered by a top-left copy."""
+    h, w = out.shape[0], out.shape[1]
+    if copied_h < h:
+        out[copied_h:, :] = 0
+    if copied_w < w:
+        out[: min(copied_h, h), copied_w:] = 0
+
+
+def crop_box(base: Rect, region: Rect | None) -> Rect:
+    """Region (relative to ``base``) translated into absolute coordinates and
+    clipped to ``base``. Without a region the whole base is used."""
+    if region is None:
+        return base
+    return region.translate(base.x, base.y).intersect(base)

capturekit/_backends/linux/__init__.py

@@ -0,0 +1 @@
+"""Linux X11/Xvfb and PulseAudio/PipeWire backends."""