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 mut config = SCStreamConfiguration::default();
config.set_width(1920);
config.set_height(1080);

Implementations

impl SCStreamConfiguration

pub fn set_ignore_fraction_of_screen(&mut self, ignore_fraction: f64)

Sets the ignore fraction of screen for this SCStreamConfiguration.

Specifies the percentage of the content filter that the stream omits from the captured image. Available on macOS 14.2+

Requires the macos_14_2 feature flag to be enabled.

pub fn get_ignore_fraction_of_screen(&self) -> f64

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

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.2+

Requires the macos_14_2 feature flag to be enabled.

pub fn get_ignores_shadows_single_window(&self) -> bool

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

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 get_should_be_opaque(&self) -> bool

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

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 get_includes_child_windows(&self) -> bool

pub fn set_presenter_overlay_privacy_alert_setting( self, setting: SCPresenterOverlayAlertSetting, )

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 get_presenter_overlay_privacy_alert_setting( &self, ) -> SCPresenterOverlayAlertSetting

pub fn set_ignore_global_clipboard(&mut self, ignore_global_clipboard: bool)

Sets whether to ignore the global clipboard when capturing.

Available on macOS 14.0+

Requires the macos_14_0 feature flag to be enabled.

pub fn get_ignore_global_clipboard(&self) -> bool

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

Sets whether to ignore shadow display configuration.

Available on macOS 14.0+

Requires the macos_14_0 feature flag to be enabled.

pub fn get_ignores_shadow_display_configuration(&self) -> bool

impl SCStreamConfiguration

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

Enable or disable audio capture

Examples

use screencapturekit::prelude::*;

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

pub fn get_captures_audio(&self) -> bool

Check if audio capture is enabled

pub fn set_sample_rate(&mut self, sample_rate: i32)

Set the audio sample rate in Hz

Common values: 44100, 48000

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_sample_rate(48000);
assert_eq!(config.get_sample_rate(), 48000);

pub fn get_sample_rate(&self) -> i32

Get the configured audio sample rate

pub fn set_channel_count(&mut self, channel_count: i32)

Set the number of audio channels

Common values: 1 (mono), 2 (stereo)

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_channel_count(2); // Stereo
assert_eq!(config.get_channel_count(), 2);

pub fn get_channel_count(&self) -> i32

Get the configured channel count

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

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 mut config = SCStreamConfiguration::default();
config.set_captures_audio(true);       // System audio
config.set_captures_microphone(true);  // Microphone audio (macOS 15.0+)
config.set_sample_rate(48000);
config.set_channel_count(2);

pub fn get_captures_microphone(&self) -> bool

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

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

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 mut config = SCStreamConfiguration::default();
config.set_captures_audio(true);
config.set_excludes_current_process_audio(true); // Prevent feedback

pub fn get_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: Option<&str>)

Set microphone capture device ID (macOS 15.0+).

Specifies which microphone device to capture from. Use None for the default system microphone.

Availability

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

Example

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_captures_microphone(true);
config.set_microphone_capture_device_id(Some("AppleHDAEngineInput:1B,0,1,0:1"));

pub fn get_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)

Show or hide the cursor in captured frames

Examples

use screencapturekit::prelude::*;

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

pub fn get_shows_cursor(&self) -> bool

Check if cursor is shown in capture

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

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 mut config = SCStreamConfiguration::default();
config.set_width(1920);
config.set_height(1080);
config.set_captures_shadows_only(true); // Only capture shadows

pub fn get_captures_shadows_only(&self) -> bool

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

impl SCStreamConfiguration

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

Set the queue depth for frame buffering

pub fn get_queue_depth(&self) -> u32

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

Set the minimum frame interval

pub fn get_minimum_frame_interval(&self) -> CMTime

pub fn set_capture_resolution(&mut self, width: usize, height: usize)

Set the capture resolution for the stream

Available on macOS 14.0+. Controls the resolution at which content is captured.

Arguments

• width - The width in pixels
• height - The height in pixels

pub fn get_capture_resolution(&self) -> (usize, usize)

Get the configured capture resolution

Returns (width, height) tuple

impl SCStreamConfiguration

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

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 get_pixel_format(&self) -> PixelFormat

Get the current pixel format

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

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 set_color_space_name(&mut self, name: &str)

Set the color space name for captured content

Available on macOS 13.0+

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

Set the color matrix for captured content

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

impl SCStreamConfiguration

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

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.get_width(), 1920);

pub fn get_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.get_width(), 1920);

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

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.get_height(), 1080);

pub fn get_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.get_height(), 1080);

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

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.get_scales_to_fit());

pub fn get_scales_to_fit(&self) -> bool

Check if scaling to fit is enabled

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

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 get_source_rect(&self) -> CGRect

Get the configured source rectangle

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

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 get_destination_rect(&self) -> CGRect

Get the configured destination rectangle

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

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.get_preserves_aspect_ratio();

pub fn get_preserves_aspect_ratio(&self) -> bool

Check if aspect ratio preservation is enabled

pub fn set_preserve_aspect_ratio(&mut self, preserve_aspect_ratio: bool)

Preserve aspect ratio when scaling (alternative API)

This is an alternative to set_preserves_aspect_ratio for compatibility.

pub fn get_preserve_aspect_ratio(&self) -> bool

Check if aspect ratio preservation is enabled (alternative API)

pub fn set_increase_resolution_for_retina_displays( &mut self, increase_resolution: bool, )

Enable or disable increased resolution for Retina displays

When enabled, the captured content will be scaled up to match the backing scale factor of Retina displays, providing higher quality output. Available on macOS 13.0+

Examples

use screencapturekit::prelude::*;

let mut config = SCStreamConfiguration::default();
config.set_increase_resolution_for_retina_displays(true);
// Note: Getter may not return the set value on all macOS versions
let _ = config.get_increase_resolution_for_retina_displays();

pub fn get_increase_resolution_for_retina_displays(&self) -> bool

Check if increased resolution for Retina displays is enabled

impl SCStreamConfiguration

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

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 mut config = SCStreamConfiguration::default();
config.set_stream_name(Some("MyApp-MainCapture"));

pub fn get_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, )

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 mut config = SCStreamConfiguration::default();
config.set_width(1920)
config.set_height(1080)
config.set_capture_dynamic_range(SCCaptureDynamicRange::HDRLocalDisplay);

pub fn get_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.

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