Screen Capturer

Capture screen content on iOS and macOS platforms

Screen Capturer

LiveKit provides platform-specific screen capture capabilities for iOS and macOS. The implementation varies based on platform capabilities and requirements.

macOS Screen Capture

MacOSScreenCapturer

Available on macOS 12.3+, MacOSScreenCapturer uses ScreenCaptureKit for high-performance screen and window capture.

Creating a Screen Share Track

// Get the main display
let display = try await MacOSScreenCapturer.mainDisplaySource()

let options = ScreenShareCaptureOptions(
    dimensions: .h1080_169,
    fps: 30,
    showCursor: true
)

let track = LocalVideoTrack.createMacOSScreenShareTrack(
    source: display,
    options: options
)

Enumerating Screen Sources

Display Sources

let displays = try await MacOSScreenCapturer.displaySources()
for display in displays {
    print("Display: \(display.displayID)")
    print("Size: \(display.width)x\(display.height)")
    print("Frame: \(display.frame)")
}

Window Sources

let windows = try await MacOSScreenCapturer.windowSources()
for window in windows {
    print("Window: \(window.title ?? "Untitled")")
    print("App: \(window.owningApplication?.applicationName ?? "Unknown")")
    print("Size: \(window.frame.size)")
    print("On screen: \(window.isOnScreen)")
}

All Sources

let allSources = try await MacOSScreenCapturer.sources(
    for: .any,
    includeCurrentApplication: false
)

Source Types

MacOSDisplay

Represents a display/monitor:

Property	Type	Description
displayID	CGDirectDisplayID	Unique display identifier
width	Int	Display width in pixels
height	Int	Display height in pixels
frame	CGRect	Display frame

MacOSWindow

Represents an application window:

Property	Type	Description
windowID	CGWindowID	Unique window identifier
frame	CGRect	Window frame
title	String?	Window title
windowLayer	Int	Window layer level
owningApplication	MacOSRunningApplication?	Application that owns the window
isOnScreen	Bool	Whether window is currently visible
isCurrentApplication	Bool	Whether window belongs to current app

Capturing Specific Windows

let windows = try await MacOSScreenCapturer.windowSources()

// Find a specific application window
if let window = windows.first(where: { 
    $0.owningApplication?.applicationName == "Safari" 
}) {
    let track = LocalVideoTrack.createMacOSScreenShareTrack(
        source: window,
        options: options
    )
}

Excluding Windows

let windowsToExclude: [UInt32] = [/* window IDs */]

let options = ScreenShareCaptureOptions(
    excludeWindowIDs: windowsToExclude
)

iOS Screen Capture

In-App Screen Capture

For capturing only your app’s content (iOS 11+):

let options = ScreenShareCaptureOptions(
    dimensions: .h1080_169,
    fps: 15
)

let track = LocalVideoTrack.createInAppScreenShareTrack(
    options: options
)

Broadcast Extension (Full Screen)

For full-screen capture including other apps, you need to implement a Broadcast Upload Extension. The SDK automatically uses the broadcast extension if configured:

let options = ScreenShareCaptureOptions(
    useBroadcastExtension: true
)

// The SDK will use the broadcast extension if available
let track = LocalVideoTrack.createScreenShareTrack(
    options: options
)

Screen Share Capture Options

ScreenShareCaptureOptions

Configure screen capture with these properties:

Property	Type	Default	Description
dimensions	Dimensions	.h1080_169	Target capture dimensions
fps	Int	30	Frames per second
showCursor	Bool	true	Show cursor in capture (macOS only)
appAudio	Bool	false	Capture application audio (macOS 13+)
useBroadcastExtension	Bool	auto	Use broadcast extension (iOS only)
includeCurrentApplication	Bool	false	Include own app windows (macOS only)
excludeWindowIDs	[UInt32]	[]	Window IDs to exclude (macOS only)

let options = ScreenShareCaptureOptions(
    dimensions: .h1080_169,
    fps: 30,
    showCursor: true,
    appAudio: true,
    includeCurrentApplication: false
)

Capturing Application Audio (macOS 13+)

On macOS 13 and later, you can capture audio from the screen share source:

let options = ScreenShareCaptureOptions(
    appAudio: true
)

let track = LocalVideoTrack.createMacOSScreenShareTrack(
    source: display,
    options: options
)

The audio is automatically routed through AudioManager and mixed with other audio sources.

Frame Resending

When screen content is static, MacOSScreenCapturer automatically resends the last frame at 1 fps to maintain the video stream. This ensures:

• Continuous video stream even when content doesn’t change
• Efficient bandwidth usage during static periods
• Smooth experience for viewers

Platform-Specific Considerations

macOS

• Requires macOS 12.3+ for ScreenCaptureKit-based capture
• User must grant screen recording permission in System Preferences
• Can capture individual windows or entire displays
• Supports audio capture on macOS 13+
• Automatically filters out small or system windows

iOS

• In-app capture only captures your app (iOS 11+)
• Full-screen capture requires Broadcast Upload Extension
• User initiates broadcast from Control Center
• Limited to portrait or landscape orientation

Error Handling

do {
    let display = try await MacOSScreenCapturer.mainDisplaySource()
    let track = LocalVideoTrack.createMacOSScreenShareTrack(
        source: display,
        options: options
    )
    try await track.start()
} catch {
    print("Failed to start screen capture: \(error)")
}

Common errors:

• deviceNotFound: No screen capture source available
• invalidState: Screen capture permission not granted
• Permission errors on macOS if screen recording is not allowed

See Also

• Camera Capturer - Camera video capture
• Custom Capturer - Creating custom video capturers
• LocalVideoTrack - Publishing screen share video