Struct SCStream

Source

pub struct SCStream { /* private fields */ }

Expand description

SCStream is a lightweight wrapper around the Swift SCStream instance. It provides direct FFI access to ScreenCaptureKit functionality.

This is the primary and only implementation of SCStream in v1.0+. All ScreenCaptureKit operations go through Swift FFI bindings.

§Examples

use screencapturekit::prelude::*;

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

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

// Create and start stream
let mut stream = SCStream::new(&filter, &config);
stream.start_capture()?;

// ... capture frames ...

stream.stop_capture()?;

Implementations§

Source §

impl SCStream

Source

pub fn new( filter: &SCContentFilter, configuration: &SCStreamConfiguration, ) -> Self

Create a new stream with a content filter and configuration

§Examples

use screencapturekit::prelude::*;

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

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

Source

pub fn new_with_delegate( filter: &SCContentFilter, configuration: &SCStreamConfiguration, delegate: impl SCStreamDelegateTrait + 'static, ) -> Self

Create a new stream with a content filter, configuration, and delegate

The delegate receives callbacks for stream lifecycle events:

did_stop_with_error - Called when the stream stops due to an error
stream_did_stop - Called when the stream stops (with optional error message)

§Panics

Panics if the internal delegate registry mutex is poisoned.

§Examples

use screencapturekit::prelude::*;
use screencapturekit::stream::delegate_trait::StreamCallbacks;

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

let delegate = StreamCallbacks::new()
    .on_error(|e| eprintln!("Stream error: {}", e))
    .on_stop(|err| {
        if let Some(msg) = err {
            eprintln!("Stream stopped with error: {}", msg);
        }
    });

let stream = SCStream::new_with_delegate(&filter, &config, delegate);
stream.start_capture()?;

Source

pub fn add_output_handler( &mut self, handler: impl SCStreamOutputTrait + 'static, of_type: SCStreamOutputType, ) -> Option<usize>

Add an output handler to receive captured frames

§Arguments

handler - The handler to receive callbacks. Can be:
- A struct implementing SCStreamOutputTrait
- A closure |CMSampleBuffer, SCStreamOutputType| { ... }
of_type - The type of output to receive (Screen, Audio, or Microphone)

§Returns

Returns Some(handler_id) on success, None on failure. The handler ID can be used with remove_output_handler.

§Examples

Using a struct:

use screencapturekit::prelude::*;

struct MyHandler;
impl SCStreamOutputTrait for MyHandler {
    fn did_output_sample_buffer(&self, _sample: CMSampleBuffer, _of_type: SCStreamOutputType) {
        println!("Got frame!");
    }
}

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

Using a closure:

use screencapturekit::prelude::*;

let mut stream = SCStream::new(&filter, &config);
stream.add_output_handler(
    |_sample, _type| println!("Got frame!"),
    SCStreamOutputType::Screen
);

Source

pub fn add_output_handler_with_queue( &mut self, handler: impl SCStreamOutputTrait + 'static, of_type: SCStreamOutputType, queue: Option<&DispatchQueue>, ) -> Option<usize>

Add an output handler with a custom dispatch queue

This allows controlling which thread/queue the handler is called on.

§Arguments

handler - The handler to receive callbacks
of_type - The type of output to receive
queue - Optional custom dispatch queue for callbacks

§Panics

Panics if the internal handler registry mutex is poisoned.

§Examples

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

let mut stream = SCStream::new(&filter, &config);
let queue = DispatchQueue::new("com.myapp.capture", DispatchQoS::UserInteractive);

stream.add_output_handler_with_queue(
    |_sample, _type| println!("Got frame on custom queue!"),
    SCStreamOutputType::Screen,
    Some(&queue)
);

Source

pub fn remove_output_handler( &mut self, id: usize, of_type: SCStreamOutputType, ) -> bool

Remove an output handler

§Arguments

id - The handler ID returned from add_output_handler
of_type - The type of output the handler was registered for

§Panics

Panics if the internal handler registry mutex is poisoned.

§Returns

Returns true if the handler was found and removed, false otherwise.

Source

pub fn start_capture(&self) -> Result<(), SCError>

Start capturing screen content

This method blocks until the capture operation completes or fails.

§Errors

Returns SCError::CaptureStartFailed if the capture fails to start.

Source

pub fn stop_capture(&self) -> Result<(), SCError>

Stop capturing screen content

This method blocks until the capture operation completes or fails.

§Errors

Returns SCError::CaptureStopFailed if the capture fails to stop.

Source

pub fn update_configuration( &self, configuration: &SCStreamConfiguration, ) -> Result<(), SCError>

Update the stream configuration

This method blocks until the configuration update completes or fails.

§Errors

Returns SCError::StreamError if the configuration update fails.

Source

pub fn update_content_filter( &self, filter: &SCContentFilter, ) -> Result<(), SCError>

Update the content filter

This method blocks until the filter update completes or fails.

§Errors

Returns SCError::StreamError if the filter update fails.

Source

pub fn synchronization_clock(&self) -> Option<CMClock>

Get the synchronization clock for this stream (macOS 13.0+)

Returns the CMClock used to synchronize the stream’s output. This is useful for coordinating multiple streams or synchronizing with other media.

Returns None if the clock is not available (e.g., stream not started or macOS version too old).

Source

pub fn add_recording_output( &self, recording_output: &SCRecordingOutput, ) -> Result<(), SCError>

Add a recording output to the stream (macOS 15.0+)

Starts recording if the stream is already capturing, otherwise recording will start when capture begins. The recording is written to the file URL specified in the SCRecordingOutputConfiguration.

§Errors

Returns SCError::StreamError if adding the recording output fails.

Source

pub fn remove_recording_output( &self, recording_output: &SCRecordingOutput, ) -> Result<(), SCError>

Remove a recording output from the stream (macOS 15.0+)

Stops recording if the stream is currently recording.

§Errors

Returns SCError::StreamError if removing the recording output fails.

Trait Implementations§

Source §

Cloning an SCStream creates a new reference to the same underlying Swift SCStream object. The cloned stream shares the same handlers as the original - they receive frames from the same capture session.

Both the original and cloned stream share the same capture state, so:

Starting capture on one affects both
Stopping capture on one affects both
Configuration updates affect both
Handlers receive the same frames

§Examples

use screencapturekit::prelude::*;

let mut stream = SCStream::new(&filter, &config);
stream.add_output_handler(|_, _| println!("Handler 1"), SCStreamOutputType::Screen);

// Clone shares the same handlers
let stream2 = stream.clone();
// Both stream and stream2 will receive frames via Handler 1