💼 Looking for a hosted desktop recording API? Check out Recall.ai — an API for recording video-conferencing services, in-person meetings, and more.

https://github.com/user-attachments/assets/8a272c48-7ec3-4132-9111-4602b4fa991d

Highlights

• 🎥 Screen, window, and app capture with a clean builder-pattern API
• 🔊 System audio + microphone capture (macOS 13.0+ / 15.0+)
• ⚡ Real-time, zero-copy frame delivery via IOSurface / Metal
• 🔄 Async support that works with any executor (Tokio, async-std, smol, …) — fully waker-based, never blocks your runtime
• 📸 Screenshots + direct-to-file recording (macOS 14.0+ / 15.0+)
• 🖱️ System content picker UI (macOS 14.0+)
• 🛡️ Memory safe — proper retain/release, leak-tested
• 📦 Minimal dependencies — only the thin apple-cf / apple-metal binding crates (plus trait-only futures-core when the async feature is on; no heavy third-party runtime deps)

Table of Contents

• Install · Quick Start · Recipes
• Feature Flags · Examples · Documentation
• Requirements & Permissions · Performance
• Troubleshooting · Migration · Contributing

Install

[dependencies]
screencapturekit = "11"

Opt-in features (additive):

macos_* features are cumulative — enabling macos_15_0 automatically enables every earlier version. Pick the highest version your minimum-supported macOS will satisfy:

screencapturekit = { version = "11", features = ["async", "macos_15_0"] }

Upgrading a major version? See docs/MIGRATION.md for a per-version guide. Releases 3.0–6.0 consolidated the Core Graphics / Core Media foundation types onto the shared apple-cf crate and 7.0 hardens the FFI boundary; the only likely source change across that line is 5.0's nested CGRect layout (rect.origin.x / rect.size.width). 9.0 tightens stream and picker lifecycle handling; 10.0 finalizes the audio, Metal, picker, and shared Core Media/Core Video safety contracts described below; 11.0 turns panics and silently ignored inputs into Results.

Quick Start

A minimal screen capture in ~25 lines. Everything else builds on these four steps: (1) list shareable content, (2) build a content filter, (3) configure the stream, (4) add an output handler and start.

use screencapturekit::prelude::*;

struct Handler;
impl SCStreamOutputTrait for Handler {
    fn did_output_sample_buffer(&self, sample: CMSampleBuffer, _: SCStreamOutputType) {
        println!("📹 frame @ {:?}", sample.presentation_timestamp());
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = SCShareableContent::get()?;
    let display = &content.displays()[0];

    let filter = SCContentFilter::create()
        .with_display(display)
        .with_excluding_windows(&[])
        .build()?;

    let config = SCStreamConfiguration::new()
        .with_width(1920)
        .with_height(1080)
        .with_pixel_format(PixelFormat::BGRA);

    let mut stream = SCStream::new(&filter, &config)?;
    stream.add_output_handler(Handler, SCStreamOutputType::Screen)?;
    stream.start_capture()?;

    std::thread::sleep(std::time::Duration::from_secs(5));
    stream.stop_capture()?;
    Ok(())
}

Output / delegate handlers must be Send + Sync — Apple's dispatch queues may invoke them concurrently from arbitrary threads.

Permission required — see Requirements & Permissions. Run it: cargo run --example 01_basic_capture.

Recipes

Short snippets for the most common follow-on tasks. Every recipe is a runnable example in examples/ — see the Examples table.

use screencapturekit::prelude::*;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
let content = SCShareableContent::get()?;
let window = content.windows().into_iter()
    .find(|w| w.title().as_deref() == Some("Safari"))
    .ok_or("Safari window not found")?;

let filter = SCContentFilter::create().with_window(&window).build()?;
let config = SCStreamConfiguration::new()
    .with_captures_audio(true)
    .with_sample_rate(48_000)
    .with_channel_count(2);

let mut stream = SCStream::new(&filter, &config)?;
// stream.add_output_handler(...) for Screen and/or Audio
stream.start_capture()?;
# Ok(()) }

# use screencapturekit::prelude::*;
# fn example(stream: &mut SCStream) {
stream.add_output_handler(
    |sample: CMSampleBuffer, _of_type: SCStreamOutputType| {
        println!("📹 frame @ {:?}", sample.presentation_timestamp());
    },
    SCStreamOutputType::Screen,
).expect("register output handler");
# }

use screencapturekit::async_api::{AsyncSCShareableContent, AsyncSCStream};
use screencapturekit::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = AsyncSCShareableContent::get().await?;
    let display = &content.displays()[0];

    let filter = SCContentFilter::create()
        .with_display(display).with_excluding_windows(&[]).build()?;
    let config = SCStreamConfiguration::new().with_width(1920).with_height(1080);

    // 30-frame ring buffer; oldest frames are dropped if the consumer can't keep up.
    let stream = AsyncSCStream::new(&filter, &config, 30, SCStreamOutputType::Screen)?;
    // start/stop/update are real futures — awaiting parks the task via its
    // Waker and never blocks the executor thread.
    stream.start_capture().await?;

    while let Some(_frame) = stream.next().await {
        // process frame
        # break;
    }

    stream.stop_capture().await?;
    // Distinguish a normal end from an error stop (display gone, perms revoked, …):
    if let Some(err) = stream.take_error() {
        eprintln!("stream stopped with error: {err}");
    }
    Ok(())
}

use futures_util::StreamExt;
let first_30: Vec<_> = stream.frames().take(30).collect().await;

use screencapturekit::async_api::{AsyncSCShareableContent, AsyncSCStream};
use screencapturekit::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = AsyncSCShareableContent::get().await?;
    let display = &content.displays()[0];
    let filter = SCContentFilter::create()
        .with_display(display).with_excluding_windows(&[]).build()?;
    // Enable audio in the configuration …
    let config = SCStreamConfiguration::new()
        .with_width(1920).with_height(1080)
        .with_captures_audio(true);

    let mut stream = AsyncSCStream::new(&filter, &config, 32, SCStreamOutputType::Screen)?;
    // … then register audio as a second output type on the SAME stream.
    stream.add_output_type(SCStreamOutputType::Audio)?;
    stream.start_capture().await?;

    // `next_typed()` yields each sample tagged with its output type.
    while let Some((_sample, kind)) = stream.next_typed().await {
        match kind {
            SCStreamOutputType::Screen => { /* video frame */ }
            SCStreamOutputType::Audio  => { /* system audio */ }
            _ => {}
        }
        # break;
    }

    stream.stop_capture().await?;
    Ok(())
}

# #[cfg(feature = "macos_14_0")]
# fn example(
#     filter: &screencapturekit::stream::content_filter::SCContentFilter,
#     config: &screencapturekit::stream::configuration::SCStreamConfiguration,
# ) -> Result<(), Box<dyn std::error::Error>> {
use screencapturekit::screenshot_manager::{CGImageExt, SCScreenshotManager};

let img = SCScreenshotManager::capture_image(filter, config)?;
let pixels = img.bgra_data()?;            // native BGRA — skips R↔B swap
// For sustained loops, reuse a buffer:
// img.bgra_data_into(&mut buffer)?;
# Ok(()) }

use screencapturekit::content_sharing_picker::*;
use screencapturekit::prelude::*;

let config = SCContentSharingPickerConfiguration::new()?;
SCContentSharingPicker::show(&config, |outcome| match outcome {
    SCPickerOutcome::Picked(result) => {
        let (w, h) = result.pixel_size();
        let filter = result.filter();
        // Use `filter` with SCStream as in the Quick Start.
        let _ = (w, h, filter);
    }
    SCPickerOutcome::Cancelled => println!("user cancelled"),
    SCPickerOutcome::Error(e)  => eprintln!("picker error: {e}"),
});

let subscription = SCContentSharingPicker::add_observer(|event| match event {
    SCPickerEvent::Updated { result, stream } => {
        let filter = result.filter();
        match stream {
            Some(identity) => println!("update for {identity:?}: {filter:?}"),
            None => println!("new selection: {filter:?}"),
        }
    }
    SCPickerEvent::Cancelled { stream } => println!("cancelled: {stream:?}"),
    SCPickerEvent::Failed(error) => eprintln!("picker error: {error}"),
}).expect("register picker observer");
SCContentSharingPicker::present().expect("present picker");
drop(subscription);

use screencapturekit::prelude::*;
use screencapturekit::dispatch_queue::{DispatchQueue, DispatchQoS};
# fn example(stream: &mut SCStream) {
let queue = DispatchQueue::new("com.myapp.capture", DispatchQoS::UserInteractive);
stream.add_output_handler_with_queue(
    |_sample, _of_type| { /* runs on `queue` */ },
    SCStreamOutputType::Screen,
    Some(&queue),
).expect("register output handler");
# }

use screencapturekit::prelude::*;
struct H;
impl SCStreamOutputTrait for H {
    fn did_output_sample_buffer(&self, sample: CMSampleBuffer, _: SCStreamOutputType) {
        if let Some(pb) = sample.pixel_buffer() {
            if let Some(surface) = pb.io_surface() {
                let _ = (surface.width(), surface.height());
                // Wrap as `MTLTexture` (see examples 17/18) — no copy.
            }
        }
    }
}

Examples

23 runnable examples cover every API surface. The full table with feature requirements lives in examples/README.md. A few favourites to start with:

cargo run --example 01_basic_capture
cargo run --example 10_recording_output --features macos_15_0
cargo run --example 08_async            --features "async,macos_14_0"

Feature Flags

See the full feature table under Install. One small example of gating version-specific options:

let mut config = SCStreamConfiguration::new().with_width(1920).with_height(1080);

#[cfg(feature = "macos_14_2")]
{
    config.set_ignores_shadows_single_window(true)?;
    config.set_includes_child_windows(false)?;
}

Documentation

Requirements & Permissions

• macOS 13.0+ (Ventura). Apple's ScreenCaptureKit itself starts at 12.3, but this crate's Swift bridge is built with a 13.0 deployment target and uses the 13.0 audio APIs unconditionally, so 13.0 is the real floor.
• 14.0+ — picker / screenshots · 15.0+ — recording / HDR / mic · 26.0+ — advanced screenshots
• Xcode Command Line Tools at build time (xcode-select --install)

Screen capture always requires user permission. To grant it:

1. System Settings → Privacy & Security → Screen Recording
2. Enable your binary (during development this is usually your terminal or IDE)
3. Restart the app

For distribution, add a purpose string to Info.plist — the user-facing TCC prompt requires it and the app will be terminated without one:

<key>NSScreenCaptureUsageDescription</key>
<string>Capture your screen so the app can …</string>

ScreenCaptureKit is purely TCC-gated: there is no code-signing entitlement that grants screen capture access. Capture is allowed solely when the user enables your binary under System Settings → Privacy & Security → Screen & System Audio Recording.

There is no com.apple.security.screen-capture entitlement. That key isn't part of Apple's security-entitlements reference; the only com.apple.security.device.* keys are camera, microphone, audio-input, usb, and bluetooth. The two real screen-capture entitlements (com.apple.developer.screen-capture.include-passthrough and com.apple.developer.protected-content) are Enterprise / visionOS managed entitlements and don't apply to ScreenCaptureKit on macOS.

Performance

Full capture (60 fps + 48 kHz stereo) costs ~1.9% of one core end-to-end on Apple Silicon — the binding itself is below the noise floor of a 4 kHz sampling profiler; nearly all CPU lives in Apple's SkyLight / libdispatch / libxpc pipeline.

Hot-path tips:

• Prefer BGRA to skip the per-pixel R↔B swap when uploading to Metal / wgpu / ffmpeg (CGImageExt::bgra_data is ~5% faster than rgba_data).
• Reuse a Vec<u8> across screenshots with the *_data_into variants (saves a ~33 MB allocation per 4K frame — new in 2.1).
• When iterating many windows / displays / apps, use the batched SCShareableContent::snapshot() API — collapses 1 + N + 6N FFI calls into one round-trip per category (~2× faster on a typical desktop).
• Read every SCStreamFrameInfo attachment in one cast via CMSampleBuffer::frame_info().

use screencapturekit::prelude::*;
use screencapturekit::shareable_content::ContentSnapshot;
# fn example() -> Result<(), Box<dyn std::error::Error>> {
let content = SCShareableContent::get()?;
let ContentSnapshot { displays, windows, applications, truncation, .. } =
    content.snapshot().ok_or("snapshot failed")?;
for w in &windows {
    let app = w.owning_app_index.and_then(|i| applications.get(i));
    println!("{} - {}", app.map(|a| &*a.application_name).unwrap_or(""),
             w.title.as_deref().unwrap_or(""));
}
# let _ = (displays, truncation);
# Ok(()) }

Run benchmarks on your hardware:

cargo bench
cargo bench --bench hotspots --features macos_14_0

See docs/BENCHMARKS.md for methodology, throughput numbers at various resolutions, and tuning guidance.

Troubleshooting

Migration

Upgrading? See docs/MIGRATION.md for the full guide, including a section for every major version bump.

Highlights by major version:

• 2.0 — output / delegate traits (and closure overloads) now require Send + Sync; PixelFormat and SCStreamErrorCode became #[non_exhaustive]; PixelFormat gained Unknown(FourCharCode); every macos_* Cargo feature now propagates to the Swift bridge build.
• 3.0 — foundation types (Core Graphics / Core Media / IOSurface / Core Video) moved onto the shared apple-cf / apple-metal crates as re-exports; ScreenCaptureKit-specific CMSampleBuffer accessors moved to the CMSampleBufferExt / CMSampleBufferSCExt extension traits (both in the prelude).
• 4.0 — ScreenshotManager::capture_image returns apple_cf::cg::CGImage and screencapturekit::cm::CMTime is an apple-cf re-export (drop any cross-crate conversions).
• 5.0 — adopts apple-cf 0.8's nested CGRect layout: use rect.origin.x / rect.size.width instead of flat rect.x / rect.width.
• 6.0 — CMSampleTimingInfo and CMClock are now re-exported from apple-cf as well.
• 7.0 — no source changes for typical users. FFI-hardening release that adds strided pixel-render helpers (CGImageExt::rgba_data_into_strided / bgra_data_into_strided) plus a locked IOSurface CPU view, and relaxes the AudioBufferRef::data() slice lifetime so the returned slice is tied to the wrapped buffer.
• 8.0 — AsyncSCStream::{start_capture, stop_capture, update_configuration, update_content_filter} now return a waker-based future instead of blocking — add .await (e.g. stream.start_capture().await?). The stream engine now reports stops only through SCStreamDelegateTrait::did_stop_with_error (the redundant stream_did_stop is deprecated). New: AsyncSCStream::{take_error, add_output_type, next_typed, try_next_typed} for error visibility and audio+video on one stream. The synchronous SCStream API is unchanged.
• 9.0 — memory-safety and lifecycle hardening. SCScreenshotOutput::file_url() -> Option<String> became file_path() -> Option<PathBuf>, and SCScreenshotConfiguration::with_file_path takes impl AsRef<Path> (&str still works). Recording codecs and file types are open, string-backed identifiers rather than integer enums, and recording delegates now require Sync. SCContentFilter is immutable once built: the nonfunctional content-rect setters are gone (crop with SCStreamConfiguration::with_source_rect) and includeMenuBar is set while building via SCContentFilterBuilder::with_include_menu_bar. AudioBuffer's fields are private, with owner-tied mutable bytes behind unsafe AudioBufferList::data_mut, and MetalDevice::as_apple_metal hands out a borrow instead of a second owner. SCShareableContent::current_process returns SCError::FeatureNotAvailable below macOS 14.4 instead of quietly falling back to system-wide content, and SCStream::update_configuration now requires the macos_14_0 feature. Build-SDK stub mode was removed. New: repeating picker observers (SCContentSharingPicker::add_observer) so allows_changing_selected_content actually delivers re-selections.
• 10.0 — audio sample mutation moves to owner-tied unsafe views; Metal buffer uploads and command/encoder lifecycle calls become checked and fallible; repeating picker events preserve optional stream identity; picker configuration is main-thread-only and fallible; shared Core Media/Core Video adoption and byte-view APIs use the finalized apple-cf safety contracts.
• 11.0 — stream and configuration constructors, SCContentFilterBuilder::build, string setters, output-handler registration and picker operations return a Result instead of panicking, returning a bare None, or ignoring invalid input, and their try_* twins are gone. The cm audio types come from apple-cf 0.11, configurations are copied when handed to ScreenCaptureKit, and the minimum Rust version is 1.82.

If you only use the prelude / screencapturekit::{cg, cm} types, the 4.0–7.0 upgrades are typically just the 5.0 CGRect field-access change. 8.0 affects you if you use the async API; 9.0 affects you if you write screenshots to disk, configure recording outputs, crop through the content filter, read AudioBuffer fields, or call SCShareableContent::current_process. 10.0 affects audio-buffer mutation, Metal upload/encoding paths, repeating picker events/configuration, and direct apple-cf raw or locked-byte access. 11.0 affects almost every caller: add ? where constructors, builders and registration calls now return a Result.

Contributing

Contributions welcome! Please:

1. Follow existing patterns — builder pattern with ::new() and .with_*()
2. Add tests for new functionality
3. cargo fmt && cargo clippy --all-features -- -D warnings && cargo test. A plain cargo test never captures the screen: the live capture tests run only with SCREENCAPTUREKIT_LIVE_TESTS=1 and Screen Recording permission.
4. Update docs and CHANGELOG.md

Used By

Powering 50+ open-source projects across screen recording, AI agents, meeting transcription, and remote desktop. A few highlights:

• AFFiNE — knowledge base, Notion / Miro alternative (68k+ ⭐)
• voicebox — open-source AI voice studio (25k+ ⭐)
• Cap — open-source Loom alternative (19k+ ⭐)
• Observer — local AI screen observer (1.4k+ ⭐)
• my-translator — real-time speech translation (1k+ ⭐)
• hylarana — cross-platform screen casting in Rust
• gst-screencapturekit — GStreamer plugin
• open-agent, watson.ai, harana/search, agent-native by Builder.io

Using screencapturekit-rs? Open an issue and we'll add you.

Contributors

Thanks to everyone who has contributed!

Per Johansson (maintainer) · Iason Paraskevopoulos · Kris Krolak · Tokuhiro Matsuno · Pranav Joglekar · Alex Jiao · Charles · bigduu · Andrew N

License

Licensed under either of Apache-2.0 or MIT at your option.