macOS 快速开始与功能指南

macOS：前置条件、安装、Token、加入频道、发布订阅、事件、错误处理与排障；接口名与签名在构建时取自公开 SDK 接口定义。

接口小节由公开 SDK 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

macOS 端与 iOS 共用 AgoraRtcEngineKit / AgoraRtcEngineDelegate 形状，差别在桌面采集：可以按「显示器 id」或「窗口 id」钉住采集源，并且需要系统屏幕录制权限与对应 entitlement。

前置条件

Xcode 16+、macOS 12+ 部署目标。
Info.plist 补 NSCameraUsageDescription、NSMicrophoneUsageDescription；屏幕共享需在「系统设置 → 隐私与安全性 → 屏幕录制」中授权。
若开启 App Sandbox：需要 com.apple.security.device.camera、com.apple.security.device.audio-input、com.apple.security.device.screen-capture。
已拿到 appId 与 Token 服务（见控制台开通服务与获取凭证）。

安装

ruby

# Podfile（坐标以发布版本为准）
pod 'NimeetRtc', :path => '../sdk/ios', :subspecs => ['macOS']

获取 Token

与 iOS 相同：Token 由后端签发，客户端通过 CallbackTokenProvider 注入；macOS 端可以把 Token 缓存在内存里，不要写进 Keychain 的明文项。

加入频道

swift

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) { }
}

发布与订阅

桌面端最常用的是「共享某个窗口」：

swift

// 1) 枚举源
engine?.getScreenCaptureSources(withThumbSize: CGSize(width: 160, height: 90),
                               iconSize: CGSize(width: 32, height: 32),
                               includeScreen: true) { sources in
    // 2) 选一个窗口源，按 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)
    }
}

按显示器采集用 startScreenCaptureByDisplayId:regionRect:captureParams:；停止用 stopScreenCapture。

事件

与 iOS 同一套 delegate：rtcEngine:didJoinedOfUid:elapsed:、rtcEngine:didOfflineOfUid:reason:、rtcEngine:didOccurError:；屏幕共享额外有源列表与采集状态回调。

错误处理

同步方法返回 Int32，0 成功，负值为声网错误号；未实现能力返回 -4。
屏幕共享最常见的失败不是版本不对，而是权限缺失：源列表为空时先检查系统授权与 entitlement。

排障

现象	原因	处理
源列表为空	未授予屏幕录制权限	系统设置授权后重启 App
共享窗口是黑屏	选中了受保护窗口或最小化窗口	换整屏或可见窗口
采集帧率很低	`frameRate` 与分辨率过高	降到 15fps / 1080p 以内
沙盒下崩溃	缺少 entitlement	补 `com.apple.security.device.*`
音视频都正常但远端听不到	麦克风权限被拒	检查 `NSMicrophoneUsageDescription` 与系统隐私设置

下一步

完整接口与重载：同端 API 参考
错误码与排障：错误码全表、FAQ
服务端签发 Token：Token 鉴权

平台信息

项	值
平台	macOS
语言	Swift / Objective-C
SDK 包	`NimeetRtc`
接口版本	`4.7.0`
兼容参考	声网 macos 端 API

本端公开接口与声网 macos 端 API 对齐；安装与运行要求见上面前置条件。

可用性

该端 SDK：正式可用。本页代码片段使用公开 API；运行时的能力边界以实际发布的 SDK 包为准。

加入频道链路

下列方法名、参数类型与返回值与同端 API 参考一致。一个平台若有多个重载，这里展示最常用的那一个；完整重载见同端 API 参考页。

步骤	接口	方法	重载数
开启视频与本地预览	`AgoraRtcEngineKit`	`enableVideo`	1
加入频道	`AgoraRtcEngineKit`	`joinChannelByToken:channelId:info:uid:joinSuccess:`	1
离开频道	`AgoraRtcEngineKit`	`leaveChannel:`	1
创建实例 / 初始化	`AgoraRtcEngineKit`	`sharedEngineWithAppId:delegate:`	1

typescript

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

事件与回调

该端 SDK 没有事件回调。

错误码

常量	值
`AgoraErrorCodeAdmGeneralError`	`1005`
`AgoraErrorCodeAdmInitLoopback`	`1022`
`AgoraErrorCodeAdmInitPlayout`	`1008`
`AgoraErrorCodeAdmInitRecording`	`1011`
`AgoraErrorCodeAdmJavaResource`	`1006`
`AgoraErrorCodeAdmNoPlayoutDevice`	`1360`
`AgoraErrorCodeAdmNoRecordingDevice`	`1359`
`AgoraErrorCodeAdmPlayAbnormalFrequency`	`1020`
`AgoraErrorCodeAdmRecordAbnormalFrequency`	`1021`
`AgoraErrorCodeAdmRecordAudioFailed`	`1018`
`AgoraErrorCodeAdmRuntimePlayoutError`	`1015`
`AgoraErrorCodeAdmRuntimeRecordingError`	`1017`
`AgoraErrorCodeAdmSampleRate`	`1007`
`AgoraErrorCodeAdmStartLoopback`	`1023`
`AgoraErrorCodeAdmStartPlayout`	`1009`
`AgoraErrorCodeAdmStartRecording`	`1012`
`AgoraErrorCodeAdmStopPlayout`	`1010`
`AgoraErrorCodeAdmStopRecording`	`1013`
`AgoraErrorCodeAlreadyInUse`	`19`
`AgoraErrorCodeBitrateLimit`	`115`
`AgoraErrorCodeBufferTooSmall`	`6`
`AgoraErrorCodeConnectionInterrupted`	`111`
`AgoraErrorCodeConnectionLost`	`112`
`AgoraErrorCodeDecryptionFailed`	`120`
`AgoraErrorCodeEncryptedStreamNotAllowedPublish`	`130`
`AgoraErrorCodeFailed`	`1`
`AgoraErrorCodeInitNetEngine`	`21`
`AgoraErrorCodeInvalidAppId`	`101`
`AgoraErrorCodeInvalidArgument`	`2`
`AgoraErrorCodeInvalidChannelId`	`102`
`AgoraErrorCodeInvalidState`	`8`
`AgoraErrorCodeInvalidToken`	`110`
`AgoraErrorCodeInvalidUserAccount`	`134`
`AgoraErrorCodeJoinChannelRejected`	`17`
`AgoraErrorCodeLeaveChannelRejected`	`18`
`AgoraErrorCodeLoadMediaEngine`	`1001`
`AgoraErrorCodeNoError`	`0`
`AgoraErrorCodeNoServerResources`	`103`
`AgoraErrorCodeNotInChannel`	`113`
`AgoraErrorCodeNotInitialized`	`7`
`AgoraErrorCodeNotReady`	`3`
`AgoraErrorCodeNotSupported`	`4`
`AgoraErrorCodePcmSendBufferOverflow`	`201`
`AgoraErrorCodePcmSendFormat`	`200`
`AgoraErrorCodeResourceLimited`	`22`
`AgoraErrorCodeSizeTooLarge`	`114`
`AgoraErrorCodeStartCall`	`1002`
`AgoraErrorCodeStartCamera`	`1003`
`AgoraErrorCodeStartVideoRender`	`1004`
`AgoraErrorCodeTimedOut`	`10`
`AgoraErrorCodeTokenExpired`	`109`
`AgoraErrorCodeTooManyDataStreams`	`116`
`AgoraErrorCodeVcmEncoderEncodeError`	`1602`
`AgoraErrorCodeVcmEncoderInitError`	`1601`
`AgoraErrorCodeVcmEncoderSetError`	`1603`
`AgoraErrorCodeVcmUnknownError`	`1600`
`AgoraErrorCodeVdmCameraNotAuthorized`	`1501`
`AgoraErrorCodeVideoEffectAssetInvalid`	`1700`
`AgoraErrorCodeVideoEffectEngineInvalid`	`1702`
`AgoraErrorCodeVideoEffectInvalidBundlePath`	`1707`
`AgoraErrorCodeVideoEffectInvalidParam`	`1705`
`AgoraErrorCodeVideoEffectNodeNotActive`	`1704`
`AgoraErrorCodeVideoEffectNotSupported`	`1706`
`AgoraErrorCodeVideoEffectSaveFailed`	`1701`
`AgoraErrorCodeWatermarkAGRB`	`128`
`AgoraErrorCodeWatermarkInfo`	`127`
`AgoraErrorCodeWatermarkParam`	`124`
`AgoraErrorCodeWatermarkPath`	`125`
`AgoraErrorCodeWatermarkPng`	`126`
`AgoraErrorCodeWatermarkRead`	`129`

平台 REST 层用 REST 错误码；SDK 层把连接/鉴权失败映射成声网错误号，映射表见各端 SDK 错误标识。

macOS 快速开始与功能指南

前置条件#

安装#

获取 Token#

加入频道#

发布与订阅#

事件#

错误处理#

排障#

下一步#