I needed cross-platform screen capture in Rust, so I built pinray

So I needed screen capture in Rust. Simple enough, right?

Wrong.

I went looking for a crate and found three options: scap, xcap, and waycap-rs. Each one had problems that drove me nuts.

So I open sourced pinray, a Rust crate for cross-platform screen and system audio capture.

The goal is simple: provide a single API over each platform's native capture APIs without depending on ffmpeg or another large capture framework. pinray focuses on capture only. It gives you raw video and audio frames with the metadata needed to build your own recording, streaming, or processing pipeline.

Repository:

xcap has the best cross-platform story, but its frame type is a joke: just width, height, and raw bytes. No stride. No pixel format. No timestamps. You're flying blind.

Its Linux engine is also one giant struct with #[cfg] fields scattered throughout, which makes extending it painful.

What pinray does

pinray is a capture infrastructure crate.

It talks directly to each operating system's native capture APIs and delivers raw frames together with their metadata, including timestamps, pixel format, stride, sequence numbers, and dropped-frame notifications.

Encoding is intentionally out of scope. The output can be sent to ffmpeg, WebRTC, wgpu, the image crate, or any custom processing pipeline.

The current native backends are:

No wrapper crates are used around these platform APIs.

Basic usage

Capturing the primary display together with system audio looks like this:

use std::time::Duration;

use pinray::{AudioCapture, CaptureEvent, CaptureSession, SourceId, VideoCaptureTarget};



fn main() -> Result<(), Box<dyn std::error::Error>> {

    let mut session = CaptureSession::builder()

        .video_target(VideoCaptureTarget::Display(SourceId::new("auto")))

        .audio(AudioCapture::SystemMix)

        .build()?;



    session.start()?;



    loop {

        match session.next_event(Some(Duration::from_secs(5)))? {

            CaptureEvent::Video(frame) => {

                println!("{}x{}", frame.width, frame.height);

            }

            CaptureEvent::Audio(frame) => {

                println!("{} Hz", frame.sample_rate);

            }

            CaptureEvent::Gap(gap) => {

                println!("Dropped frames: {:?}", gap.reason);

            }

            CaptureEvent::End => break,

        }

    }



    session.stop()?;

    Ok(())

}

The same API works across Linux, macOS, and Windows.

On Linux, Auto selects either the Wayland or X11 backend. On Windows it prefers DXGI Desktop Duplication and falls back to Windows Graphics Capture when appropriate. backend_info() can be used to inspect which backend was selected.

Window enumeration follows the same API:

use pinray::{CaptureSource, CaptureSession};



let sources = pinray::enumerate_sources()?;



let window = sources.iter().find_map(|source| match source {

    CaptureSource::Window(window) if window.title.contains("Firefox") => {

        Some(window.id.clone())

    }

    _ => None,

});

Audio-only capture is equally straightforward:

let mut session = CaptureSession::builder()

    .audio(AudioCapture::SystemMix)

    .build()?;

Design decisions

The most challenging part was not implementing screen capture for a single platform. It was exposing a consistent API over several fundamentally different capture systems.

Different capture models

Each platform delivers frames differently.

ScreenCaptureKit and Windows Graphics Capture continuously stream frames. DXGI Desktop Duplication only produces new frames when the desktop changes, so an idle desktop naturally results in timeouts. X11 has no event-driven capture API, so the backend polls at the requested frame rate.

Consistent timestamps

Every platform uses a different clock.

Windows exposes QPC ticks, macOS uses host time, and PipeWire exposes different timing information. pinray normalizes everything to monotonic nanosecond timestamps so audio and video from the same capture session share a common timeline.

Wayland support

Wayland intentionally requires user approval through the desktop portal.

Instead of trying to work around that, pinray embraces the portal workflow. SourceId::new("auto") opens the native picker, while restore tokens allow subsequent sessions to reuse previously granted permissions.

Native pixel formats

All current backends produce BGRA frames. If an application requests RGBA, pinray performs the conversion explicitly. There are no hidden format conversions.

Frame drops

Dropped frames are exposed as explicit Gap events, and every frame carries a sequence number. Applications that synchronize audio and video need this information, so it is surfaced directly instead of being hidden internally.

Getting started

cargo add pinray

Linux requires libpipewire-0.3-dev and clang during compilation. No additional dependencies are required on macOS or Windows.

• Repository:
  


• Crate:
  
  
  

  If you try pinray and run into an issue, feel free to open one on GitHub. Including the output of session.backend_info() is especially helpful since backend selection can differ between systems.

  Vollständiger Original-Bericht

  Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

  ↗ Original-Artikel auf dev.to lesen