如果你希望从此前版本的 macOS 客户端 SDK 升级到最新的客户端 SDK，请在工程文件中，替换最新的客户端 SDK 文件，并参考本文完成 API，回调，参数类型等的替换。

升级过程中，你可能需要参考老版本 API 文档归档。

3.50
产物变更

该版本 SDK 产物新增 libAGFX.dylib 和 libbytenn.dylib 依赖库，需手动导入项目，具体添加方式参看添加依赖。

头文件变更

原 ByteRTCCommonDefines.h 文件拆分为 ByteRTCMediaDefines.h 及 ByteRTCRtsDefines.h

方法变更
变更详情功能模块变动前方法变动后方法备注

拆分

视频管理

(int) registerFaceDetectionObserver:(_Nullable id<ByteRTCFaceDetectionObserver>)faceDetectionObserver withInterval:(NSInteger)interval;

解除人脸识别与视频特效之间的耦合，提升接口易用性。

参数变更

消息

(int64_t)sendUserMessage:(NSString *_Nonnull)userId message:(NSString *_Nonnull)message config:(ByteRTCMessageConfig)config;

(NSInteger)sendUserMessage:(NSString *_Nonnull)userId message:(NSString *_Nonnull)message config:(ByteRTCMessageConfig)config;

返回参数类型由 int64_t 变更为 NSInteger

(int64_t)sendUserBinaryMessage:(NSString * _Nonnull)uid message:(NSData * _Nonnull)message config:(ByteRTCMessageConfig)config;(NSInteger)sendUserBinaryMessage:(NSString * _Nonnull)uid message:(NSData * _Nonnull)message config:(ByteRTCMessageConfig)config;
(int64_t)sendRoomMessage:(NSString *_Nonnull)message NS_SWIFT_NAME(sendRoomMessage(_:));(NSInteger)sendRoomMessage:(NSString *_Nonnull)message NS_SWIFT_NAME(sendRoomMessage(_:));
(int64_t)sendRoomBinaryMessage:(NSData * _Nonnull)message NS_SWIFT_NAME(sendRoomBinaryMessage(_:));(NSInteger)sendRoomBinaryMessage:(NSData * _Nonnull)message NS_SWIFT_NAME(sendRoomBinaryMessage(_:));
(int64_t)sendUserMessageOutsideRoom:(NSString * _Nonnull)userId message:(NSString * _Nonnull)messageStr config:(ByteRTCMessageConfig)config;(NSInteger)sendUserMessageOutsideRoom:(NSString * _Nonnull)userId message:(NSString * _Nonnull)messageStr config:(ByteRTCMessageConfig)config;
(int64_t)sendUserBinaryMessageOutsideRoom:(NSString * _Nonnull)userId message:(NSData * _Nonnull)messageStr config:(ByteRTCMessageConfig)config;(NSInteger)sendUserBinaryMessageOutsideRoom:(NSString * _Nonnull)userId message:(NSData * _Nonnull)messageStr config:(ByteRTCMessageConfig)config;
(int64_t)sendServerMessage:(NSString * _Nonnull)messageStr;(NSInteger)sendServerMessage:(NSString * _Nonnull)messageStr;
(int64_t)sendServerBinaryMessage:(NSData * _Nonnull)messageStr;(NSInteger)sendServerBinaryMessage:(NSData * _Nonnull)messageStr;

参数类型变更

屏幕共享

-(int)setScreenVideoEncoderConfig:(ByteRTCVideoEncoderConfig * _Nullable) screen_solution;

-(int)setScreenVideoEncoderConfig:(ByteRTCScreenVideoEncoderConfig * _Nullable) screen_solution;

参数类型变更为新增的 ByteRTCScreenVideoEncoderConfig

行为变更、名称变更

屏幕共享

  • setVideoSourceType:WithStreamIndex:: 屏幕流默认为外部源

  • setScreenAudioSourceType:: 当前设置为内部源时，且已开启了采集，调用该接口切换为外部源时，不会停止内部采集

  • startScreenAudioCapture:: 当前为外部源时，调用本接口将自动切换为内部源，并开启采集

  • startScreenCaptureSourceInfo:captureParameters:: 当前为外部源时，调用本接口将自动切换为内部源，并开启采集

  • stopScreenAudioCapture/ stopScreenVideoCapture: 当前为外部源时，调用本接口将关闭外部采集

优化屏幕共享接口的行为

所属类型变更、名称变更、参数变更

音视频处理

  • (int)checkVideoEffectLicense:(NSString * _Nonnull)licenseFile;

  • (void)setVideoEffectAlgoModelPath:(NSString * _Nonnull)modelPath;

(int) initCVResource:(NSString* _Nonnull)license_file withAlgoModelDir: (NSString* _Nonnull)algo_model_dir;

  • 统一从 ByteRTCVideo 类下调整到 ByteRTCVideoEffect 类下

  • 统一返回值

(int)enableVideoEffect:(BOOL)enabled;

(int) setVideoEffectNodes:(NSArray <NSString *> *_Nonnull)effectNodePaths;(int) setEffectNodes:(NSArray<NSString*>*_Nonnull)effect_nodes;
(int) updateVideoEffectNode:(NSString * _Nonnull)nodePath nodeKey:(NSString * _Nonnull)nodeKey nodeValue:(float) nodeValue;(int) updateEffectNode:(NSString* _Nonnull)node key:(NSString* _Nonnull)key value:(float) value;

(int) setBackgroundSticker:(NSString* _Nullable)modelPath source:(ByteRTCVirtualBackgroundSource* _Nonnull)source;

(int) setVideoEffectColorFilter:(NSString * _Nonnull)resPath;(int) setColorFilter:(NSString* _Nonnull)filter_res;
(int) setVideoEffectColorFilterIntensity:(float) intensity;(int) setColorFilterIntensity:(float) intensity;
参数变更消息(int)sendSEIMessage:(ByteRTCStreamIndex)streamIndex andMessage:(NSData* _Nonnull)message andRepeatCount:(int)repeatCount;(int)sendSEIMessage:(ByteRTCStreamIndex)streamIndex andMessage:(NSData* _Nonnull)message andRepeatCount:(int)repeatCount andCountPerFrame:(ByteRTCSEICountPerFrame) mode;支持 SEI 多发模式，即在 1 帧间隔内多次发送 SEI 数据时，多个 SEI 随下个视频帧同时发送。

多个模块

返回值类型变化，例如：

  • 旧方法——(void)subscribeStream:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

  • 新方法——(int)subscribeStream:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

以下接口返回值类型由 void 变为 int，具体 int 值含义参考新增数据结构 ByteRTCReturnStatus：
subscribeStream
subscribeScreen
setVoiceChangerType
setVoiceReverbType
login
以下接口返回值类型由 BOOL 变为 int，具体 int 值含义参考新增数据结构 ByteRTCReturnStatus：
pushExternalEncodedVideoFrame
以下接口返回值类型由 BOOL 变为 void：
setUserVisibility
setMultiDeviceAVSync
registerAudioProcessor
以下接口返回值类型由 int 变为 void：
leaveRoom
publishStream
unpublishStream
publishScreen
unpublishScreen
enableSimulcastMode
updateLocalVideoCanvas
setLocalVideoMirrorType
setVideoRotationMode
startLiveTranscoding
stopLiveTranscoding
setPublishFallbackOption
setSubscribeFallbackOption

视频管理

(int)setRemoteVideoCanvas:(NSString * _Nonnull)uid withIndex:(ByteRTCStreamIndex)streamIndex withCanvas:(ByteRTCVideoCanvas * _Nullable)canvas;

(void)setRemoteVideoCanvas:(ByteRTCRemoteStreamKey * _Nonnull)key withCanvas:(ByteRTCVideoCanvas * _Nullable)canvas;

  • 返回值类型由 int 变更为 void。

  • 通过 key 传入 uid 和 streamIndex。

(int)updateRemoteStreamVideoCanvas:(NSString * _Nonnull)roomid withUserId:(NSString * _Nonnull)uid withIndex:(ByteRTCStreamIndex)streamIndex withRenderMode:(ByteRTCRenderMode)renderMode withBackgroundColor:(NSUInteger)backgroundColor;

(void)updateRemoteStreamVideoCanvas:(ByteRTCRemoteStreamKey * _Nonnull)key withRenderMode:(ByteRTCRenderMode)renderMode withBackgroundColor:(NSUInteger)backgroundColor;

  • 返回值类型由 int 变更为 void。

  • 通过 key 传入 roomid 、uid 和 streamIndex。

名称和参数变更

音视频传输

(void)unSubscribeStream:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

(int)unsubscribeStream:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

  • 返回值由 void 变为 int。

  • 修正名称中的大小写。

(void)unSubscribeScreen:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

(int)unsubscribeScreen:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

  • 返回值由 void 变为 int。

  • 修正名称中的大小写。

屏幕分享

(void)pushScreenCaptureFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(int)rotation;

(int)pushScreenVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(int)rotation;

  • 返回值由 void 变为 int。

  • 方法名称由 pushScreenFrame 变更为 pushScreenVideoFrame。

自定义流处理

(BOOL)pushExternalByteVideoFrame:(ByteRTCVideoFrame * _Nonnull)frame;

(int)pushExternalVideoFrame:(ByteRTCVideoFrame * _Nonnull)frame;

  • 返回值由 BOOL 变为 int。

  • 名称由 pushExternalByteVideoFrame 变更为 pushExternalVideoFrame。

(BOOL)setAudioFrameObserver:(_Nullable id<ByteRTCAudioFrameObserver>) audioFrameObserver;

(void)registerAudioFrameObserver:(_Nullable id<ByteRTCAudioFrameObserver>) audioFrameObserver;

  • 返回值由 BOOL 变为 void。

  • 名称由 setAudioFrameObserver 变为 registerAudioFrameObserver。

名称变更

高级功能

UpdateScreenCaptureMouseCursor

updateScreenCaptureMouseCursor

大驼峰变为小驼峰。

SetVideoWatermarksetVideoWatermark
音视频处理ClearVideoWatermarkclearVideoWatermark
ClearVideoWatermarkclearVideoWatermark
视频管理SetVideoEncoderConfigsetVideoEncoderConfig
SetMaxVideoEncoderConfigsetMaxVideoEncoderConfig
屏幕分享getScreenCaptureSourceThumbnailgetThumbnail
房间管理joinRoomByTokenjoinRoom
renewTokenupdateToken
setRtcRoomDelegatesetRTCRoomDelegate修正大小写。
引擎管理getSdkVersiongetSDKVersion修正大小写。
安全与加密setEncryptTypesetEncryptInfo
屏幕分享SetScreenVideoEncoderConfigsetScreenVideoEncoderConfig
音频管理startPlaybackDeviceTeststartAudioPlaybackDeviceTest
stopPlaybackDeviceTeststopAudioPlaybackDeviceTest

删除

自定义流处理

删除：

  • (BOOL)pushExternalVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts;

  • (BOOL)pushExternalVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(ByteRTCVideoRotation)rotation;

  • (BOOL)pushExternalVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(ByteRTCVideoRotation)rotation extendedData:(NSData* _Nullable)extendedData supplementaryInfo:(NSData* _Nullable)supplementoryInfo;

由以下接口替代：
(int)pushExternalVideoFrame:(ByteRTCVideoFrame * _Nonnull)frame;

回调变更
变更详情功能模块变动前回调变动后回调备注
废弃音视频传输onRemoteAudioStateChanged 和 onRemoteVideoStateChanged/
音频管理onLocalAudioStateChanged 和 onLocalVideoStateChanged使用 onAudioDeviceStateChanged 和 onVideoDeviceStateChanged 代替

参数变更

消息

(void)rtcRoom:( ByteRTCRoom *_Nonnull)rtcRoom onUserMessageSendResult:(int64_t)msgid error:(ByteRTCUserMessageSendResult)error;

(void)rtcRoom:( ByteRTCRoom *_Nonnull)rtcRoom onUserMessageSendResult:(NSInteger)msgid error:(ByteRTCUserMessageSendResult)error;

msgid 参数类型由 int64_t 变更为 NSInteger

(void)rtcRoom:( ByteRTCRoom *_Nonnull)rtcRoom onRoomMessageSendResult:(int64_t)msgid error:(ByteRTCRoomMessageSendResult)error;(void)rtcRoom:( ByteRTCRoom *_Nonnull)rtcRoom onRoomMessageSendResult:(NSInteger)msgid error:(ByteRTCRoomMessageSendResult)error;
(void)rtcEngine:(ByteRTCVideo * _Nonnull)engine onUserMessageSendResultOutsideRoom:(int64_t)msgid error:(ByteRTCUserMessageSendResult)error;(void)rtcEngine:(ByteRTCVideo * _Nonnull)engine onUserMessageSendResultOutsideRoom:(NSInteger)msgid error:(ByteRTCUserMessageSendResult)error;

CDN 推流

(void)onMixingAudioFrame:(ByteRTCAudioFrame *_Nonnull)audioFrame taskId:(NSString *_Nonnull)taskId;

(void)onMixingAudioFrame:(ByteRTCAudioFrame *_Nonnull)audioFrame timestamp:(int64_t)timeStamp taskId:(NSString *_Nonnull)taskId;

新增参数 timeStamp

消息

(void)rtcEngine:(ByteRTCVideo * _Nonnull)engine onPublicStreamSEIMessageReceived:(NSString* _Nonnull)publicStreamId andMessage:(NSData* _Nonnull)message;

(void)rtcEngine:(ByteRTCVideo * _Nonnull)engine onPublicStreamSEIMessageReceived:(NSString* _Nonnull)publicStreamId andMessage:(NSData* _Nonnull)message andSourceType:(ByteRTCSEIMessageSourceType)sourceType;

名称变更房间管理onLeaveRoomWithStatsonLeaveRoom

音视频传输

connectionChangedToState

onConnectionStateChanged

networkTypeChangedToTypeonNetworkTypeChanged
reportSysStatsonSysStats

网络管理

onPerformanceAlarmsWithMode

onPerformanceAlarms

OnSimulcastSubscribeFallbackonSimulcastSubscribeFallback大驼峰变为小驼峰。
安全与加密ByteRTCEncryptRawDataonEncryptData
ByteRTCDecryptRawDataonDecryptData
视频管理onFaceDetectionResultonFaceDetectResult

删除

音视频传输

删除：
(void)rtcEngine:(ByteRTCVideo * _Nonnull)engine remoteVideoStateChangedOfUid:(NSString * _Nonnull)uid state:(ByteRTCRemoteVideoState)state;

/

删除回调类

范围语音

ByteRTCRangeAudioObserver 类和相关的接口

此前，在手动订阅的场景下，如果你希望使用范围语音功能，你必须根据此回调获取的衰减系数，设定音量。
自此版本起，无论是手动订阅还是自动订阅，衰减效果都由 SDK 实现，无需使用此接口。

类型变更
变更详情数据类型备注
取值范围拓展ByteRTCVideoCompositingRegion 中，width 和 height取值范围由 (0.0, 1.0] 拓展为 [0.0, 1.0]。
枚举值增删ByteRTCAudioFrameMethod新增枚举值：ByteRTCAudioFrameProcessorEarMonitor = 3
成员变量变更ByteRTCFaceDetectionResult新增成员变量：frameTimestamp
ByteRTCVideoCanvas删除变量：roomId 和 uid

ByteRTCVideoFrame

  • extendedData 的类型由 ByteRTCFrameExtendedData 变为 NSData

  • 新增成员变量：supplementaryInfo

ByteRTCLiveTranscoding新增成员变量：ByteRTCTranscodingClientMixParam
变量类型变更空间音频功能中表示空间坐标的 position 的 变量 x, y, z 类型由 int 更改为 float。提升球面立体声渲染效果。
配置变更ByteRTCRoomProfile房间属性的默认值 ByteRTCRoomProfileCommunication = 0，对应的由 ByteRTCRoomProfileChatRoom = 6 变更为 ByteRTCRoomProfileMeeting = 16。
错误码变更
变更详情错误码备注
枚举值增删ByteRTCErrorCode新增枚举值：ByteRTCUserIDDifferent = -1014
ByteRTCUserMessageSendResult新增枚举值：ByteRTCUserMessageSendResultExceedQPS = 5
ByteRTCRoomMessageSendResult新增枚举值：ByteRTCRoomMessageSendResultExceedQPS = 5
新增ByteRTCPublicStreamErrorCodeonPlayPublicStreamResult: 和 onPushPublicStreamResult: 中的 errorCode 参数类型由 ByteRTCTranscodingError 改为 ByteRTCPublicStreamErrorCode
3.45.6
类型变更

以下表格中的类型发生了变化，你需要在工程文件中找到该类型，并根据变化调整相关处理逻辑：

变更详情数据类型备注
枚举值增删ByteRTCAudioFrameMethod新增屏幕共享音频的枚举值： ByteRTCAudioFrameProcessorScreen = 4
3.45.4
方法变更

以下表格中的方法发生了变化。你需要在工程文件中找到该方法，并进行相关修改：

变更详情功能模块
方法
备注
参数数据结构改动音频管理(void)enableAudioPropertiesReport:(ByteRTCAudioPropertiesConfig* _Nonnull)config;数据结构中，新增参数：
  • ByteRTCAudioPropertiesMode
  • ByteRTCAudioReportMode
    • 3.45.2
    方法变更

    以下表格中的方法发生了变化。你需要在工程文件中找到该方法，并进行相关修改：

    变更详情功能模块
    变动前方法
    变动后方法
    备注
    废弃原方法音频处理(void)muteAudioPlayback:(ByteRTCMuteState)muteState;(void)setPlaybackVolume:(NSInteger)volume;设置远端用户音量为 0 即可停止播放本地收到的音频流