CloudHub 文档中心
下载中心 文档中心

RTC 实时音视频


CloudHubSDK iOS

CloudHubRtcEngineKit

代理设置

delegate:

设置 CloudHubRtcEngineKit 的回调代理

@property (nonatomic, weak) id<CloudHubRtcEngineDelegate> _Nullable delegate;

详情

详见 CloudHubRtcEngineDelegate

频道管理

sharedEngineWithAppId:config:

获得 RTC 引擎单例对象指针

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId
                                        config:(NSString * _Nullable)config;

参数

参数描述
appIdCloudHub 为 app 开发者提供的 App ID,使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播,一个 App ID 只能用于创建一个 CloudHubRtcEngineKit
config保留参数

返回

详情

请在主线程调用 CloudHubRtcEngineKit 类的接口函数

Note

sharedEngineWithAppId:config:externalDevices:

获得 RTC 引擎单例对象指针

- (instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId
                                        config:(NSString * _Nullable)config
                                        externalDevices:(int)extDevices;

参数

参数描述
appIdCloudHub 为 app 开发者提供的 App ID,使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播,一个 App ID 只能用于创建一个 CloudHubRtcEngineKit
config保留参数
extDevices外部设备

返回

详情

请在主线程调用 CloudHubRtcEngineKit 类的接口函数

Note

setChannelProfile

设置频道场景

- (int)setChannelProfile:(CloudHubChannelProfile)profile;

参数

参数描述
profile频道场景,详见 CloudHubChannelProfile

返回

详情

CloudHubRtcEngineKit 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质

Note

setClientRole

设置用户角色

- (int)setClientRole:(CloudHubClientRole)role;

参数

参数描述
role用户角色,详见 CloudHubClientRole

返回

详情

在加入频道前,用户需要通过本方法设置观众(默认)或主播角色,在加入频道后,用户可以通过本方法切换用户角色 如果你在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 rtcEngine:onClientRoleChangedFrom:to: 回调; 远端会触发 rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel:rtcEngine:didOfflineOfUid:reason: 回调

Note

joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess:

加入频道

- (int)joinChannelByToken:(NSString * _Nullable)token
                channelId:(NSString * _Nonnull)channelId
               properties:(NSString * _Nullable)properties
                      uid:(NSString * _Nullable)uid
       autoSubscribeAudio:(BOOL)autoSubscribeAudio
       autoSubscribeVideo:(BOOL)autoSubscribeVideo
              joinSuccess:(void(^ _Nullable)(NSString * _Nonnull uid, NSInteger elapsed))joinSuccessBlock;

参数

参数描述
token开发者服务侧生成的 token,如果对安全性要求不高,可以传空
channelId频道号,必须是字母、数字的组合
properties用户自定义属性,会被同步给频道内其他用户,必须是 json 字符串可以传空
uid用户在频道内的唯一标识,字符串,必须是字母、数字的组合,如果传空,CloudHubRtcEngineKit 会自动为你生成一个 GUID 做为 uid ,并通过 rtcEngine:didJoinChannelwithUid:elapsed: 回调告知你
autoSubscribeAudio自动订阅音频
autoSubscribeVideo自动订阅视频
joinSuccessBlock成功加入频道回调,会在 rtcEngine:didJoinChannelwithUid:elapsed: 之后调用

返回

详情

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊,使用不同 App ID 的 App 是不能互通的,如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道

Note

leaveChannel

离开频道

- (int)leaveChannel:(void(^ _Nullable)(void))leaveChannelBlock;

参数

参数描述
leaveChannelBlock成功离开频道回调,会在 rtcEngine:didLeaveChannel: 之后调用

返回

详情

离开频道,即挂断或退出通话,当调用 joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess: 方法后,必须调用 leaveChannel: 结束通话,否则无法开始下一次通话, 不管当前是否在通话中,都可以调用本方法,没有副作用,该方法会把会话相关的所有资源释放掉,该方法是异步操作,调用返回时并没有真正退出频道

renewToken

更新token

- (int)renewToken:(NSString * _Nonnull)token;

参数

参数描述
token开发者服务侧生成的token

返回

详情

该方法用于更新 Token,如果启用了 Token 机制,过一段时间后使用的 Token 会失效当以下任意一种情况发生时:

App 应重新获取 Token,然后调用该 API 更新 Token,否则 SDK 无法和服务器建立连接

getConnectionState

获取当前网络连接状态

- (CloudHubConnectionStateType)getConnectionState;

返回

音频管理

enableAudio

启⽤⾳频模块

- (int)enableAudio;

返回

详情

本⽅法可以启⽤⾳频模块,(⾳频模块默认为开启状态)

disableAudio

关闭⾳频模块

- (int)disableAudio;

返回

详情

本⽅法可以关闭⾳频模块,(⾳频模块默认为开启状态)

adjustRecordingSignalVolume:

调节麦克风采集信号音量

- (int)adjustRecordingSignalVolume:(int)volume;

参数

参数描述
volume麦克风采集信号音量。取值范围为 [0,400],其中:
• 0: 静音
• 100:(默认)原始音量
• 400: 原始音量的 4 倍(自带溢出保护)

返回

adjustUserPlaybackSignalVolume:volume:

调节本地播放的所有远端用户的信号音量

- (int)adjustUserPlaybackSignalVolume:(NSString* _Nonnull)uid
                               volume:(int)volume;

参数

参数描述
volume播放音量。取值范围为 [0,100],其中:
• 0: 静音
• 100:(默认)原始音量

返回

adjustPlaybackSignalVolume:

调节本地播放的所有远端用户的信号音量

- (int)adjustPlaybackSignalVolume:(int)volume;

参数

参数描述
volume播放音量。取值范围为 [0,400],其中:
• 0: 静音
• 100:(默认)原始音量
• 400: 原始音量的 4 倍(自带溢出保护)

返回

enableLocalAudio

开关本地音频采集

- (int)enableLocalAudio:(BOOL)enabled;

参数

参数描述
enabled• YES: 开启本地语音采集
• NO: 停止本地语音采集或处理

返回

详情

当调用 publishStream 方法发布本地音视频流后,语音默认是开启的,该方法可以关闭或重新开启本地语音功能,即停止或重新开始本地音频采集 该方法不影响接收或播放远端音频流,enableLocalAudio: NO 适用于只听不发的用户场景

Note

muteLocalAudioStream

开关本地音频发送

- (int)muteLocalAudioStream:(BOOL)mute;

参数

参数描述
mute• YES: 停止本地音频发送
• NO: 开启本地音频发送

返回

详情

该方法用于允许/禁止往网络发送本地音频流,成功调用该方法后,远端会触发 rtcEngine:remoteAudioStateChangedOfUid:state:reason: 回调(reasonCloudHubAudioRemoteReasonLocalMuted

Note

muteRemoteAudioStream:mute:

接收/停止接收指定音频流

- (int)muteRemoteAudioStream:(NSString* _Nonnull)uid 
                        mute:(BOOL)mute;

参数

参数描述
uid要操作的用户 id
mute是否停止接收该用户的声音

返回

Note

muteAllRemoteAudioStreams

接收/停止接收指定音频流

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

参数

参数描述
mute是否停止接收所有用户的声音

返回

视频管理

enableVideo

启用视频模块

- (int)enableVideo;

返回

详情

该方法用于打开视频模式,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启视频模式,在通话中调用则由音频模式切换为视频模式,调用 disableVideo 方法可关闭视频模式

Note

disableVideo

关闭视频模块

- (int)disableVideo;

返回

详情

该方法用于关闭视频模式,详情请见 enableVideo

setVideoEncoderConfiguration

设置视频编码属性

- (int)setVideoEncoderConfiguration:(CloudHubVideoEncoderConfiguration * _Nonnull)config;

参数

参数描述
config要设置的属性,详见 CloudHubVideoEncoderConfiguration

返回

详情

该方法设置视频编码配置,每个配置对应一套视频参数,如分辨率、帧率、码率、视频方向等,所有设置的参数均为理想情况下的最大值,当视频引擎因设备、网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时,会取最接近最大值的那个值

startPlayingLocalVideo:renderMode:mirrorMode:

为本地视频设置视图并开始播放

- (int)startPlayingLocalVideo:(VIEW_CLASS * _Nonnull)view  
                   renderMode:(CloudHubVideoRenderMode) renderMode  
                   mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

参数

参数描述
view要设置的本地视图(UIView)
renderMode详见 CloudHubVideoRenderMode
mirrorMode详见 CloudHubVideoMirrorMode

返回

详情

调用该方法开始预览本地视频,需要预先调用 enableVideoenableLocalVideo 启动本地摄像头,离开频道再次进入时,需要重新调用该方法才能再次开始预览本地视频

Note

startPlayingRemoteVideo:streamId:renderMode:mirrorMode:

为远端视频设置视图并开始播放

- (int)startPlayingRemoteVideo:(VIEW_CLASS * _Nonnull)view 
                      streamId:(NSString * _Nonnull)streamId 
                    renderMode:(CloudHubVideoRenderMode) renderMode
                    mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

参数

参数描述
view要设置的视图(UIView)
streamID远端视频流的 ID ,可从这个回调⽅法中得到:rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo:
renderMode详⻅ CloudHubVideoRenderMode
mirrorMode详⻅ CloudHubVideoMirrorMode

返回

详情

调⽤该⽅法开始播放远端视频,需要预先调⽤ enableVideo 启动视频引擎

Note

setLocalRenderMode:mirrorMode:

更新本地视图显示模式

- (int)setLocalRenderMode:(CloudHubVideoRenderMode) renderMode
               mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

参数

参数描述
renderMode详见 CloudHubVideoRenderMode
mirrorMode详见 CloudHubVideoMirrorMode

返回

详情

初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式,该方法只影响本地用户看到的视频画面,不影响本地发布视频

Note

setRemoteRenderMode:renderMode:mirrorMode:

更新远端视图显示模式

- (int)setRemoteRenderMode:(NSString * _Nonnull)streamId
                renderMode:(CloudHubVideoRenderMode) renderMode
                mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

参数

参数描述
streamId远端视频流的 Id ,可从这个回调⽅法中得到:rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo:
renderMode详⻅ CloudHubVideoRenderMode
mirrorMode详见 CloudHubVideoMirrorMode

返回

详情

初始化远端⽤户视图后,你可以调⽤该⽅法更新远端⽤户视图在本地显示时的渲染和镜像模式,该⽅法只影响本地⽤户看到的视频画⾯

Note

enableLocalVideo

开关本地视频采集

- (int)enableLocalVideo:(BOOL)enabled;

参数

参数描述
enabled是否启用本地视频:
• YES: 开启本地视频采集和渲染(默认)
• NO: 关闭使用本地摄像头设备,关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流,设置为 NO 时,该方法不需要本地有摄像头

返回

详情

该方法禁用或重新启用本地视频采集,不影响接收远端视频

Note

muteLocalVideoStream

开关本地视频发送

- (int)muteLocalVideoStream:(BOOL)mute;

参数

参数描述
mute• YES: 不发送本地视频流
• NO: 发送本地视频流(默认)

返回

详情

成功调用该方法后,远端会触发 rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: 回调,reasonCloudHubVideoRemoteStateReasonRemoteMuted

Note

muteRemoteVideoStreamWithUid:mute:

是否停⽌接收指定远端⽤户的视频流

- (int)muteRemoteVideoStreamWithUid:(NSString * _Nonnull)uid
                               mute:(BOOL)mute;

参数

参数描述
uid远端视频流的⽤户ID
mute• YES: 不接收远端视频流
• NO: 接收远端视频流(默认)

返回

详情

在加入频道后

Note

muteRemoteVideoByStreamId:mute:

取消或恢复订阅指定远端视频流

- (int)muteRemoteVideoByStreamId:(NSString * _Nonnull)streamId
                            mute:(BOOL)mute;

参数

参数描述
streamId远端视频流的 ID
mute• YES: 不接收远端视频流
• NO: 接收远端视频流(默认)

返回

详情

在加入频道后

muteAllRemoteVideoStreams

是否停⽌接收指定远端⽤户的视频流

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

参数

参数描述
mute• YES: 不接收远端视频流
• NO: 接收远端视频流(默认)

返回

stopPlayingLocalVideo

停止播放本地视频并释放本地视频视图

- (int)stopPlayingLocalVideo;

返回

stopPlayingRemoteVideo

停止播放远端视频并释放视图

- (int)stopPlayingRemoteVideo:(NSString * _Nonnull)streamId;

参数

参数描述
streamId远端视频流的 Id ,可从这个回调⽅法中得到:rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo:

返回

setLocalVideoHD

设置本地视频高清采集。

- (int)setLocalVideoHD;

返回

详情

该方法启用本地视频高清采集,但不影响发送到远端的视频尺寸。发出的视频会做裁剪、拉伸等处理,受 setVideoEncoderConfiguration 控制。

setVideoRotation

设置本地视频旋转方式

- (int)setVideoRotation:(CloudHubVideoRotation)rotation;

参数

参数描述
rotation要设置的旋转方式,详见 CloudHubVideoRotation 默认为 CloudHubVideoRotationAuto

返回

详情

该方法设置本地视频旋转方式,默认情况下(也即选中 CloudHubVideoRotationAuto 时),无论设备处于任何角度,远端看到你的视频总会是头朝上的: 当手机被竖向手持时,发出的视频也是竖向的; 当手机被横置时,发出的视频也是横向的,但你可以通过设置此值,固定视频旋转角度为某个方向,以与你的界面保持一致,此时只有手机方向与你设置的方向一致时,你的视频在远端看起来才是正向

视频前处理及后处理

setBeautyEffectOptions:options:

- (int)setBeautyEffectOptions:(BOOL)enabled options:(CloudHubBeautyOptions *_Nullable)options;

设置美颜参数

参数

参数说明
enabled是否开启美颜功能:

* true:开启
* false:(默认)关闭
options美颜选项,详细定义见 CloudHubBeautyOptions

返回

setVideoEffectEnable:options:device:

- (int)setVideoEffectEnable:(BOOL)enabled
                    options:(CloudHubVideoEffectOptions *_Nullable)options
                     device:(NSString *_Nullable)deviceID;

设置美颜参数

参数

参数说明
enabled是否开启美颜功能:

* true:开启
* false:(默认)关闭
options美颜选项,详细定义见 CloudHubVideoEffectOptions
deviceID指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略

返回

子频道方法

createChannel:

创建子频道

- (CloudHubRtcChannelKit * _Nullable) createChannel:(NSString * _Nonnull)channelId;

参数

参数描述
channelId频道号,必须是字母、数字的组合

返回

destroyChannel:

销毁子频道

(int) destroyChannel:(CloudHubRtcChannelKit * _Nonnull)channel;

参数

参数描述
channelId频道号,必须是字母、数字的组合

返回

音乐文件播放

startPlayingMovie:cycle:

开始播放一个音乐文件

- (int) startPlayingMovie:(NSString * _Nonnull)filepath
                    cycle:(BOOL)cycle;

参数

参数描述
filepath⾳乐⽂件的路径,可以是本地⽂件,也可以是 http/https 链接
cycle播放完毕后是否自动从头开始,默认为 NO

返回

startPlayingMovie:cycle:view:paused:

开始播放一个音乐文件

- (int) startPlayingMovie:(NSString * _Nonnull)filepath
                    cycle:(BOOL)cycle
                     view:(VIEW_CLASS * _Nullable)view
                   paused:(BOOL)paused;

参数

参数描述
filepath⾳乐⽂件的路径,可以是本地⽂件,也可以是 http/https 链接
cycle播放完毕后是否自动从头开始,默认为 NO
view观看带视频的⾳乐⽂件要⽤的视图(UIView),可以为空
paused是否在启动后立即暂停,默认为 NO

返回

stopPlayingMovie:

停止播放一个音乐文件

- (int) stopPlayingMovie:(NSString * _Nonnull)filepath;

参数

参数描述
filepath详见 startPlayingMovie:cycle:view:paused:

返回

pausePlayingMovie:

暂停播放一个音乐文件

- (int) pausePlayingMovie:(NSString * _Nonnull)filepath;

参数

参数描述
filepath详见 startPlayingMovie:cycle:view:paused:

返回

resumePlayingMovie:

继续播放一个音乐文件

- (int) resumePlayingMovie:(NSString * _Nonnull)filepath;

参数

参数描述
filepath详见 startPlayingMovie:cycle:view:paused:

返回

getMovieInfo:

获取音乐文件播放数据

- (CloudHubLocalMovieInfo * _Nullable) getMovieInfo:(NSString * _Nonnull)filepath;

参数

参数描述
filepath详见 startPlayingMovie:cycle:view:paused:

返回

getMovieCurrentPosition:

获取音乐文件的播放进度

- (NSUInteger) getMovieCurrentPosition:(NSString * _Nonnull)filepath;

参数

参数描述
filepath详见 startPlayingMovie:cycle:view:paused:

返回

setMoviePosition:withFile:

为播放中的音乐文件设置进度

- (int) setMoviePosition:(NSUInteger)pos 
                withFile:(NSString * _Nonnull)filepath;

参数

参数描述
pos要移动的目标时间,以毫秒为单位
filepath详见 startPlayingMovie:cycle:view:paused:

返回

⾳效文件播放

getEffectsVolume

获取⾳效⽂件播放⾳量

- (int) getEffectsVolume;

返回

setEffectsVolume:

设置⾳效⽂件播放⾳量

- (int) setEffectsVolume:(int)volume;

参数

参数描述
volume⾳量值,范围为[0, 100],默认为 100

返回

setVolumeOfEffect:volume:

实时调整⾳效⽂件播放饮料,范围为[0,100]

- (int) setVolumeOfEffect:(int)soundId 
                   volume:(int)volume;

参数

参数描述
soundIdplayEffect:filePath:loopCount:pitch:pan:gain:publish:startTimeMS:endTimeMS: 时传⼊的⾳效 Id
volume⾳量值,范围为 [0, 100],默认为 100

返回

playEffect:filePath:loopCount:pitch:gain:publish:startTimeMS:endTimeMS:

开始播放⼀个⾳效⽂件

- (int) playEffect:(int)soundId  
          filePath:(NSString * _Nonnull)filepath  
         loopCount:(int)loopCount  
             pitch:(double)pitch
               pan:(double)pan
              gain:(int)gain  
           publish:(BOOL)publish  
       startTimeMS:(NSUInteger)starttime  
         endTimeMS:(NSUInteger)endtime;

参数

参数描述
soundId⾃⾏设定的⾳效 Id,需要保持唯⼀性
filepath⾳乐⽂件的路径,可以是本地⽂件,也可以是 http/https 链接
loopCount设置⾳效⽂件循环播放的次数:
• 0: 播放⾳效⽂件⼀次
• 1: 循环播放⾳效⽂件两次
• -1: ⽆限循环播放⾳效⽂件,直⾄调⽤ stopEffect:stopAllEffects 后停⽌
pitch音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低
pan音效的空间位置。取值范围为 [-1.0,1.0],例如:
• -1.0: 音效出现在左边
• 0.0: 音效出现在正前方
• 1.0: 音效出现在右边
gain设置⾳效的⾳量
取值范围为 [0.0,100.0],默认值为 100.0, 取值越⼩,则⾳效的⾳量越低
publish设置是否将⾳效传到远端
• YES:⾳效⽂件中本地播放的同时,远端⽤户也能听到该⾳效
• NO:只能在本地听到该⾳效
starttime设置开始播放的时间(毫秒),⽂件将从该处开始播放
endtime设置结束播放的时间(毫秒),⽂件播放到该处时将结束

返回

详情

该⽅法可以播放指定的本地或在线⾳效⽂件来给应⽤增加⾳效,⽐如游戏中特 定操作的⾳效

你可以在该⽅法中设置⾳效⽂件的播放次数和增益,以及远端⽤户是否能听到该⾳效, 你可以多次调⽤该⽅法,通过传⼊不同的⾳效⽂件的 soundID 和 filePath,同时播放多个⾳效⽂件,实现⾳效叠加, 为获得最佳⽤户体验,我们建议同时播放的⾳效⽂件不要超过 3 个

调⽤该⽅法播放⾳效结束后,会触发 rtcEngine:onAudioEffectFinish: 回调

stopEffect:

停⽌播放⼀个⾳效⽂件

- (int) stopEffect:(int)soundId;

参数

参数描述
soundIdplayEffect:filePath:loopCount:pitch:pan:gain:publish:startTimeMS:endTimeMS: 时传⼊的⾳效 Id

返回

stopAllEffects

停⽌播放⼀个⾳效⽂件

- (int) stopAllEffects;

返回

preloadEffect:filePath:

将指定音效文件预加载至内存

- (int) preloadEffect:(int)soundId 
             filePath:(NSString * _Nonnull)filepath;

参数

参数描述
soundId自行设定的音效 Id,需要保持唯一性
filepath音乐文件的路径,可以是本地文件,也可以是 http/https 链接

返回

unloadEffect:

从内存释放某个预加载的音效文件

- (int) unloadEffect:(int)soundId;

参数

参数描述
soundIdplayEffect:filePath:loopCount:pitch:pan:gain:publish:startTimeMS:endTimeMS: 时传⼊的⾳效 ID

返回

pauseEffect:

暂停播放⼀个⾳效⽂件

- (int) pauseEffect:(int)soundId;

参数

参数描述
soundIdplayEffect:filePath:loopCount:pitch:pan:gain:publish:startTimeMS:endTimeMS: 时传⼊的⾳效 Id

返回

pauseAllEffects

暂停播放⼀个⾳效⽂件

- (int) pauseAllEffects;

返回

resumeEffect:

继续播放⼀个⾳效⽂件

- (int) resumeEffect:(int)soundId;

参数

参数描述
soundIdplayEffect:filePath:loopCount:pitch:pan:gain:publish:startTimeMS:endTimeMS: 时传⼊的⾳效 Id

返回

resumeAllEffects

暂停播放⼀个⾳效⽂件

- (int) resumeAllEffects;

返回

translateWavFileToText:

从声音文件识别文本

- (int)translateWavFileToText:(NSString* _Nonnull)wavFile;

参数

参数描述
wavFile声音文件,仅支持 wav 格式

返回

人声效果

要使用人声效果相关功能,请先联系我们帮您开通

setAudioQuality

设置本地发送音频质量

- (int)setAudioQuality:(CloudHubAudioQuality)quality;

参数

参数描述
quality音频质量,详见 CloudHubAudioQuality

返回

setLocalVoicePitch:

设置本地语音音调

- (int)setLocalVoicePitch:(double)pitch

参数

参数描述
pitch语音频率。可以在 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调

返回

详情

该方法改变本地说话人声音的音调。该方法需要在 enableLocalAudio 后调用。 注意,调用 enableLocalAudio 接口并传入 NO 会重设 pitch 为默认状态(即不需要修改音调)

setLocalVoiceEqualizationOfBandFrequency:withGain:

设置本地语音音效均衡

- (int)setLocalVoiceEqualizationOfBandFrequency:(CloudHubAudioEqualizationBandFrequency)bandFrequency 
                                       withGain:(NSInteger)gain

参数

参数描述
bandFrequency频谱子带索引,取值范围是 [0,7],分别代表 8 个 频带,对应的中心频率是 [70 150 250 500 1000 2000 4000 8000] Hz,详见 CloudHubAudioEqualizationBandFrequency
gain每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0

返回

详情

该方法改变本地说话人声音的音调。该方法需要在 enableLocalAudio 后调用。注意,调用 enableLocalAudio接口并传入 false 会重设音效均衡为初始状态

setLocalVoiceReverbOfType:withValue:

设置本地音效混响

- (int)setLocalVoiceReverbOfType:(CloudHubAudioReverbType)reverbType
                       withValue:(double)value

参数

参数描述
reverbType混响音效类型,详见 CloudHubAudioReverbType
value设置混响音效的效果数值,各混响音效对应的取值范围请参考 CloudHubAudioReverbType

返回

详情

该方法设置本地音效混响。该方法需要在 enableLocalAudio后调用。注意,调用 enableLocalAudio接口并传入 false 会取消混响效果

setAudioEffectPreset:

设置 SDK 预设的人声音效

- (int)setAudioEffectPreset:(CloudHubAudioEffectPreset)preset

参数

参数描述
preset预设的音效选项,详见 CloudHubAudioEffectPreset

返回

详情

该方法设置 SDK 预设的人声音效。该方法需要在 enableLocalAudio 后调用。注意,调用 enableLocalAudio 接口并传入 false 会取消预设音效。此方法不能和 setLocalVoicePitch:setLocalVoiceEqualizationOfBandFrequency:withGain:setLocalVoiceReverbOfType:withValue: 混用

enableDeepLearningDenoise:

开启或关闭 AI 降噪模式

- (int)enableDeepLearningDenoise:(BOOL)enabled

参数

参数描述
enabled是否开启 AI 降噪模式:
YES: (默认)开启
NO: 关闭

返回

听声辨位

enableSoundPositionIndication:

开启/关闭远端用户的语音立体声

- (int)enableSoundPositionIndication:(BOOL)enabled

参数

参数描述
enabled是否开启远端用户语音立体声:
YES:开启
NO:关闭

返回

详情

如果想调用 setRemoteVoicePosition:pan:gain: 实现听声辨位的功能,请确保在enableAudio前调用本方法开启远端用户的语音立体声

setRemoteVoicePosition:pan:gain:

设置远端用户的语音位置

- (int)setRemoteVoicePosition:(NSString * _Nonnull)uid
                          pan:(double)pan
                         gain:(double)gain

参数

参数描述
uid远端用户的 ID
pan设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
•(默认)0.0:声音出现在正前方
• -1.0:声音出现在左边
• 1.0:声音出现在右边
gain设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低

返回

详情

设置远端用户声音的空间位置和音量,方便本地用户听声辨位

通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置

Note

跨频道媒体流转发

startChannelMediaRelay:

开始跨频道媒体流转发

- (int) startChannelMediaRelay: (CloudHubChannelMediaRelayConfig* _Nonnull) config;

参数

参数描述
config跨频道媒体流转发参数配置,详⻅ CloudHubChannelMediaRelayConfig

返回

详情

成功调⽤该⽅法后,SDK 会触发 rtcEngine:onChannel:MediaRelayStateChanged:error: 回调,并在回调中报告当前的跨频道媒体流转发状态和事件

Note

updateChannelMediaRelay:

更新媒体流转发的频道

- (int) updateChannelMediaRelay: (CloudHubChannelMediaRelayConfig* _Nonnull) config;

参数

参数描述
config跨频道媒体流转发参数配置,详⻅ CloudHubChannelMediaRelayConfig

返回

详情

成功开始跨频道转发媒体流后,如果你希望将流转发到多个⽬标频道,或退出当前的转发频道,可以调⽤该⽅法

Note

stopChannelMediaRelay

停⽌跨频道媒体流转发

- (int) stopChannelMediaRelay;

返回

详情

⼀旦停⽌,主播会退出所有⽬标频道 成功调⽤该⽅法后,SDK 会触发 rtcEngine:onChannel:MediaRelayStateChanged:error: 回调,如果报告 CloudHub_RELAY_STATE_IDLECloudHub_RELAY_OK,则表示已停⽌转发媒体流

Note

音量提示

enableAudioVolumeIndication:smooth:reportVAD:

启用说话者音量提示

- (int)enableAudioVolumeIndication:(NSInteger)interval 
                            smooth:(NSInteger)smooth 
                         reportVAD:(BOOL)reportVad;

参数

参数描述
interval指定音量提示的时间间隔:
• < = 0: 禁用音量提示功能
• > 0: 提示间隔,单位为毫秒,建议设置到⼤于 200 毫秒,最⼩不得少于 10 毫秒,启⽤该⽅法后,⽆论频道内是否有⼈说话,都会在 rtcEngine:reportAudioVolumeIndication:totalVolume: 回调中按设置的时间间隔返回⾳量提示
smooth指定⾳量提示的灵敏度,取值范围为 [0,10],建议值为 3,数字越⼤,波动越灵敏;数字越⼩,波动越平滑
reportVad指定音量提示的时间间隔:
• YES :开启本地⼈声检测功能,开启后, rtcEngine:reportAudioVolumeIndication:totalVolume: 回调的 speakers 数组,包含 CloudHubAudioVolumeInfovad 数据会报告是否在本地检测到⼈声
• NO:(默认)关闭本地⼈声检测功能,除引擎⾃动进⾏本地⼈声检测 的场景外, rtcEngine:reportAudioVolumeIndication:totalVolume: 回调的 speakers 数组,包含CloudHubAudioVolumeInfovad 数据不会报告是否在本地检测到⼈声

返回

切换播放声音使用扬声器或听筒

setEnableSpeakerphone:

设置当前是否使用扬声器

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

参数

参数描述
enableSpeaker当前是否使用扬声器(默认为 YES)

返回

详情

该方法设置是否将语音路由到扬声器(外放),该方法可以在 joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess: 之前调用

isSpeakerphoneEnabled

获得当前是否使用扬声器

- (BOOL)isSpeakerphoneEnabled;

返回

详情

在接入有线或蓝牙耳机时,声音会被自动切换至耳机,此时 isSpeakerphoneEnabled 的返回值仍然是接入耳机之前的设置,当断开耳机后,声音也将回到接入耳机之前设置的播放路径

耳返控制

enableInEarMonitoring:

开启耳返功能

- (int)enableInEarMonitoring:(BOOL)enabled

参数

参数描述
enabled是否开启耳返功能:
YES: 开启
NO: (默认)关闭

返回

详情

该方法在加入频道前后都能调用

Note

setInEarMonitoringVolume:

设置耳返音量

- (int)setInEarMonitoringVolume:(NSInteger)volume

参数

参数描述
volume设置耳返音量,取值范围在 [0,100]。默认值为 100

返回

该方法在加入频道前后都能调用

Note

通话前⽹络测试

startEchoTest:

开始语⾳通话回路测试

- (int)startEchoTest: (int)intervalInSeconds;

参数

参数描述
intervalInSeconds返回语⾳通话回路测试结果的时间间隔,取值范围为 [2,10],单位 为秒

返回

Note

stopEchoTest

停止语⾳通话回路测试

- (int)stopEchoTest;

返回

startLastmileProbeTest:

开始通话前⽹络质量探测

- (int)startLastmileProbeTest:(CloudHubLastmileProbeConfig* _Nonnull)config;

参数

参数描述
Config测试参数,详⻅ CloudHubLiveTranscoding

返回

详情

开始通话前⽹络质量探测,向⽤户反馈上下⾏⽹络的带宽、丢包、⽹络抖动和 往返时延数据

启⽤该⽅法后,SDK 会依次返回如下 2 个回调:

Note

stopLastmileProbeTest

停止通话前⽹络质量探测

- (int)stopLastmileProbeTest;

返回

音频自采集(仅 Push 模式)

setExternalAudioSourceSampleRate:channels:

- (int) setExternalAudioSourceSampleRate:(int)sampleRate
                                channels:(int)channels;

设置采集数据的格式。

详情 该方法需要在加入频道前调用。

参数

参数描述
sampleRate指定返回数据的采样率,可设置为 8000、 16000、 32000、 44100 或 48000
channel指定 rtcEngine:onRecordAudioFrame:sampleRate:channels: 中返回数据的通道数,可设置为 1 或 2 (1: 单声道 2: 双声道)

返回

pushAudioFrame:

- (int) pushAudioFrame:(NSData * _Nonnull)buffer;

推送外部音频帧

参数

参数描述
buffer帧的有效数据

返回

音频自渲染(仅 Pull 模式)

setExternalAudioSinkSampleRate:channels:

- (int) setExternalAudioSinkSampleRate:(int)sampleRate
                              channels:(int)channels;

设置渲染数据的格式。

详情 该方法需要在加入频道前调用。

参数

参数描述
sampleRate指定返回数据的采样率,可设置为 8000、 16000、 32000、 44100 或 48000
channels指定 rtcEngine:onRecordAudioFrame:sampleRate:channels: 中返回数据的通道数,可设置为 1 或 2 (1: 单声道 2: 双声道)

返回

pullAudioFrame:

- (int) pullAudioFrame:(NSData * _Nonnull)buffer;

拉取播放(混音后)数据(一次拉取10ms数据)(用户需要持续以10ms间隔调用)。

调用该方法后,App 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。

参数

参数描述
buffer有效的帧数据

返回

原始音频数据

setRecordingAudioFrameSampleRate:channels:samples:

- (int) setRecordingAudioFrameSampleRate:(int)sampleRate
                                channels:(int)channel
                                 samples:(int)samplesPerCall;

设置IAudioFrameObaser::onRecordAudioFrame回调数据格式。 该方法设置 rtcEngine:onRecordAudioFrame:sampleRate:channels: 回调的采集音频格式。

详情 该方法需要在加入频道前调用。

参数

参数描述
sampleRate指定返回数据的采样率,可设置为 8000、 16000、 32000、 44100 或 48000
channel指定 rtcEngine:onRecordAudioFrame:sampleRate:channels: 中返回数据的通道数,可设置为 1 或 2 (1: 单声道 2: 双声道)
samplesPerCall返回数据的采样点数,如 RTMP/RTMPS 推流应用中通常为 1024

返回

setPlaybackAudioFrameSampleRate:channels:samples:

- (int) setPlaybackAudioFrameSampleRate:(int)sampleRate
                               channels:(int)channel
                                samples:(int)samplesPerCall;

设置IAudioFrameObaser::OnPlaybackAudioFrame回调数据格式。 该方法设置 rtcEngine:onPlaybackAudioFrame:sampleRate:channels: 回调的采集音频格式。

详情 该方法需要在加入频道前调用。

参数

参数描述
sampleRate指定返回数据的采样率,可设置为 8000、 16000、 32000、 44100 或 48000
channel指定 rtcEngine:onRecordAudioFrame:sampleRate:channels: 中返回数据的通道数,可设置为 1 或 2 (1: 单声道 2: 双声道)
samplesPerCall返回数据的采样点数,如 RTMP/RTMPS 推流应用中通常为 1024

返回

音频录制

startRecordingVoiceClip:duration:fileType:

开始录制声音片段

- (int)startRecordingVoiceClip:(NSString* _Nonnull) clipBaseName
                      duration:(NSInteger)clipDurationSeconds
                      fileType:(CloudHubMediaFileType) type;

参数

参数描述
clipBaseName声音片段basename
clipDurationSeconds每个声音片段时长
type录音文件的存放格式(0: ogg (opus) 1: wav),详见 CloudHubMediaFileType

返回

详情

调用成功后,用户会收到 rtcEngine:voiceClipFileReady:clip:ts: 回调。

stopRecordingVoiceClip:

停止录制声音片段

- (int)stopRecordingVoiceClip:(NSString* _Nonnull) clipBaseName;

参数

参数描述
clipBaseName声音片段basename

返回

摄像头控制

switchCamera:

切换前置/后置摄像头

- (int)switchCamera:(BOOL)front;

参数

参数描述
front是否使用前置摄像头(默认为 YES)

返回

详情

在调用 joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess: 之前也可以调用该方法

setCameraFlipMode

设置摄像头的翻转模式

- (int)setCameraFlipMode:(BOOL)horizontalFlip  Vertivcal:(BOOL)verticalFlip

参数

参数说明
horizontalFlip是否启用水平翻转
verticalFlip是否启用垂直翻转

返回

详情

该方法对摄像头采集的数据进行水平翻转(和/或)垂直翻转。对于同一个摄像头,关闭该摄像头后,引擎仍然会记住该摄像头的翻转设置,下次打开该摄像头后会自动加载之前的设置,除非用户通过 enableVideo: NO关闭过视频引擎。

correctCameraKeystoning

校正摄像头的梯形畸变

- (int)correctCameraKeystoning:(float)fromX FromY:(float)fromY ToX:(float)toX ToY:(float)toY

参数

参数说明
fromX,fromY本次校正的向量起点坐标
toX,toY本次校正的向量终点坐标

返回

详情

该方法通过增量交互的模式校正摄像头的梯形畸变。起点A(fromX,fromY)和终点B(toX,toY)构成的向量AB代表了本次校正的位移,相当于用户拖动鼠标从A移动到B,引擎会根据起点A的位置自动判断本次校正的角点是图片的哪个角点。

视图左上角和右下角的坐标为(0.0,0.0)和(1.0,1.0),视图划分为四个等分的1/4区域,分别为左上区、右上区、右下区、左下区。A点和B点必须位于视图的某个等分区域内,跨区域校正是无效的。

resetCameraKeystoning

取消校正摄像头的梯形畸变

- (int)resetCameraKeystoning

返回

详情

该方法禁用摄像头的梯形校正功能,恢复默认行为

流消息

sendStreamMessage:

- (int) sendStreamMessage:(NSData * _Nonnull)message;

发送数据流。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

成功调用该方法后,远端会触发 rtcEngine:onStreamMessagWithUid:data: 回调,远端用户可以在该回调中获取接收到的流消息。

参数

参数描述
message待发送的数据

返回

发布管理

setPublishStreamInfo:

设置发布本地音视频时用户自定义数据(Json字符串格式)

- (int)setPublishStreamInfo:(NSString * _Nonnull)info;

返回

详情

此方法必须在 rtcEngine:didJoinChannelwithUid:elapsed: 回调成功后,publishStream 之前调用。 如果远端成功订阅此视频流, 将会在收到 rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: 回调时,通过 streamInfo 参数通知远端。

publishStream

开始发布本地音视频

- (int)publishStream;

返回

详情

将自己的音视频发布到频道中,让其他人观看和收听,当发布成功后,本地会收到 rtcEngine:localVideoStateChangeWithState:error: 回调

Note

unPublishStream

停止发布本地音视频

- (int)unPublishStream;

返回

详情

停止发布自己的音视频,当停止发布后,本地会收到 rtcEngine:localVideoStateChangeWithState:error: 回调, 远端如果关闭了自动订阅,会收到 rtcEngine:onUserUnPublished:type:stream: 回调,另外不论远端是否关闭自动订阅,都会收到 rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: 回调

Note

手动订阅管理

subscribe

开始订阅一路音视频

- (int)subscribe:(NSString * _Nonnull)streamId;

参数

参数描述
streamId该路⾳视频流在频道内的唯⼀ Id,此 Id 可从 rtcEngine:onUserPublished:type:stream: 回调获得
返回

详情

请在收到 rtcEngine:onUserPublished:type:stream: 回调后调⽤

unSubscribe

取消订阅一路音视频

- (int)unSubscribe:(NSString * _Nonnull)streamId;

参数

参数描述
streamId该路⾳视频流在频道内的唯⼀ Id,此 Id 可从 rtcEngine:onUserPublished:type:stream: rtcEngine:onUserUnPublished:type:stream: 回调获得

返回

详情

服务器录制

startServerRecord

开始服务器录制

- (int) startServerRecord;

返回

stopServerRecord

停⽌服务器录制

- (int) stopServerRecord;

返回

pauseServerRecord

暂停服务器录制

- (int) pauseServerRecord;

返回

resumeServerRecord

恢复服务器录制

- (int) resumeServerRecord;

返回

⾼级信令⽅法

这些方法都必须在加入频道成功后调用

setPropertyOfUid:tell:properties:

为频道内某个用户设置自定义属性

- (int)setPropertyOfUid:(NSString * _Nonnull)uid 
                   tell:(NSString * _Nullable)whom 
             properties:(NSString * _Nonnull)prop;

参数

参数描述
uid目标用户的 uid,可以从 rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel: 回调中获得
tell要通知的用户,为空则通知频道内的所有人,如果指定某个用户的 uid,则只通知指定通知的用户,默认为空
prop自定义属性,必须是 json 对象

返回

详情

自定义属性有两种设置方法:

Note

sendChatMsg:to:withExtraData:

发送聊天消息

- (int)sendChatMsg:(NSString * _Nonnull)message 
                to:(NSString * _Nullable)whom 
     withExtraData:(NSString * _Nullable)extraData;

参数

参数描述
message聊天消息文本
whom要通知的用户,为空则通知频道内的所有人,如果指定某个用户的 uid,则只通知指定通知的用户
extraData该条消息自定义属性,必须是 json 对象,可以为空

返回

详情

通常可以使用 extraData 来传递一些字体、头像等信息
频道内的用户会收到 rtcEngine:onChatMessageArrival:from:withExtraData: 回调

pubMsg:msgId:to:withData:associatedWithUser:associatedWithMsg:save:extraData:

发布一条自定义消息

- (int)     pubMsg:(NSString * _Nonnull)msgName
             msgId:(NSString * _Nonnull)msgId
                to:(NSString * _Nullable)whom
          withData:(NSString * _Nullable)data
associatedWithUser:(NSString * _Nullable)uid
 associatedWithMsg:(NSString * _Nullable)assMsgID
              save:(BOOL)save
         extraData:(NSString * _Nullable)extra;

参数

参数描述
msgName消息名称
msgId消息 id,是一条消息在频道内的唯一标识
whom要通知的用户,为空则通知频道内的所有人,如果指定某个用户的 uid,则只通知指定通知的用户
data消息内容,必须是 json 字符串,可以为空
uid关联用户的 uid,一旦一条消息和一个用户关联,则该用户退出时,此条消息自动被删除
assMsgId关联消息的 id,一旦一条消息和另一条消息关联,则被关联的消息被删除时,此条消息自动被删除
save是否保存,如果保存,则之后进入频道的用户会在 rtcEngine:onPubMsg:msgId:from:withData:associatedWithUser:associatedWithMsg:ts:withExtraData:isHistory: 回调中收到这条信令,直至此条消息被用 delMsg:msgId:to: 方法删除
extra保留参数

返回

详情

pubMsg 机制类似于一个留言板,用于保存和同步频道内的业务状态,无论是已经在频道内的用户,还是之后新加入的用户,都可以通过 rtcEngine:onPubMsg:msgId:from:withData:associatedWithUser:associatedWithMsg:ts:withExtraData:isHistory: 回调收到当前频道内已经发布的自定义消息

delMsg:msgId:to:

删除一条自定义消息

- (int)delMsg:(NSString * _Nonnull)msgName
        msgId:(NSString * _Nonnull)msgId
           to:(NSString * _Nullable)whom;  

- (int)delMsg:(NSString * _Nonnull)msgName
        msgId:(NSString * _Nonnull)msgId
           to:(NSString * _Nullable)whom
     withData:(NSString * _Nullable)data;

参数

参数描述
msgName消息名
msgId要删除消息 id,通过 pubMsg:msgId:to:withData:associatedWithUser:associatedWithMsg:save:extraData: 方法发布消息时会指定其 id
whom要通知的用户,为空则通知频道内的所有人,如果指定某个用户的 uid,则只通知指定通知的用户
data保留参数

返回

详情

调用成功后,已经在频道内的用户,会收到 rtcEngine:onDelMsg:msgId:from:withData: 消息

Note

evictUser:reason:

将一个用户踢出频道

- (int)evictUser:(NSString * _Nonnull)uid 
          reason:(NSInteger)reason;

参数

参数描述
uid被踢用户的 uid
reason自定义字段

返回

详情

调用成功后,被踢用户会收到 rtcEngine:onLocalUserEvicted: 回调,其他用户会收到 rtcEngine:didOfflineOfUid:reason: 回调

CDN推流

addPublishStreamUrl:

增加推流地址

- (int) addPublishStreamUrl:(NSString* _Nonnull)url;

参数

参数描述
urlCDN 推流地址,格式为 RTMP,该字符串⻓度不能超过 1024 字节,URL 不⽀持中⽂等特殊字符

返回

removePublishStreamUrl:

删除推流地址

- (int) removePublishStreamUrl:(NSString* _Nonnull)url;

参数

参数描述
urlCDN 推流地址,格式为 RTMP,该字符串⻓度不能超过 1024 字节, URL 不⽀持中⽂等特殊字符

返回

setLiveTranscoding:

设置转码参数

- (int) setLiveTranscoding:(CloudHubLiveTranscoding* _Nonnull)transcoding;

参数

参数描述
transcoding转码参数,详⻅ CloudHubLiveTranscoding

返回

其他方法

getCallId

获取频道号

- (NSString * _Nullable)getCallId;

返回

getSdkVersion

获取sdk版本号

+ (NSString * _Nonnull)getSdkVersion;

返回

setLogFilter:

设置日志输出等级

- (int)setLogFilter:(NSUInteger)filter;

参数

参数描述
filter详见 CloudHubLogFilter

返回

getNativeHandle

获取 Native SDK Engine Handle

- (void *_Nullable)getNativeHandle;

详情

该方法获取 native SDK engineC++ handle,用于包括注册音视频帧观测器在内的特殊场景