lexian-pyscap 0.1.2b5

A Rust library for high-quality screen capture that leverages native OS APIs for optimal performance!

1. macOS: ScreenCaptureKit
2. Windows: Windows.Graphics.Capture
3. Linux: Pipewire

Features

1. Cross-platform across Windows, Mac and Linux!
2. Checks for support and recording permissions.
3. Query list of captureable targets (displays and windows).
4. Exclude certain targets from being captured.

Contributing

We found most of Rust's tooling around screen capture either very outdated, non-performant or platform-specific. This project is our attempt to change that. Contributions, PRs and Issues are most welcome!

If you want to contribute code, here's a quick primer:

1. Clone the repo and run it with cargo run.
2. Explore the API and library code in lib.rs.
3. Platform-specific code lives in the win, mac and linux modules.
4. The main.rs is a small program that "consumes" the library, for easy testing.

Usage

use scap::{
    capturer::{Point, Area, Size, Capturer, Options},
    frame::Frame,
};

fn main() {
    // Check if the platform is supported
    if !scap::is_supported() {
        println!("❌ Platform not supported");
        return;
    }

    // Check if we have permission to capture screen
    // If we don't, request it.
    if !scap::has_permission() {
        println!("❌ Permission not granted. Requesting permission...");
        if !scap::request_permission() {
            println!("❌ Permission denied");
            return;
        }
    }

    // Get recording targets
    let targets = scap::get_all_targets();
    println!("Targets: {:?}", targets);

    // All your displays and windows are targets
    // You can filter this and capture the one you need.

    // Create Options
    let options = Options {
        fps: 60,
        target: None, // None captures the primary display
        show_cursor: true,
        show_highlight: true,
        excluded_targets: None,
        output_type: scap::frame::FrameType::BGRAFrame,
        output_resolution: scap::capturer::Resolution::_720p,
        crop_area: Some(Area {
            origin: Point { x: 0.0, y: 0.0 },
            size: Size {
                width: 2000.0,
                height: 1000.0,
            },
        }),
        ..Default::default()
    };

    // Create Capturer
    let mut capturer = Capturer::build(options).unwrap();

    // Start Capture
    capturer.start_capture();

    let mut input = String::new();
    std::io::stdin().read_line(&mut input).unwrap();

    // Stop Capture
    capturer.stop_capture();
}

Python bindings

The optional Python extension is built with maturin and returns captured data as owned NumPy arrays. Install a development build with:

python -m pip install maturin numpy
maturin develop --features python

Example:

import scap

if not scap.has_permission():
    if not scap.request_permission():
        raise RuntimeError("screen capture permission was denied")

options = scap.CaptureOptions(
    fps=30,
    output_type="bgra",
    output_resolution="720p",
)
capturer = scap.Capturer(options)
capturer.start()
try:
    frame = capturer.next_frame()
    print(frame.data.shape, frame.data.dtype, frame.format)
finally:
    capturer.stop()

Video arrays currently contain the native packed byte order reported by frame.format (rgb, rgbx, xbgr, bgrx, bgr0, or bgra) and have shape (height, width, channels). Audio arrays contain the owned raw bytes as a one-dimensional uint8 NumPy array; AudioFrameInfo exposes the sample format, channel count, sample rate, sample count, and planar layout.

The extension is feature-gated, so normal Rust builds are unchanged. macOS requires Screen Recording permission.

Linux capture backends

On Linux, PyScap prefers PipeWire through the XDG Desktop Portal. This remains the recommended backend for normal Wayland desktop screen sharing because the portal provides user-controlled source selection. Set SCAP_BACKEND=pipewire to require it.

For X11 desktops and headless virtual displays, set SCAP_BACKEND=x11. The X11 backend connects to the server named by DISPLAY and captures that screen's root window. It uses MIT-SHM when the X server permits it and falls back to the core X11 GetImage request otherwise. X11 capture is display-level; it does not provide the portal's interactive window or monitor picker.

When captures_audio=True, Linux records stereo 48 kHz signed 16-bit PCM from the default PulseAudio/PipeWire-Pulse output monitor. Set SCAP_AUDIO_SOURCE to override the source name. The PulseAudio client libraries and a running audio server must be available; headless systems normally need a null sink for Chromium to produce capturable audio.

For example, start Xvfb and capture its 1920x1080 screen:

Xvfb :99 -screen 0 1920x1080x24 &
DISPLAY=:99 SCAP_BACKEND=x11 python capture.py

An explicit backend is never silently replaced by another backend. With no SCAP_BACKEND, PyScap probes PipeWire and the ScreenCast portal first, then falls back to X11 when DISPLAY points to a usable X server.

License

The code in this repository is open-sourced under the MIT license, though it may be relying on dependencies that are licensed differently. Please consult their documentation for exact terms.

Contributors

Pranav Joglekar 💻

Siddharth 💻

Rohan Punjani 💻

NiiightmareXD 💻

MAlba124 💻

Anubhav Singhal 💻

Vasu Sharma 💻

Credits

This project builds on top of the fabulous work done by:

• @MAlba124 for Linux support via Pipewire
• @svtlabs for screencapturekit-rs
• @NiiightmareXD for windows-capture