Struct SCStreamConfiguration 

pub struct SCStreamConfiguration(/* private fields */);

Opaque wrapper around SCStreamConfiguration

Configuration for a screen capture stream, including dimensions, pixel format, audio settings, and other capture parameters.

Examples

use screencapturekit::stream::configuration::SCStreamConfiguration;

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

Implementations

impl SCStreamConfiguration

pub fn set_ignores_shadows_single_window( &mut self, ignores_shadows: bool, ) -> &mut Self

Sets whether to ignore shadows for single window capture.

A Boolean value that indicates whether the stream omits the shadow effects of the windows it captures. Available on macOS 14.0+

Requires the macos_14_0 feature flag to be enabled.

pub fn with_ignores_shadows_single_window(self, ignores_shadows: bool) -> Self

Sets whether to ignore shadows for single window capture (builder pattern)

pub fn ignores_shadows_single_window(&self) -> bool

pub fn set_should_be_opaque(&mut self, should_be_opaque: bool) -> &mut Self

Sets whether captured content should be treated as opaque.

A Boolean value that indicates whether the stream treats the transparency of the captured content as opaque. Available on macOS 13.0+

Requires the macos_13_0 feature flag to be enabled.

pub fn with_should_be_opaque(self, should_be_opaque: bool) -> Self

Sets whether captured content should be treated as opaque (builder pattern)

pub fn should_be_opaque(&self) -> bool

pub fn set_includes_child_windows( &mut self, includes_child_windows: bool, ) -> &mut Self

Sets whether to include child windows in capture.

A Boolean value that indicates whether the content includes child windows. Available on macOS 14.2+

Requires the macos_14_2 feature flag to be enabled.

pub fn with_includes_child_windows(self, includes_child_windows: bool) -> Self

Sets whether to include child windows (builder pattern)

pub fn includes_child_windows(&self) -> bool

pub fn set_presenter_overlay_privacy_alert_setting( &mut self, setting: SCPresenterOverlayAlertSetting, ) -> &mut Self

Sets the presenter overlay privacy alert setting.

A configuration for the privacy alert that the capture session displays. Available on macOS 14.2+

Requires the macos_14_2 feature flag to be enabled.

pub fn with_presenter_overlay_privacy_alert_setting( self, setting: SCPresenterOverlayAlertSetting, ) -> Self

Sets the presenter overlay privacy alert setting (builder pattern)

pub fn presenter_overlay_privacy_alert_setting( &self, ) -> SCPresenterOverlayAlertSetting

pub fn set_ignores_shadow_display_configuration( &mut self, ignores_shadow: bool, ) -> &mut Self

Sets whether to ignore shadow display configuration.

Available on macOS 14.0+

Requires the macos_14_0 feature flag to be enabled.

pub fn with_ignores_shadow_display_configuration( self, ignores_shadow: bool, ) -> Self

Sets whether to ignore shadow display configuration (builder pattern)

pub fn ignores_shadow_display_configuration(&self) -> bool

impl SCStreamConfiguration

pub fn set_captures_audio(&mut self, captures_audio: bool) -> &mut Self

Enable or disable audio capture

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_captures_audio(true);
assert!(config.captures_audio());

pub fn with_captures_audio(self, captures_audio: bool) -> Self

Enable or disable audio capture (builder pattern)

pub fn captures_audio(&self) -> bool

Check if audio capture is enabled

pub fn set_sample_rate(&mut self, sample_rate: impl Into<i32>) -> &mut Self

Set the audio sample rate

Accepts either an AudioSampleRate enum or a raw i32 Hz value.

Supported Values

ScreenCaptureKit supports: 8000, 16000, 24000, 48000 Hz. Other values will default to 48000 Hz.

Examples

use screencapturekit::prelude::*;
use screencapturekit::stream::configuration::audio::AudioSampleRate;

// Using the enum (recommended)
let config = SCStreamConfiguration::new()
    .with_sample_rate(AudioSampleRate::Rate48000);

// Using raw value (still works)
let config = SCStreamConfiguration::new()
    .with_sample_rate(48000);

pub fn with_sample_rate(self, sample_rate: impl Into<i32>) -> Self

Set the audio sample rate (builder pattern)

pub fn sample_rate(&self) -> i32

Get the configured audio sample rate in Hz

pub fn audio_sample_rate(&self) -> Option<AudioSampleRate>

Get the configured audio sample rate as an enum

Returns None if the current sample rate is not a supported value.

pub fn set_channel_count(&mut self, channel_count: impl Into<i32>) -> &mut Self

Set the number of audio channels

Accepts either an AudioChannelCount enum or a raw i32 value.

Supported Values

ScreenCaptureKit supports: 1 (mono), 2 (stereo). Other values will default to stereo.

Examples

use screencapturekit::prelude::*;
use screencapturekit::stream::configuration::audio::AudioChannelCount;

// Using the enum (recommended)
let config = SCStreamConfiguration::new()
    .with_channel_count(AudioChannelCount::Stereo);

// Using raw value (still works)
let config = SCStreamConfiguration::new()
    .with_channel_count(2);

pub fn with_channel_count(self, channel_count: impl Into<i32>) -> Self

Set the number of audio channels (builder pattern)

pub fn channel_count(&self) -> i32

Get the configured channel count

pub fn audio_channel_count(&self) -> Option<AudioChannelCount>

Get the configured channel count as an enum

Returns None if the current channel count is not a supported value.

pub fn set_captures_microphone( &mut self, captures_microphone: bool, ) -> &mut Self

Enable microphone capture (macOS 15.0+)

When set to true, the stream will capture audio from the microphone in addition to system/application audio (if captures_audio is also enabled).

Note: Requires NSMicrophoneUsageDescription in your app’s Info.plist for microphone access permission.

Availability

macOS 15.0+. On earlier versions, this setting has no effect.

Example

use screencapturekit::prelude::*;

let config = SCStreamConfiguration::new()
    .with_captures_audio(true)       // System audio
    .with_captures_microphone(true)  // Microphone audio (macOS 15.0+)
    .with_sample_rate(48000)
    .with_channel_count(2);

pub fn with_captures_microphone(self, captures_microphone: bool) -> Self

Enable microphone capture (builder pattern)

pub fn captures_microphone(&self) -> bool

Get whether microphone capture is enabled (macOS 15.0+).

pub fn set_excludes_current_process_audio( &mut self, excludes: bool, ) -> &mut Self

Exclude current process audio from capture.

When set to true, the stream will not capture audio from the current process, preventing feedback loops in recording applications.

Example

use screencapturekit::prelude::*;

let config = SCStreamConfiguration::new()
    .with_captures_audio(true)
    .with_excludes_current_process_audio(true); // Prevent feedback

pub fn with_excludes_current_process_audio(self, excludes: bool) -> Self

Exclude current process audio (builder pattern)

pub fn excludes_current_process_audio(&self) -> bool

Get whether current process audio is excluded from capture.

pub fn set_microphone_capture_device_id(&mut self, device_id: &str) -> &mut Self

Set microphone capture device ID (macOS 15.0+).

Specifies which microphone device to capture from.

Availability

macOS 15.0+. On earlier versions, this setting has no effect.

Example

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::new()
    .with_captures_microphone(true);
config.set_microphone_capture_device_id("AppleHDAEngineInput:1B,0,1,0:1");

pub fn with_microphone_capture_device_id(self, device_id: &str) -> Self

Set microphone capture device ID (builder pattern)

pub fn clear_microphone_capture_device_id(&mut self) -> &mut Self

Clear microphone capture device ID, reverting to default system microphone

pub fn microphone_capture_device_id(&self) -> Option<String>

Get microphone capture device ID (macOS 15.0+).

impl SCStreamConfiguration

pub fn set_shows_cursor(&mut self, shows_cursor: bool) -> &mut Self

Show or hide the cursor in captured frames

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_shows_cursor(true);
assert!(config.shows_cursor());

pub fn with_shows_cursor(self, shows_cursor: bool) -> Self

Show or hide the cursor (builder pattern)

pub fn shows_cursor(&self) -> bool

Check if cursor is shown in capture

pub fn set_shows_mouse_clicks(&mut self, shows_mouse_clicks: bool) -> &mut Self

Show mouse click indicators (macOS 15.0+)

When enabled, draws a circle around the cursor when clicked. This helps viewers track mouse activity in recordings.

Availability

macOS 15.0+. On earlier versions, this setting has no effect.

Examples

use screencapturekit::prelude::*;

let config = SCStreamConfiguration::new()
    .with_shows_cursor(true)
    .with_shows_mouse_clicks(true);

pub fn with_shows_mouse_clicks(self, shows_mouse_clicks: bool) -> Self

Show mouse click indicators (builder pattern)

pub fn shows_mouse_clicks(&self) -> bool

Check if mouse click indicators are shown (macOS 15.0+)

pub fn set_captures_shadows_only( &mut self, captures_shadows_only: bool, ) -> &mut Self

Capture only window shadows (macOS 14.0+)

When set to true, the stream captures only the shadows of windows, not the actual window content. This is useful for creating transparency or blur effects in compositing applications.

Availability

macOS 14.0+. On earlier versions, this setting has no effect.

Examples

use screencapturekit::prelude::*;

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

pub fn with_captures_shadows_only(self, captures_shadows_only: bool) -> Self

Capture only window shadows (builder pattern)

pub fn captures_shadows_only(&self) -> bool

Get whether only window shadows are captured (macOS 14.0+).

pub fn set_ignores_shadows_display( &mut self, ignores_shadows: bool, ) -> &mut Self

Ignore shadows for display capture (macOS 14.0+)

When set to true, window shadows are excluded from display capture.

Availability

macOS 14.0+. On earlier versions, this setting has no effect.

pub fn with_ignores_shadows_display(self, ignores_shadows: bool) -> Self

Ignore shadows for display capture (builder pattern)

pub fn ignores_shadows_display(&self) -> bool

Check if shadows are ignored for display capture (macOS 14.0+)

pub fn set_ignore_global_clip_display(&mut self, ignore: bool) -> &mut Self

Ignore global clip for display capture (macOS 14.0+)

When set to true, the global clip region is ignored for display capture.

Availability

macOS 14.0+. On earlier versions, this setting has no effect.

pub fn with_ignore_global_clip_display(self, ignore: bool) -> Self

Ignore global clip for display capture (builder pattern)

pub fn ignore_global_clip_display(&self) -> bool

Check if global clip is ignored for display capture (macOS 14.0+)

pub fn set_ignore_global_clip_single_window( &mut self, ignore: bool, ) -> &mut Self

Ignore global clip for single window capture (macOS 14.0+)

When set to true, the global clip region is ignored for single window capture.

Availability

macOS 14.0+. On earlier versions, this setting has no effect.

pub fn with_ignore_global_clip_single_window(self, ignore: bool) -> Self

Ignore global clip for single window capture (builder pattern)

pub fn ignore_global_clip_single_window(&self) -> bool

Check if global clip is ignored for single window capture (macOS 14.0+)

impl SCStreamConfiguration

pub fn set_queue_depth(&mut self, queue_depth: u32) -> &mut Self

Set the queue depth for frame buffering

pub fn with_queue_depth(self, queue_depth: u32) -> Self

Set the queue depth (builder pattern)

pub fn queue_depth(&self) -> u32

pub fn set_minimum_frame_interval(&mut self, cm_time: &CMTime) -> &mut Self

Set the minimum frame interval

pub fn with_minimum_frame_interval(self, cm_time: &CMTime) -> Self

Set the minimum frame interval (builder pattern)

pub fn minimum_frame_interval(&self) -> CMTime

pub fn fps(&self) -> u32

Get the target frame rate in frames per second

Converts the minimum frame interval (CMTime) to FPS. Returns 0 if the frame interval is invalid.

pub fn set_fps(&mut self, fps: u32) -> &mut Self

Set the target frame rate in frames per second

This is a convenience method that creates the appropriate CMTime for the given FPS. For example, 60 FPS creates a frame interval of 1/60 second.

Arguments

• fps - Target frames per second (e.g., 30, 60, 120)

Examples

use screencapturekit::stream::configuration::SCStreamConfiguration;

let config = SCStreamConfiguration::new()
    .with_fps(60);

pub fn with_fps(self, fps: u32) -> Self

Set the target frame rate (builder pattern)

See set_fps for details.

pub fn set_capture_resolution_type( &mut self, resolution_type: SCCaptureResolutionType, ) -> &mut Self

Set the capture resolution type (macOS 14.0+)

Controls how the capture resolution is determined.

Arguments

• resolution_type - The resolution strategy to use

Examples

use screencapturekit::stream::configuration::{SCStreamConfiguration, SCCaptureResolutionType};

let config = SCStreamConfiguration::new()
    .with_capture_resolution_type(SCCaptureResolutionType::Best);

pub fn with_capture_resolution_type( self, resolution_type: SCCaptureResolutionType, ) -> Self

Set the capture resolution type (builder pattern, macOS 14.0+)

pub fn capture_resolution_type(&self) -> SCCaptureResolutionType

Get the capture resolution type (macOS 14.0+)

impl SCStreamConfiguration

pub fn set_pixel_format(&mut self, pixel_format: PixelFormat) -> &mut Self

Set the pixel format for captured frames

Examples

use screencapturekit::stream::configuration::{SCStreamConfiguration, PixelFormat};

let mut config = SCStreamConfiguration::default();
config.set_pixel_format(PixelFormat::BGRA);

pub fn with_pixel_format(self, pixel_format: PixelFormat) -> Self

Set the pixel format (builder pattern)

pub fn pixel_format(&self) -> PixelFormat

Get the current pixel format

pub fn set_background_color(&mut self, r: f32, g: f32, b: f32) -> &mut Self

Set the background color for captured content

Available on macOS 13.0+

Parameters

• r: Red component (0.0 - 1.0)
• g: Green component (0.0 - 1.0)
• b: Blue component (0.0 - 1.0)

pub fn with_background_color(self, r: f32, g: f32, b: f32) -> Self

Set the background color (builder pattern)

pub fn set_color_space_name(&mut self, name: &str) -> &mut Self

Set the color space name for captured content

Available on macOS 13.0+

pub fn with_color_space_name(self, name: &str) -> Self

Set the color space name (builder pattern)

pub fn set_color_matrix(&mut self, matrix: &str) -> &mut Self

Set the color matrix for captured content

Available on macOS 13.0+. The matrix should be a 3x3 array in row-major order.

pub fn color_matrix(&self) -> Option<String>

Get the color matrix for captured content

Returns the color matrix as a string, or None if not set.

pub fn with_color_matrix(self, matrix: &str) -> Self

Set the color matrix (builder pattern)

impl SCStreamConfiguration

pub fn set_width(&mut self, width: u32) -> &mut Self

Set the output width in pixels

The width determines the width of captured frames.

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_width(1920);
assert_eq!(config.width(), 1920);

pub fn with_width(self, width: u32) -> Self

Set the output width in pixels (builder pattern)

Examples

use screencapturekit::prelude::*;

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

pub fn width(&self) -> u32

Get the configured output width in pixels

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_width(1920);
assert_eq!(config.width(), 1920);

pub fn set_height(&mut self, height: u32) -> &mut Self

Set the output height in pixels

The height determines the height of captured frames.

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_height(1080);
assert_eq!(config.height(), 1080);

pub fn with_height(self, height: u32) -> Self

Set the output height in pixels (builder pattern)

Examples

use screencapturekit::prelude::*;

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

pub fn height(&self) -> u32

Get the configured output height in pixels

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_height(1080);
assert_eq!(config.height(), 1080);

pub fn set_scales_to_fit(&mut self, scales_to_fit: bool) -> &mut Self

Enable or disable scaling to fit the output dimensions

When enabled, the source content will be scaled to fit within the configured width and height, potentially changing aspect ratio.

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_scales_to_fit(true);
assert!(config.scales_to_fit());

pub fn with_scales_to_fit(self, scales_to_fit: bool) -> Self

Enable or disable scaling to fit (builder pattern)

pub fn scales_to_fit(&self) -> bool

Check if scaling to fit is enabled

pub fn set_source_rect(&mut self, source_rect: CGRect) -> &mut Self

Set the source rectangle to capture

Defines which portion of the source content to capture. Coordinates are relative to the source content’s coordinate system.

Examples

use screencapturekit::prelude::*;
use screencapturekit::cg::CGRect;

// Capture only top-left quarter of screen
let rect = CGRect::new(0.0, 0.0, 960.0, 540.0);
let mut config = SCStreamConfiguration::default();
config.set_source_rect(rect);

pub fn with_source_rect(self, source_rect: CGRect) -> Self

Set the source rectangle (builder pattern)

pub fn source_rect(&self) -> CGRect

Get the configured source rectangle

pub fn set_destination_rect(&mut self, destination_rect: CGRect) -> &mut Self

Set the destination rectangle for captured content

Defines where the captured content will be placed in the output frame. Useful for picture-in-picture or multi-source compositions.

Examples

use screencapturekit::prelude::*;
use screencapturekit::cg::CGRect;

// Place captured content in top-left corner
let rect = CGRect::new(0.0, 0.0, 640.0, 480.0);
let mut config = SCStreamConfiguration::default();
config.set_destination_rect(rect);

pub fn with_destination_rect(self, destination_rect: CGRect) -> Self

Set the destination rectangle (builder pattern)

pub fn destination_rect(&self) -> CGRect

Get the configured destination rectangle

pub fn set_preserves_aspect_ratio( &mut self, preserves_aspect_ratio: bool, ) -> &mut Self

Preserve aspect ratio when scaling

When enabled, the content will be scaled while maintaining its original aspect ratio, potentially adding letterboxing or pillarboxing.

Note: This property requires macOS 14.0+. On older versions, the setter is a no-op and the getter returns false.

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_preserves_aspect_ratio(true);
// Returns true on macOS 14.0+, false on older versions
let _ = config.preserves_aspect_ratio();

pub fn with_preserves_aspect_ratio(self, preserves_aspect_ratio: bool) -> Self

Preserve aspect ratio when scaling (builder pattern)

pub fn preserves_aspect_ratio(&self) -> bool

Check if aspect ratio preservation is enabled

impl SCStreamConfiguration

pub fn set_stream_name(&mut self, name: Option<&str>) -> &mut Self

Set the stream name for identification

Assigns a name to the stream that can be used for debugging and identification purposes. The name appears in system logs and debugging tools.

Examples

use screencapturekit::prelude::*;

let config = SCStreamConfiguration::new()
    .with_stream_name(Some("MyApp-MainCapture"));

pub fn with_stream_name(self, name: Option<&str>) -> Self

Set the stream name (builder pattern)

pub fn stream_name(&self) -> Option<String>

Get the configured stream name

Returns the name assigned to this stream, if any.

pub fn set_capture_dynamic_range( &mut self, dynamic_range: SCCaptureDynamicRange, ) -> &mut Self

Set the dynamic range mode for capture (macOS 15.0+)

Controls whether to capture in SDR or HDR mode and how HDR content should be tone-mapped for display.

Availability

macOS 15.0+. Requires the macos_15_0 feature flag to be enabled.

Modes

• SDR: Standard dynamic range capture (default)
• HDRLocalDisplay: HDR with tone mapping optimized for the local display
• HDRCanonicalDisplay: HDR with canonical tone mapping for portability

Examples

use screencapturekit::prelude::*;
use screencapturekit::stream::configuration::stream_properties::SCCaptureDynamicRange;

let config = SCStreamConfiguration::new()
    .with_width(1920)
    .with_height(1080)
    .with_capture_dynamic_range(SCCaptureDynamicRange::HDRLocalDisplay);

pub fn with_capture_dynamic_range( self, dynamic_range: SCCaptureDynamicRange, ) -> Self

Set the dynamic range mode (builder pattern)

pub fn capture_dynamic_range(&self) -> SCCaptureDynamicRange

Get the configured dynamic range mode (macOS 15.0+)

Returns the current HDR capture mode setting.

Requires the macos_15_0 feature flag to be enabled.

impl SCStreamConfiguration

pub fn new() -> Self

Create a new stream configuration with default values

This is equivalent to SCStreamConfiguration::default().

Examples

use screencapturekit::prelude::*;

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

pub fn from_preset(preset: SCStreamConfigurationPreset) -> Self

Create a configuration from a preset (macOS 15.0+)

Presets provide optimized default values for specific use cases, particularly for HDR capture.

Examples

use screencapturekit::stream::configuration::{SCStreamConfiguration, SCStreamConfigurationPreset};

let config = SCStreamConfiguration::from_preset(SCStreamConfigurationPreset::CaptureHDRStreamLocalDisplay);

Trait Implementations

impl Clone for SCStreamConfiguration

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SCStreamConfiguration

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SCStreamConfiguration

fn default() -> Self

Returns the “default value” for a type.

impl Display for SCStreamConfiguration

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for SCStreamConfiguration

fn drop(&mut self)

Executes the destructor for this type.

impl Hash for SCStreamConfiguration

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for SCStreamConfiguration

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for SCStreamConfiguration

impl Send for SCStreamConfiguration

impl Sync for SCStreamConfiguration