macOS SDK Guide

Install, join a channel, screen capture and platform notes.

Interface sections generated from the public SDK definitions

Version v1.1.0 · Updated 2026-10-26 · revision 1

The macOS platform shares the AgoraRtcEngineKit / AgoraRtcEngineDelegate shape with iOS; the difference is desktop capture: the capture source can be pinned by "display id" or "window id", and it requires the system screen-recording permission plus the matching entitlement.

Prerequisites#

• Xcode 16+, a macOS 12+ deployment target.
• Add NSCameraUsageDescription and NSMicrophoneUsageDescription to Info.plist; screen sharing must be authorised in "System Settings → Privacy & Security → Screen Recording".
• If App Sandbox is enabled, you need com.apple.security.device.camera, com.apple.security.device.audio-input and com.apple.security.device.screen-capture.
• You already have an appId and a token service (see Enable services and get credentials).

Install#

# Podfile (planned coordinate; not published yet)
pod 'NimeetRtc', :path => '../sdk/ios', :subspecs => ['macOS']

Get a token#

As on iOS: tokens are issued by the backend and injected by the client through CallbackTokenProvider; on macOS you can cache the token in memory, but do not write it into a plaintext Keychain item.

Join a channel#

import NimeetRtc

final class MeetingController: NSObject, AgoraRtcEngineDelegate {
    private var engine: AgoraRtcEngineKit?

    func start(appId: String, token: String, localView: NSView) {
        engine = AgoraRtcEngineKit.sharedEngine(withAppId: appId, delegate: self)
        engine?.setChannelProfile(.liveBroadcasting)
        engine?.enableVideo()
        let canvas = AgoraRtcVideoCanvas()
        canvas.view = localView
        engine?.setupLocalVideo(canvas)
        engine?.startPreview()
        engine?.joinChannel(byToken: token, channelId: "weekly-sync", uid: 10001, mediaOptions: .init()) { channel, uid, elapsed in
            print("joined \(channel) uid=\(uid)")
        }
    }

    func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) { }
    func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) { }
}

Publish and subscribe#

The most common desktop scenario is "share one window":

// 1) Enumerate sources
engine?.getScreenCaptureSources(withThumbSize: CGSize(width: 160, height: 90),
                               iconSize: CGSize(width: 32, height: 32),
                               includeScreen: true) { sources in
    // 2) Pick a window source and pin capture to its windowId
    if let window = sources.first(where: { $0.sourceType == .window }) {
        let params = AgoraScreenCaptureParameters()
        params.frameRate = 15
        let region = CGRect.zero
        engine?.startScreenCapture(byWindowId: window.windowId, regionRect: region, captureParams: params)
    }
}

To capture a display, use startScreenCaptureByDisplayId:regionRect:captureParams:; stop with stopScreenCapture.

Events#

The same delegate set as iOS: rtcEngine:didJoinedOfUid:elapsed:, rtcEngine:didOfflineOfUid:reason:, rtcEngine:didOccurError:; screen sharing adds source-list and capture-state callbacks.

Error handling#

• Synchronous methods return Int32; 0 means success and a negative value is an Agora error number; unimplemented capabilities return -4.
• The most common screen-sharing failure is not a wrong version but a missing permission: when the source list is empty, check the system authorisation and the entitlement first.

Troubleshooting#

Next steps#

• Full interfaces and overloads: API reference for this platform
• Error codes and troubleshooting: Error code table, FAQ
• Issue tokens on your server: Token authentication

Platform information

The public interfaces are aligned with the Agora macos API; installation and runtime requirements are listed under Prerequisites above.

Availability

This platform's SDK: Generally available. The examples use the public API; runtime capability follows the published SDK package.

join-channel flow

The method names, parameter types and return values match the API reference for the same platform. Where a method has several overloads, the most common one is shown here; see the API reference for all overloads.

enableVideo(): int
joinChannelByToken:channelId:info:uid:joinSuccess:(token?: NSString*, channelId: NSString*, info?: NSString*, uid: NSUInteger, joinSuccessBlock?: void(^ )(NSString*channel,NSUInteger uid,NSInteger elapsed)): int
leaveChannel:(leaveChannelBlock?: void(^ )(AgoraChannelStats*stat)): int
sharedEngineWithAppId:delegate:(appId: NSString*, delegate?: id): instancetype

Events and callbacks

This SDK has no event callbacks.

Error codes

the platform REST layer uses REST error codes；the SDK layer maps connection/authentication failures to Agora error numbers, for the mapping table see SDK error identifiers per platform。