screencapturekit-rs

The screencapturekit-rs project uses a Swift bridge to expose macOS's ScreenCaptureKit to Rust via C-compatible symbols (@_cdecl). The bridge is organized into several functional domains:

• Capture Control: Stream.swift handles stream lifecycle.
• Content Discovery: ShareableContent.swift manages finding available content.
• Configuration: StreamConfiguration.swift defines stream settings.
• Advanced Features: ScreenshotManager.swift (macOS 14+), RecordingOutput.swift (macOS 15+), and ContentSharingPicker.swift (macOS 14+).
• Data Types: Provides bindings for CoreGraphics (CGImage, CGRect), CoreMedia (CMSampleBuffer, CMTime), CoreVideo (CVPixelBuffer), IOSurface, and Dispatch (DispatchQueue).

The screencapturekit crate provides Rust bindings for Apple's ScreenCaptureKit.framework.

Important Caveat on Coverage: When a type is marked as "Bound", it means the crate exposes the top-level declaration (class, protocol, enum, or constant). It does not guarantee that every single property or method of that type is implemented in Rust. If you encounter a missing property on a bound type, it may be a gap in the bindings.

Audited Surface Areas include:

• SCStream, SCStreamConfiguration, SCContentFilter
• SCShareableContent, SCShareableContentInfo, SCRunningApplication, SCDisplay, SCWindow
• SCContentSharingPicker, SCContentSharingPickerConfiguration, SCContentSharingPickerMode
• SCRecordingOutput, SCRecordingOutputConfiguration
• SCScreenshotManager (macOS 15.2+ additions)
• Error types: SCStreamErrorCode, SCStreamErrorDomain

The screencapturekit crate provides Rust bindings for the macOS ScreenCaptureKit SDK.

Important Coverage Note: Coverage metrics refer to declaration-level coverage, not member-level coverage. This means that while a top-level SDK declaration (like a class, protocol, or enum) may have a corresponding Rust binding, not every property or method on that type is necessarily reachable or implemented in Rust.

If you encounter a property or method that exists in the macOS SDK but is missing in the Rust API, it is likely due to these implementation gaps.

When passing data from Rust to Metal shaders (as seen in the full_metal_app example), you must ensure memory alignment matches the Metal expectations. Use #[repr(C)] and include explicit padding for types to maintain 16-byte alignment for uniforms.

// Rust struct matching Metal shader vertex input
#[repr(C)]
struct Vertex {
    position: [f32; 2],  // 8 bytes - matches packed_float2
    color: [f32; 4],     // 16 bytes - matches packed_float4
}

// Uniforms with explicit padding for 16-byte alignment
#[repr(C)]
struct Uniforms {
    viewport_size: [f32; 2],  // 8 bytes
    time: f32,                // 4 bytes
    _padding: f32,            // 4 bytes (16-byte alignment)
}

All exported C-compatible symbols follow a strict naming convention to ensure clarity when called from Rust:

<domain>_<object>_<action>

Examples:

• sc_stream_start_capture
• cv_pixel_buffer_lock_base_address

Apple models frame metadata as attachment keys on CMSampleBuffer. Instead of requiring you to use raw string constants, screencapturekit provides a more ergonomic Rust layer.

It exposes these keys as typed accessors and a batched FrameInfo snapshot. You can access properties such as:

• frame_status
• display_time
• scale_factor
• content_scale
• content_rect
• bounding_rect
• screen_rect
• presenter_overlay_content_rect
• dirty_rects

Use the frame_info() method to retrieve a batched snapshot of this data.

To avoid CPU copies when working with Metal or GPU pipelines, use IOSurface to create textures directly from the pixel buffer.

if let Some(surface) = pixel_buffer.io_surface() {
    // Create Metal texture directly from IOSurface
    let texture = device.create_texture_from_iosurface(&surface);
}

Because the bridge crosses the FFI boundary between Swift and Rust, manual memory management is required using the following primitives:

• retain<T>(_:): Use this to pass a retained object to Rust.
• unretained<T>(_:): Use this to get a reference from a Rust pointer.
• release(_:): Use this to release an object currently held by Rust.

retain<T>(_:)     // Pass retained object to Rust
unretained<T>(_:) // Get reference from Rust pointer  
release(_:)       // Release Rust-held object

The screencapturekit crate provides Rust bindings for the macOS ScreenCaptureKit SDK. While the crate aims for high declaration-level coverage (matching top-level classes, protocols, and enums), it is important to note that not every property and method on a bound type is necessarily reachable.

Coverage is measured at the declaration level. For example, a class might be bound, but specific methods within that class might not yet have corresponding Rust implementations. Always check the specific module documentation for the availability of individual members.

To avoid CPU copies when using Metal or wgpu, access the underlying IOSurface from the CMSampleBuffer.

1. Get the pixel_buffer from the CMSampleBuffer.
2. Get the io_surface from the pixel_buffer.
3. Wrap the surface as a MTLTexture (Metal) or use it in wgpu.

Built-in Metal helpers are available in screencapturekit::metal.

use screencapturekit::prelude::*;

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` — no copy.
            }
        }
    }
}