ios-screen-sharing.md

iOS Screen Sharing

LiveKit integrates with ReplayKit to support screen sharing on iOS. There are two capture modes available depending on the requirements of your app:

• In-app Capture (default): Share screen content within your app.
• Broadcast Capture: Share screen content even when users switch to other apps.

In-app Capture

By default, LiveKit uses the In-app Capture mode, which requires no additional configuration. In this mode, when screen sharing is enabled, the system prompts the user with a screen recording permission dialog. Once granted, a screen share track is published. The user only needs to grant permission once per app execution.

Permission Dialog

Broadcast Capture

In this mode, when screen sharing is enabled, the system will present the user with a "Screen Broadcast" dialog. To start broadcasting, the user must tap "Start Broadcast." If the user taps outside the dialog, the operation is canceled. This dialog will be presented each time screen sharing is requested.

Screen Broadcast Dialog

In order to capture system-wide screen content, ReplayKit requires a Broadcast Upload Extension—a separate process responsible for delivering samples to your app. This architecture is conceptually illustrated below:

flowchart LR
    subgraph ide1[Common App Group]
    a1[Your Application]
    a2[Broadcast Upload Extension]
    a1--->a2
    a2--Samples from screen-->a1
    end

Loading

Setup Guide

To use the Broadcast Capture mode, follow these steps to add a Broadcast Upload Extension target and associated configuration to your project. You can also refer to the example app, which demonstrates this configuration.

1. Add Broadcast Upload Extension Target

1. In Xcode, Choose "File" > "New > "Target"
2. From the template chooser, select "Broadcast Upload Extension"
3. Name the extension (e.g. "BroadcastExtension"). Take note of the extension's bundle identifier, as it will be needed later.
4. Replace the default content of SampleHandler.swift in the new target with the following:

import LiveKit

#if os(iOS)
@available(macCatalyst 13.1, *)
class SampleHandler: LKSampleHandler {
    override var enableLogging: Bool { true }
}
#endif

Note: Overriding the enableLogging property to return true will bootstrap the logging system in the extension's process, making log messages available through the macOS Console app for troubleshooting.

2. Add Targets to Common App Group

In order for the broadcast extension to communicate with your app, they must be members of the same app group. To enable this, perform the following steps for both your primary app target and broadcast extension target:

1. In the Project Editor, select the target.
2. Select the "Signing & Capabilities" tab and press the "+ Capability" button.
3. Add the "App Groups" capability.
4. Press "+" to add a new app group.
5. Enter an app group identifier in the format group.<domain>.<group_name>. Be sure to use the same identifier for both targets.

3. Add Properties to Info.plist

1. Set RTCAppGroupIdentifier in the Info.plist of both targets to the group identifier from the previous step.
2. Set RTCScreenSharingExtension in the Info.plist of your primary app target to the broadcast extension's bundle identifier.

4. Begin Screen Share

With setup of the broadcast extension complete, broadcast capture will be used by default when enabling screen share:

try await room.localParticipant.setScreenShare(enabled: true)

Note: When using broadcast capture, custom capture options must be set as room defaults rather than passed when enabling screen share with set(source:enabled:captureOptions:publishOptions:).

Troubleshooting

While running your app in a debug session in Xcode, check the debug console for errors and use the Console app to inspect logs from the broadcast extension:

1. Launch the Console app.
2. Select your iOS device from the left sidebar and press "Start Streaming."
3. In the search bar, add a filter for messages with a category of "LKSampleHandler."
4. Initiate a screen share in your app and inspect Console for errors.

Advanced Usage

When using broadcast capture, a broadcast can be initiated externally (for example, via control center). By default, when a broadcast begins, the local participant automatically publishes a screen share track. In some cases, however, you may want to handle track publication manually. You can achieve this by using BroadcastManager:

First, disable automatic track publication:

BroadcastManager.shared.shouldPublishTrack = false

Then, use one of the two methods for detecting changes in the broadcast state:

Combine Publisher

let subscription = BroadcastManager.shared
    .isBroadcastingPublisher
    .sink { isBroadcasting in
        // Manually handle track publication
    }

Delegate

class MyDelegate: BroadcastManagerDelegate {
    func broadcastManager(didChangeState isBroadcasting: Bool) {
        // Manually handle track publication
    }
}
BroadcastManager.shared.delegate = MyDelegate()