Crate screencapturekit

Crate screencapturekit 

Source
Expand description

ScreenCaptureKit-rs

Crates.io Crates.io Downloads docs.rs License Build Status Stars

💼 Looking for a hosted desktop recording API?
Check out Recall.ai - an API for recording Zoom, Google Meet, Microsoft Teams, in-person meetings, and more.

Safe, idiomatic Rust bindings for Apple’s ScreenCaptureKit framework.

Capture screen content, windows, and applications with high performance and low overhead on macOS 12.3+.

§📑 Table of Contents

§✨ Features

  • 🎥 Screen & Window Capture - Capture displays, windows, or specific applications
  • 🔊 Audio Capture - Capture system audio and microphone input
  • ⚡ Real-time Processing - High-performance frame callbacks with custom dispatch queues
  • 🏗️ Builder Pattern API - Clean, type-safe configuration with ::builder()
  • 🔄 Async Support - Runtime-agnostic async API (works with Tokio, async-std, smol, etc.)
  • 🎨 IOSurface Access - Zero-copy GPU texture access for Metal/OpenGL
  • 🛡️ Memory Safe - Proper reference counting and leak-free by design
  • 📦 Zero Dependencies - No runtime dependencies (only dev dependencies for examples)

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

§📦 Installation

Add to your Cargo.toml:

[dependencies]
screencapturekit = "1"

For async support:

[dependencies]
screencapturekit = { version = "1", features = ["async"] }

For latest macOS features:

[dependencies]
screencapturekit = { version = "1", features = ["macos_26_0"] }

§🚀 Quick Start

§Basic Screen Capture

use screencapturekit::prelude::*;

struct Handler;

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Get available displays
    let content = SCShareableContent::get()?;
    let display = &content.displays()[0];
    
    // Configure capture
    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);
    
    // Start streaming
    let mut stream = SCStream::new(&filter, &config);
    stream.add_output_handler(Handler, SCStreamOutputType::Screen);
    stream.start_capture()?;
    
    // Capture runs in background...
    std::thread::sleep(std::time::Duration::from_secs(5));
    
    stream.stop_capture()?;
    Ok(())
}

§Async Capture

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Get content asynchronously
    let content = AsyncSCShareableContent::get().await?;
    let display = &content.displays()[0];
    
    // Create filter and config
    let filter = SCContentFilter::create()
        .with_display(display)
        .with_excluding_windows(&[])
        .build();
    
    let config = SCStreamConfiguration::new()
        .with_width(1920)
        .with_height(1080);
    
    // Create async stream with frame buffer
    let stream = AsyncSCStream::new(&filter, &config, 30, SCStreamOutputType::Screen);
    stream.start_capture()?;
    
    // Capture frames asynchronously
    for _ in 0..10 {
        if let Some(frame) = stream.next().await {
            println!("📹 Got frame!");
        }
    }
    
    stream.stop_capture()?;
    Ok(())
}

§Window Capture with Audio

use screencapturekit::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = SCShareableContent::get()?;
    
    // Find a specific window
    let windows = content.windows();
    let window = windows
        .iter()
        .find(|w| w.title().as_deref() == Some("Safari"))
        .ok_or("Safari window not found")?;
    
    // Capture window with audio
    let filter = SCContentFilter::create()
        .with_window(window)
        .build();
    
    let config = SCStreamConfiguration::new()
        .with_width(1920)
        .with_height(1080)
        .with_captures_audio(true)
        .with_sample_rate(48000)
        .with_channel_count(2);
    
    let mut stream = SCStream::new(&filter, &config);
    // Add handlers...
    stream.start_capture()?;
    
    Ok(())
}

§Content Picker (macOS 14.0+)

Use the system picker UI to let users choose what to capture:

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = SCContentSharingPickerConfiguration::new();
    
    // Show picker - callback receives result when user selects or cancels
    SCContentSharingPicker::show(&config, |outcome| {
        match outcome {
            SCPickerOutcome::Picked(result) => {
                // Get dimensions from the picked content
                let (width, height) = result.pixel_size();
                println!("Selected: {}x{} (scale: {})", width, height, result.scale());
                
                let stream_config = SCStreamConfiguration::new()
                    .with_width(width)
                    .with_height(height);
                
                // Get filter for streaming
                let filter = result.filter();
                let mut stream = SCStream::new(&filter, &stream_config);
                // ...
            }
            SCPickerOutcome::Cancelled => println!("User cancelled"),
            SCPickerOutcome::Error(e) => eprintln!("Error: {}", e),
        }
    });
    
    Ok(())
}

§Async Content Picker (macOS 14.0+)

Use the async version in async contexts to avoid blocking:

ⓘ
use screencapturekit::async_api::AsyncSCContentSharingPicker;
use screencapturekit::content_sharing_picker::*;
use screencapturekit::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = SCContentSharingPickerConfiguration::new();
    
    // Async picker - doesn't block the executor
    match AsyncSCContentSharingPicker::show(&config).await {
        SCPickerOutcome::Picked(result) => {
            let (width, height) = result.pixel_size();
            println!("Selected: {}x{}", width, height);
            
            let filter = result.filter();
            // Use filter with stream...
        }
        SCPickerOutcome::Cancelled => println!("User cancelled"),
        SCPickerOutcome::Error(e) => eprintln!("Error: {}", e),
    }
    
    Ok(())
}

§🎯 Key Concepts

§Builder Pattern

All types use a consistent ::new() with .with_*() chainable methods pattern:

ⓘ
// Stream configuration
let config = SCStreamConfiguration::new()
    .with_width(1920)
    .with_height(1080)
    .with_pixel_format(PixelFormat::BGRA)
    .with_captures_audio(true);

// Content retrieval options
let content = SCShareableContent::create()
    .with_on_screen_windows_only(true)
    .with_exclude_desktop_windows(true)
    .get()?;

// Content filters
let filter = SCContentFilter::create()
    .with_display(&display)
    .with_excluding_windows(&windows)
    .build();

§Custom Dispatch Queues

Control callback threading with custom dispatch queues:

ⓘ
use screencapturekit::prelude::*;
use screencapturekit::dispatch_queue::{DispatchQueue, DispatchQoS};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let content = SCShareableContent::get()?;
    let display = content.displays().into_iter().next().unwrap();
    let filter = SCContentFilter::create()
        .with_display(&display)
        .with_excluding_windows(&[])
        .build();
    let config = SCStreamConfiguration::new();
    
    let mut stream = SCStream::new(&filter, &config);
    
    let queue = DispatchQueue::new("com.myapp.capture", DispatchQoS::UserInteractive);
    
    stream.add_output_handler_with_queue(
        |_sample: CMSampleBuffer, _of_type: SCStreamOutputType| { /* process frame */ },
        SCStreamOutputType::Screen,
        Some(&queue)
    );
    
    Ok(())
}

Quality of Service Levels:

  • Background - Maintenance tasks
  • Utility - Long-running tasks
  • Default - Standard priority
  • UserInitiated - User-initiated tasks
  • UserInteractive - UI updates (highest priority)

§IOSurface Access

Zero-copy GPU texture access:

use screencapturekit::prelude::*;

struct Handler;

impl SCStreamOutputTrait for Handler {
    fn did_output_sample_buffer(&self, sample: CMSampleBuffer, _of_type: SCStreamOutputType) {
        if let Some(pixel_buffer) = sample.image_buffer() {
            if let Some(surface) = pixel_buffer.io_surface() {
                let width = surface.width();
                let height = surface.height();
                
                // Use with Metal/OpenGL...
                println!("IOSurface: {}x{}", width, height);
            }
        }
    }
}

§Metal Integration

Built-in Metal types for hardware-accelerated rendering without external crates:

use screencapturekit::prelude::*;
use screencapturekit::metal::{
    MetalDevice, MetalRenderPassDescriptor, MetalRenderPipelineDescriptor,
    MTLLoadAction, MTLStoreAction, MTLPrimitiveType, MTLPixelFormat,
    Uniforms, SHADER_SOURCE,
};

// Get the system default Metal device
let device = MetalDevice::system_default().expect("No Metal device");
let command_queue = device.create_command_queue().unwrap();

// Compile built-in shaders (supports BGRA, YCbCr, UI overlays)
let library = device.create_library_with_source(SHADER_SOURCE).unwrap();

// Create render pipeline for textured rendering
let vert_fn = library.get_function("vertex_fullscreen").unwrap();
let frag_fn = library.get_function("fragment_textured").unwrap();
let pipeline_desc = MetalRenderPipelineDescriptor::new();
pipeline_desc.set_vertex_function(&vert_fn);
pipeline_desc.set_fragment_function(&frag_fn);
pipeline_desc.set_color_attachment_pixel_format(0, MTLPixelFormat::BGRA8Unorm);
let _pipeline = device.create_render_pipeline_state(&pipeline_desc).unwrap();

Built-in Shader Functions:

  • vertex_fullscreen - Aspect-ratio-preserving fullscreen quad
  • fragment_textured - BGRA/L10R single-texture rendering
  • fragment_ycbcr - YCbCr biplanar (420v/420f) to RGB conversion
  • vertex_colored / fragment_colored - UI overlay rendering

Metal Types:

  • MetalDevice, MetalCommandQueue, MetalCommandBuffer
  • MetalTexture, MetalBuffer, MetalLayer, MetalDrawable
  • MetalRenderPipelineState, MetalRenderPassDescriptor
  • CapturedTextures<T> - Multi-plane texture container (Y + CbCr for YCbCr formats)

§🎛️ Feature Flags

§Core Features

FeatureDescription
asyncRuntime-agnostic async API (works with any executor)

§macOS Version Features

Feature flags enable APIs for specific macOS versions. They are cumulative (enabling macos_15_0 enables all earlier versions).

FeaturemacOSAPIs Enabled
macos_13_013.0 VenturaAudio capture, synchronization clock
macos_14_014.0 SonomaContent picker, screenshots, content info
macos_14_214.2Menu bar capture, child windows, presenter overlay
macos_14_414.4Current process shareable content
macos_15_015.0 SequoiaRecording output, HDR capture, microphone
macos_15_215.2Screenshot in rect, stream active/inactive delegates
macos_26_026.0Advanced screenshot config, HDR screenshot output

§Version-Specific Example

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

#[cfg(feature = "macos_13_0")]
config.set_should_be_opaque(true);

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

§📚 API Overview

§Core Types

TypeDescription
SCShareableContentQuery available displays, windows, and applications
SCContentFilterDefine what to capture (display/window/app)
SCStreamConfigurationConfigure resolution, format, audio, etc.
SCStreamMain capture stream with output handlers
CMSampleBufferFrame data with timing and metadata

§Async API (requires async feature)

TypeDescription
AsyncSCShareableContentAsync content queries
AsyncSCStreamAsync stream with frame iteration
AsyncSCScreenshotManagerAsync screenshot capture (macOS 14.0+)
AsyncSCContentSharingPickerAsync content picker UI (macOS 14.0+)

§Display & Window Types

TypeDescription
SCDisplayDisplay information (resolution, ID, frame)
SCWindowWindow information (title, bounds, owner, layer)
SCRunningApplicationApplication information (name, bundle ID, PID)

§Media Types

TypeDescription
CMSampleBufferSample buffer with timing and attachments
CMTimeHigh-precision timestamps with timescale
IOSurfaceGPU-backed pixel buffers for zero-copy access
CGImageCore Graphics images for screenshots
CVPixelBufferCore Video pixel buffer with lock guards

§Metal Types (metal module)

TypeDescription
MetalDeviceMetal GPU device wrapper
MetalTextureMetal texture with automatic retain/release
MetalBufferVertex/uniform buffer
MetalCommandQueue / MetalCommandBufferCommand submission
MetalLayerCAMetalLayer for window rendering
MetalRenderPipelineStateCompiled render pipeline
CapturedTextures<T>Multi-plane texture container (Y + CbCr for YCbCr)
UniformsShader uniform structure matching SHADER_SOURCE

§Configuration Types

TypeDescription
PixelFormatBGRA, YCbCr420v, YCbCr420f, l10r (10-bit)
SCPresenterOverlayAlertSettingPrivacy alert behavior
SCCaptureDynamicRangeHDR/SDR modes (macOS 15.0+)
SCScreenshotConfigurationAdvanced screenshot config (macOS 26.0+)
SCScreenshotDynamicRangeSDR/HDR screenshot output (macOS 26.0+)

§🏃 Examples

The examples/ directory contains focused API demonstrations:

§Quick Start (Numbered by Complexity)

  1. 01_basic_capture.rs - Simplest screen capture
  2. 02_window_capture.rs - Capture specific windows
  3. 03_audio_capture.rs - Audio + video capture
  4. 04_pixel_access.rs - Read pixel data with std::io::Cursor
  5. 05_screenshot.rs - Single screenshot, HDR capture (macOS 14.0+, 26.0+)
  6. 06_iosurface.rs - Zero-copy GPU buffers
  7. 07_list_content.rs - List available content
  8. 08_async.rs - Async/await API with multiple examples
  9. 09_closure_handlers.rs - Closure-based handlers and delegates
  10. 10_recording_output.rs - Direct video file recording (macOS 15.0+)
  11. 11_content_picker.rs - System UI for content selection (macOS 14.0+)
  12. 12_stream_updates.rs - Dynamic config/filter updates
  13. 13_advanced_config.rs - HDR, presets, microphone (macOS 15.0+)
  14. 14_app_capture.rs - Application-based filtering
  15. 15_memory_leak_check.rs - Memory leak detection with leaks
  16. 16_full_metal_app/ - Full Metal GUI application (macOS 14.0+)
  17. 17_metal_textures.rs - Metal texture creation from IOSurface
  18. 18_wgpu_integration.rs - Zero-copy wgpu integration
  19. 19_ffmpeg_encoding.rs - Real-time H.264 encoding via FFmpeg
  20. 20_egui_viewer.rs - egui screen viewer integration
  21. 21_bevy_streaming.rs - Bevy texture streaming
  22. 22_tauri_app/ - Tauri 2.0 desktop app with WebGL (macOS 14.0+)
  23. 23_client_server/ - Client/server screen sharing

See examples/README.md for detailed descriptions.

Run an example:

# Basic examples
cargo run --example 01_basic_capture
cargo run --example 09_closure_handlers
cargo run --example 12_stream_updates
cargo run --example 14_app_capture
cargo run --example 17_metal_textures
cargo run --example 18_wgpu_integration
cargo run --example 19_ffmpeg_encoding  # Requires: brew install ffmpeg
cargo run --example 20_egui_viewer
cargo run --example 21_bevy_streaming

# Feature-gated examples
cargo run --example 05_screenshot --features macos_14_0
cargo run --example 08_async --features async
cargo run --example 10_recording_output --features macos_15_0
cargo run --example 11_content_picker --features macos_14_0
cargo run --example 13_advanced_config --features macos_15_0
cargo run --example 16_full_metal_app --features macos_14_0

# Tauri app (separate project)
cd examples/22_tauri_app && npm install && npm run tauri dev

# Client/server screen sharing
cargo run --example 23_client_server_server  # Terminal 1
cargo run --example 23_client_server_client  # Terminal 2

§🧪 Testing

§Run Tests

# All tests
cargo test

# With features
cargo test --features async
cargo test --all-features

# Specific test
cargo test test_stream_configuration

§Linting

cargo clippy --all-features -- -D warnings
cargo fmt --check

§🏗️ Architecture

§Module Organization

screencapturekit/
├── cm/                     # Core Media (CMSampleBuffer, CMTime, IOSurface)
├── cv/                     # Core Video (CVPixelBuffer, CVPixelBufferPool)
├── cg/                     # Core Graphics (CGRect, CGPoint, CGSize)
├── metal/                  # Metal GPU integration (textures, shaders)
├── stream/                 # Stream management
│   ├── configuration/      # SCStreamConfiguration
│   ├── content_filter/     # SCContentFilter
│   └── sc_stream/          # SCStream
├── shareable_content/      # SCShareableContent, SCDisplay, SCWindow
├── dispatch_queue/         # Custom dispatch queues
├── error/                  # Error types
├── screenshot_manager/     # SCScreenshotManager (macOS 14.0+)
├── content_sharing_picker/ # SCContentSharingPicker (macOS 14.0+)
├── recording_output/       # SCRecordingOutput (macOS 15.0+)
├── async_api/              # Async wrappers (feature = "async")
├── utils/                  # FFI strings, FourCharCode utilities
└── prelude/                # Convenience re-exports

§Memory Management

  • Reference Counting - Proper CFRetain/CFRelease for all CoreFoundation types
  • RAII - Automatic cleanup in Drop implementations
  • Thread Safety - Safe to share across threads (where supported)
  • Leak Free - Comprehensive leak tests ensure no memory leaks

§❓ Troubleshooting

§Permission Denied / No Displays Found

Problem: SCShareableContent::get() returns an error or empty lists.

Solution: Grant screen recording permission:

  1. Open System Preferences → Privacy & Security → Screen Recording
  2. Add your app or Terminal to the list
  3. Restart your application

For development, you may need to add Terminal.app to the allowed list.

§Entitlements for App Store / Notarization

Problem: App crashes or permissions fail after notarization.

Solution: Add required entitlements to your entitlements.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.screen-capture</key>
    <true/>
</dict>
</plist>

§Black Frames / No Video Data

Problem: Frames are received but contain no visible content.

Solutions:

  1. Ensure the captured window/display is visible (not minimized)
  2. Check that pixel_format matches your processing expectations
  3. Verify the content filter includes the correct display/window
  4. On Apple Silicon, ensure proper GPU access

§Audio Capture Not Working

Problem: Audio samples not received or empty.

Solutions:

  1. Enable audio capture: .with_captures_audio(true)
  2. Add an audio output handler: stream.add_output_handler(handler, SCStreamOutputType::Audio)
  3. Verify sample_rate and channel_count are set correctly

§Build Errors

Problem: Compilation fails with Swift bridge errors.

Solutions:

  1. Ensure Xcode Command Line Tools are installed: xcode-select --install
  2. Clean and rebuild: cargo clean && cargo build
  3. Check that you’re on macOS (this crate is macOS-only)

§🔧 Platform Requirements

  • macOS 12.3+ (Monterey) - Base ScreenCaptureKit support
  • macOS 13.0+ (Ventura) - Audio capture, synchronization clock
  • macOS 14.0+ (Sonoma) - Content picker, screenshots, content info
  • macOS 15.0+ (Sequoia) - Recording output, HDR capture, microphone
  • macOS 26.0+ (Tahoe) - Advanced screenshot config, HDR screenshot output

§Screen Recording Permission

Screen recording requires explicit user permission. For development:

  • Terminal/IDE must be in System Preferences → Privacy & Security → Screen Recording

For distribution:

  • Add NSScreenCaptureUsageDescription to your Info.plist
  • Sign with appropriate entitlements for notarization

§⚡ Performance

Run benchmarks to measure performance on your hardware:

cargo bench

See docs/BENCHMARKS.md for detailed benchmark documentation including:

  • API overhead measurements
  • Frame throughput at various resolutions
  • First-frame latency
  • Pixel buffer and IOSurface access patterns
  • Optimization tips for latency, throughput, and memory

§Typical Performance (Apple Silicon)

ResolutionExpected FPSFirst Frame Latency
1080p30-60 FPS30-100ms
4K15-30 FPS50-150ms

§🔄 Migration

Upgrading from an older version? See docs/MIGRATION.md for:

  • API changes between versions
  • Code examples for common migrations
  • Deprecated API replacements

§🤝 Contributing

Contributions welcome! Please:

  1. Follow existing code patterns (builder pattern with ::new() and .with_*() methods)
  2. Add tests for new functionality
  3. Run cargo test and cargo clippy
  4. Update documentation

§🚀 Used By

This crate is used by some amazing projects:

  • AFFiNE - Next-gen knowledge base, alternative to Notion and Miro (50k+ ⭐)
  • Vibe - Transcribe on your own! Local transcription tool (5k+ ⭐)
  • Lycoris - Real-time speech recognition & AI-powered note-taking for macOS

Using screencapturekit-rs? Let us know and we’ll add you to the list!

§👥 Contributors

Thanks to everyone who has contributed to this project!

§📄 License

Licensed under either of:

at your option.

§API Documentation

Safe, idiomatic Rust bindings for Apple’s ScreenCaptureKit framework.

Capture screen content, windows, and applications with high performance on macOS 12.3+.

§Features

  • Screen and window capture - Capture displays, windows, or specific applications
  • Audio capture - System audio and microphone input (macOS 13.0+)
  • Real-time frame processing - High-performance callbacks with custom dispatch queues
  • Async support - Runtime-agnostic async API (Tokio, async-std, smol, etc.)
  • Zero-copy GPU access - Direct IOSurface access for Metal/OpenGL integration
  • Screenshots - Single-frame capture without streaming (macOS 14.0+)
  • Recording - Direct-to-file video recording (macOS 15.0+)
  • Content Picker - System UI for user content selection (macOS 14.0+)

§Installation

Add to your Cargo.toml:

[dependencies]
screencapturekit = "1"

For async support:

[dependencies]
screencapturekit = { version = "1", features = ["async"] }

§Quick Start

§1. Request Permission

Screen recording requires user permission. Add to your Info.plist:

<key>NSScreenCaptureUsageDescription</key>
<string>This app needs screen recording permission.</string>

§2. Implement a Frame Handler

You can use either a struct or a closure:

Struct-based handler:

use screencapturekit::prelude::*;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;

struct FrameHandler {
    count: Arc<AtomicUsize>,
}

impl SCStreamOutputTrait for FrameHandler {
    fn did_output_sample_buffer(&self, sample: CMSampleBuffer, of_type: SCStreamOutputType) {
        match of_type {
            SCStreamOutputType::Screen => {
                let n = self.count.fetch_add(1, Ordering::Relaxed);
                if n % 60 == 0 {
                    println!("Frame {n}");
                }
            }
            SCStreamOutputType::Audio => {
                println!("Got audio samples!");
            }
            _ => {}
        }
    }
}

Closure-based handler:

use screencapturekit::prelude::*;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;

let frame_count = Arc::new(AtomicUsize::new(0));
let count_clone = frame_count.clone();

let mut stream = SCStream::new(&filter, &config);
stream.add_output_handler(
    move |_sample: CMSampleBuffer, _of_type: SCStreamOutputType| {
        count_clone.fetch_add(1, Ordering::Relaxed);
    },
    SCStreamOutputType::Screen
);

§3. Start Capturing

use screencapturekit::prelude::*;

// Get available displays
let content = SCShareableContent::get()?;
let display = content.displays().into_iter().next().ok_or("No display")?;

// Configure what to capture
let filter = SCContentFilter::create()
    .with_display(&display)
    .with_excluding_windows(&[])
    .build();

// Configure how to capture
let config = SCStreamConfiguration::new()
    .with_width(1920)
    .with_height(1080)
    .with_pixel_format(PixelFormat::BGRA)
    .with_shows_cursor(true);

// Create stream and add handler
let mut stream = SCStream::new(&filter, &config);
stream.add_output_handler(MyHandler, SCStreamOutputType::Screen);

// Start capturing
stream.start_capture()?;

// ... capture runs in background ...
std::thread::sleep(std::time::Duration::from_secs(5));

stream.stop_capture()?;

§Configuration Options

Use the builder pattern for fluent configuration:

use screencapturekit::prelude::*;

// For 60 FPS, use CMTime to specify frame interval
let frame_interval = CMTime::new(1, 60); // 1/60th of a second

let config = SCStreamConfiguration::new()
    // Video settings
    .with_width(1920)
    .with_height(1080)
    .with_pixel_format(PixelFormat::BGRA)
    .with_shows_cursor(true)
    .with_minimum_frame_interval(&frame_interval)
     
    // Audio settings
    .with_captures_audio(true)
    .with_sample_rate(48000)
    .with_channel_count(2);

§Available Pixel Formats

FormatDescriptionUse Case
PixelFormat::BGRA32-bit BGRAGeneral purpose, easy to use
PixelFormat::l10r10-bit RGBHDR content
PixelFormat::YCbCr_420vYCbCr 4:2:0Video encoding (H.264/HEVC)
PixelFormat::YCbCr_420fYCbCr 4:2:0 full rangeVideo encoding

§Accessing Frame Data

§Pixel Data (CPU)

Lock the pixel buffer for direct CPU access:

use screencapturekit::prelude::*;
use screencapturekit::cv::{CVPixelBuffer, CVPixelBufferLockFlags, PixelBufferCursorExt};
use std::io::{Read, Seek, SeekFrom};

if let Some(buffer) = sample.image_buffer() {
    if let Ok(guard) = buffer.lock(CVPixelBufferLockFlags::READ_ONLY) {
        // Method 1: Direct slice access (fast)
        let pixels = guard.as_slice();
        let width = guard.width();
        let height = guard.height();

        // Method 2: Use cursor for reading specific pixels
        let mut cursor = guard.cursor();
         
        // Read first pixel (BGRA)
        if let Ok(pixel) = cursor.read_pixel() {
            println!("First pixel: {:?}", pixel);
        }

        // Seek to center pixel
        let center_x = width / 2;
        let center_y = height / 2;
        if cursor.seek_to_pixel(center_x, center_y, guard.bytes_per_row()).is_ok() {
            if let Ok(pixel) = cursor.read_pixel() {
                println!("Center pixel: {:?}", pixel);
            }
        }
    }
}

§IOSurface (GPU)

For Metal/OpenGL integration, access the underlying IOSurface:

use screencapturekit::prelude::*;
use screencapturekit::cm::IOSurfaceLockOptions;
use screencapturekit::cv::PixelBufferCursorExt;

if let Some(buffer) = sample.image_buffer() {
    // Check if IOSurface-backed (usually true for ScreenCaptureKit)
    if buffer.is_backed_by_io_surface() {
        if let Some(surface) = buffer.io_surface() {
            println!("Dimensions: {}x{}", surface.width(), surface.height());
            println!("Pixel format: 0x{:08X}", surface.pixel_format());
            println!("Bytes per row: {}", surface.bytes_per_row());
            println!("In use: {}", surface.is_in_use());

            // Lock for CPU access to IOSurface data
            if let Ok(guard) = surface.lock(IOSurfaceLockOptions::READ_ONLY) {
                let mut cursor = guard.cursor();
                if let Ok(pixel) = cursor.read_pixel() {
                    println!("First pixel: {:?}", pixel);
                }
            }
        }
    }
}

§Audio + Video Capture

Capture system audio alongside video:

use screencapturekit::prelude::*;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;

struct AVHandler {
    video_count: Arc<AtomicUsize>,
    audio_count: Arc<AtomicUsize>,
}

impl SCStreamOutputTrait for AVHandler {
    fn did_output_sample_buffer(&self, _sample: CMSampleBuffer, of_type: SCStreamOutputType) {
        match of_type {
            SCStreamOutputType::Screen => {
                self.video_count.fetch_add(1, Ordering::Relaxed);
            }
            SCStreamOutputType::Audio => {
                self.audio_count.fetch_add(1, Ordering::Relaxed);
            }
            SCStreamOutputType::Microphone => {
                // Requires macOS 15.0+ and .with_captures_microphone(true)
            }
        }
    }
}

let content = SCShareableContent::get()?;
let display = content.displays().into_iter().next().ok_or("No display")?;

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

let config = SCStreamConfiguration::new()
    .with_width(1920)
    .with_height(1080)
    .with_captures_audio(true)  // Enable system audio
    .with_sample_rate(48000)    // 48kHz
    .with_channel_count(2);     // Stereo

let handler = AVHandler {
    video_count: Arc::new(AtomicUsize::new(0)),
    audio_count: Arc::new(AtomicUsize::new(0)),
};

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

§Dynamic Stream Updates

Update configuration or content filter while streaming:

use screencapturekit::prelude::*;

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

// Capture at initial resolution...
std::thread::sleep(std::time::Duration::from_secs(2));

// Update to higher resolution while streaming
let new_config = SCStreamConfiguration::new()
    .with_width(1920)
    .with_height(1080);
stream.update_configuration(&new_config)?;

// Switch to a different window
let windows = content.windows();
if let Some(window) = windows.iter().find(|w| w.is_on_screen()) {
    let window_filter = SCContentFilter::create().with_window(window).build();
    stream.update_content_filter(&window_filter)?;
}

stream.stop_capture()?;

§Error Handling with Delegates

Handle stream errors gracefully using delegates:

use screencapturekit::prelude::*;
use screencapturekit::stream::ErrorHandler;

// Create an error handler using a closure
let error_handler = ErrorHandler::new(|error| {
    eprintln!("Stream error: {error}");
});

// Create stream with delegate
let mut stream = SCStream::new_with_delegate(&filter, &config, error_handler);
stream.add_output_handler(
    |_sample, _type| { /* process frames */ },
    SCStreamOutputType::Screen
);
stream.start_capture()?;

§Custom Dispatch Queues

Control which thread/queue handles frame callbacks:

use screencapturekit::prelude::*;
use screencapturekit::dispatch_queue::{DispatchQueue, DispatchQoS};

let mut stream = SCStream::new(&filter, &config);

// Create a high-priority queue for frame processing
let queue = DispatchQueue::new("com.myapp.capture", DispatchQoS::UserInteractive);

stream.add_output_handler_with_queue(
    |_sample, _type| { /* called on custom queue */ },
    SCStreamOutputType::Screen,
    Some(&queue)
);

§Async API

Enable the async feature for async/await support. The async API is executor-agnostic and works with Tokio, async-std, smol, or any runtime:

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

async fn capture() -> Result<(), Box<dyn std::error::Error>> {
    // Get content asynchronously (true async - no blocking)
    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);
     
    // Create async stream with 30-frame buffer
    let stream = AsyncSCStream::new(&filter, &config, 30, SCStreamOutputType::Screen);
    stream.start_capture()?;
     
    // Async iteration over frames
    let mut count = 0;
    while count < 100 {
        if let Some(_frame) = stream.next().await {
            count += 1;
        }
    }
     
    stream.stop_capture()?;
    Ok(())
}

// Concurrent async operations
async fn concurrent_queries() -> Result<(), Box<dyn std::error::Error>> {
    let (result1, result2) = tokio::join!(
        AsyncSCShareableContent::get(),
        AsyncSCShareableContent::with_options()
            .on_screen_windows_only(true)
            .get(),
    );
    Ok(())
}

§Screenshots (macOS 14.0+)

Take single screenshots without setting up a stream:

ⓘ
use screencapturekit::prelude::*;
use screencapturekit::screenshot_manager::SCScreenshotManager;

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);

// Capture screenshot as CGImage
let image = SCScreenshotManager::capture_image(&filter, &config)?;
println!("Screenshot: {}x{}", image.width(), image.height());

// Or capture as CMSampleBuffer for more control
let sample_buffer = SCScreenshotManager::capture_sample_buffer(&filter, &config)?;

§Recording (macOS 15.0+)

Record directly to a video file:

ⓘ
use screencapturekit::prelude::*;
use screencapturekit::recording_output::{
    SCRecordingOutput, SCRecordingOutputConfiguration,
    SCRecordingOutputCodec, SCRecordingOutputFileType
};
use std::path::PathBuf;

let content = SCShareableContent::get()?;
let display = &content.displays()[0];

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

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

// Configure recording output
let output_path = PathBuf::from("/tmp/screen_recording.mp4");
let recording_config = SCRecordingOutputConfiguration::new()
    .with_output_url(&output_path)
    .with_video_codec(SCRecordingOutputCodec::H264)
    .with_output_file_type(SCRecordingOutputFileType::MP4);

let recording_output = SCRecordingOutput::new(&recording_config)
    .ok_or("Failed to create recording output")?;

// Start stream and add recording
let stream = SCStream::new(&filter, &stream_config);
stream.add_recording_output(&recording_output)?;
stream.start_capture()?;

// Record for 10 seconds
std::thread::sleep(std::time::Duration::from_secs(10));

// Check recording stats
let duration = recording_output.recorded_duration();
let file_size = recording_output.recorded_file_size();
println!("Recorded {}/{} seconds, {} bytes", duration.value, duration.timescale, file_size);

stream.remove_recording_output(&recording_output)?;
stream.stop_capture()?;

§Module Organization

ModuleDescription
streamStream configuration and management (SCStream, SCContentFilter)
shareable_contentDisplay, window, and application enumeration
cmCore Media types (CMSampleBuffer, CMTime, IOSurface)
cvCore Video types (CVPixelBuffer, lock guards)
cgCore Graphics types (CGRect, CGSize)
metalMetal texture helpers for zero-copy GPU rendering
dispatch_queueCustom dispatch queues for callbacks
errorError types and result aliases
async_apiAsync wrappers (requires async feature)
screenshot_managerSingle-frame capture (macOS 14.0+)
recording_outputDirect file recording (macOS 15.0+)

§Feature Flags

FeatureDescription
asyncRuntime-agnostic async API
macos_13_0macOS 13.0+ APIs (audio capture, synchronization clock)
macos_14_0macOS 14.0+ APIs (screenshots, content picker)
macos_14_2macOS 14.2+ APIs (menu bar, child windows, presenter overlay)
macos_14_4macOS 14.4+ APIs (current process shareable content)
macos_15_0macOS 15.0+ APIs (recording output, HDR, microphone)
macos_15_2macOS 15.2+ APIs (screenshot in rect, stream delegates)
macos_26_0macOS 26.0+ APIs (advanced screenshot config, HDR output)

Features are cumulative: enabling macos_15_0 also enables all earlier versions.

§Platform Requirements

  • macOS 12.3+ (Monterey) - Base ScreenCaptureKit support
  • Screen Recording Permission - Must be granted by user in System Preferences
  • Hardened Runtime - Required for notarized apps

§Examples

See the examples directory:

ExampleDescription
01_basic_captureSimplest screen capture
02_window_captureCapture specific windows
03_audio_captureAudio + video capture
04_pixel_accessRead pixel data with cursor API
05_screenshotSingle screenshot (macOS 14.0+)
06_iosurfaceZero-copy GPU buffer access
07_list_contentList available displays, windows, apps
08_asyncAsync/await API with any runtime
09_closure_handlersClosure-based handlers
10_recording_outputDirect video recording (macOS 15.0+)
11_content_pickerSystem content picker UI (macOS 14.0+)
12_stream_updatesDynamic config/filter updates
13_advanced_configHDR, presets, microphone (macOS 15.0+)
14_app_captureApplication-based filtering
15_memory_leak_checkMemory leak detection
16_full_metal_appFull Metal GUI application
17_metal_texturesMetal texture creation from IOSurface

§Common Patterns

§Capture Window by Title

use screencapturekit::prelude::*;

let content = SCShareableContent::get()?;
let windows = content.windows();
let window = windows
    .iter()
    .find(|w| w.title().is_some_and(|t| t.contains("Safari")))
    .ok_or("Window not found")?;

let filter = SCContentFilter::create()
    .with_window(window)
    .build();

§Capture Specific Application

use screencapturekit::prelude::*;

let content = SCShareableContent::get()?;
let display = content.displays().into_iter().next().ok_or("No display")?;

// Find app by bundle ID
let apps = content.applications();
let safari = apps
    .iter()
    .find(|app| app.bundle_identifier() == "com.apple.Safari")
    .ok_or("Safari not found")?;

// Capture only windows from this app
let filter = SCContentFilter::create()
    .with_display(&display)
    .with_including_applications(&[safari], &[])  // Include Safari, no excepted windows
    .build();

§Exclude Your Own App’s Windows

use screencapturekit::prelude::*;

let content = SCShareableContent::get()?;
let display = content.displays().into_iter().next().ok_or("No display")?;

// Find our app's windows
let windows = content.windows();
let my_windows: Vec<&SCWindow> = windows
    .iter()
    .filter(|w| w.owning_application()
        .map(|app| app.bundle_identifier() == "com.mycompany.myapp")
        .unwrap_or(false))
    .collect();

// Capture everything except our windows
let filter = SCContentFilter::create()
    .with_display(&display)
    .with_excluding_windows(&my_windows)
    .build();

§List All Available Content

use screencapturekit::prelude::*;

let content = SCShareableContent::get()?;

println!("=== Displays ===");
for display in content.displays() {
    println!("  Display {}: {}x{}", display.display_id(), display.width(), display.height());
}

println!("\n=== Windows ===");
for window in content.windows().iter().filter(|w| w.is_on_screen()) {
    println!("  [{}] {} - {}",
        window.window_id(),
        window.owning_application()
            .map(|app| app.application_name())
            .unwrap_or_default(),
        window.title().unwrap_or_default()
    );
}

println!("\n=== Applications ===");
for app in content.applications() {
    println!("  {} ({})", app.application_name(), app.bundle_identifier());
}

Re-exports§

pub use cm::codec_types;
pub use cm::media_types;
pub use cm::AudioBuffer;
pub use cm::AudioBufferList;
pub use cm::CMFormatDescription;
pub use cm::CMSampleBuffer;
pub use cm::CMSampleTimingInfo;
pub use cm::CMTime;
pub use cm::IOSurface;
pub use cm::SCFrameStatus;
pub use cv::CVPixelBuffer;
pub use cv::CVPixelBufferPool;
pub use utils::four_char_code::FourCharCode;

Modules§

async_api
Async API for ScreenCaptureKit
audio_devices
Audio input device enumeration using AVFoundation.
cg
Core Graphics types for screen coordinates and dimensions
cm
Core Media types and wrappers
content_sharing_picker
SCContentSharingPicker - UI for selecting content to share
cv
Core Video types and wrappers
dispatch_queue
Dispatch Queue wrapper for custom queue management
error
Error types for ScreenCaptureKit operations
ffi
Swift FFI bridge to ScreenCaptureKit
metal
Metal texture helpers for IOSurface
prelude
Prelude module for convenient imports
recording_output
SCRecordingOutput - Direct video file recording
screenshot_manager
SCScreenshotManager - Single-shot screenshot capture
shareable_content
Shareable content types - displays, windows, and applications
stream
Screen capture stream functionality
utils
Utility modules