CloudHubSDK Electron
频道管理
initialize
初始化 SDK 引擎。
rtcEngine.initialize ( appId ) ;
参数 | 说明 |
---|---|
appId | CloudHub 为 app 开发者提供的 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine |
详情
请在主线程调用 RtcEngine 类的接口方法。
setChannelProfile
设置频道场景。
rtcEngine.setChannelProfile ( profile ) ;
参数 | 说明 |
---|---|
profile | 频道场景,取值如下:0: ( 默认 ) 通信 1:直播 2:游戏 |
详情
RtcEngine 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
Note:
- 同频道内的用户必须使用同一种频道场景。
- 该方法必须在加入频道前调用,进入频道后无法再设置频道场景。
setClientRole
设置用户角色。
rtcEngine.setClientRole ( role ) ;
参数 | 说明 |
---|---|
role | 直播场景用户角色,取值如下:1:主播 2:观众 |
详情
加入频道前,用户需要通过本方法设置观众 ( 默认 ) 或主播角色。加入频道后,用户可以通过本方法切换用户角色。 如果在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 onClientRoleChanged 回调;远端会触发 onUserLeaved 和 onUserJoind 回调。
Note: 该方法仅适用于直播场景。
joinChannel
加入频道。
rtcEngine.joinChannel ( token,channelId,info,uid ) ;
参数 | 说明 |
---|---|
token | 开发者服务侧生成的 token 。如果对安全性要求不高,可以传空 |
channelId | 频道号 |
info | 用户自定义属性。会被同步给频道内的其他用户,必须是 json 字符串,可以传空 |
uid | 用户在频道内的唯一标识。必须是字母、数字的组合。如果传空,SDK 会自动生成一个 GUID 做为 uid ,并通过 onJoinChannel 回调告知,必须为 String |
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。 加入频道后,本地会触发 onJoinChannel 回调;通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。
Note: 频道内的各用户之间 uid 不能重复。如果重复,后面相同 uid 的用户进入时,会触发前面的用户自动离开频道。此时前面的用户会收到 onLocalUserEvicted 回调。
leaveChannel
离开频道。
rtcEngine.leaveChannel ( ) ;
详情
离开频道,即挂断或退出通话。
当调用 joinChannel 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用本方法。该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。 成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserLeaved 回调。
renewToken
更新 token。
rtcEngine.renewToken ( token ) ;
详情
该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。当以下任意一种情况发生时:
onRequestToken 回调;
App 应重新获取 Token,然后调用该 API 更新 Token,否则 SDK 将无法和服务器建立连接;
on
绑定监听事件。
rtcEngine.on ( "onJoinChannel",onJoinChannel ) ;
参数 | 说明 |
---|---|
event | 绑定的事件名称 |
callback | 绑定的事件监听器 |
Note:
需要在相应事件调用前进行监听 例如监听 joinchannel 回调 必须在调用 joinChannel 方法前 进行监听 rtcEngine.on ( “onJoinChannel”,onJoinChannel ) 这样在加入房间后才会有回调返回。
off
取消绑定监听事件。
rtcEngine.off ( "onJoinChannel",onJoinChannel ) ;
offAll
取消绑定 event 所有的监听事件。
rtcEngine.offAll ( "joinchannel" ) ;
音频管理
setAudioQuality
设置本地发送音频质量
int setAudioQuality( quality )
参数
参数 | 描述 |
---|---|
quality | 音频质量,详见 AUDIO_QUALITY |
返回
- 0: 成功
- 非0: 失败
adjustRecordingSignalVolume
调节麦克风采集信号音量, 该方法在加入频道前后都能调用。
rtcEngine.adjustRecordingSignalVolume(volume)
参数
参数 | 描述 |
---|---|
volume | number类型 0-400. 0: 静音 100:(默认)原始音量 400: 原始音量的 4 倍(自带溢出保护) |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量, 该方法在加入频道前后都能调用。
rtcEngine.adjustPlaybackSignalVolume(volume)
参数
参数 | 描述 |
---|---|
volume | number类型 0-400. 0: 静音 100:(默认)原始音量 400: 原始音量的 4 倍(自带溢出保护) |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户音量, 请在加入频道后,调用该方法。 你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的 音量,则需多次调用该方法。
rtcEngine.adjustUserPlaybackSignalVolume(uid, volume)
参数
参数 | 描述 |
---|---|
uid | string : 远端用户 ID |
volume | number类型 0-100. 0: 静音 100: 原始音量 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
enableLocalAudio
开/关本地音频采集。
rtcEngine.enableLocalAudio ( mute ) ;
参数 | 说明 |
---|---|
enable | true 开启本地语音采集 false 停止本地语音采集 |
详情
该方法不影响接收或播放远端音频流,enableLocalAudio ( false ) 适用于只听不发的用户场景。
muteLocalAudioStream
开/关本地音频发送。
rtcEngine.muteLocalAudioStream ( mute ) ;
参数 | 说明 |
---|---|
mute | true 停止本地音频发送 false 开启本地音频发送 |
详情
该方法用于允许/禁止向网络发送本地音频流。成功调用该方法后,远端会触发 onRemoteAudioStateChanged 回调 reason 为 5 ( 停止 ) /6 ( 发送 ) 。
Note:
该方法不影响录音状态,并没有禁用麦克风。
muteRemoteAudioStream
接收/停止接收指定的远端音频流。
rtcEngine.muteRemoteAudioStream ( uid,mute ) ;
参数 | 说明 |
---|---|
uid | 要操作的用户 id,必须为 String |
mute | 是否停止接收该用户的声音 |
详情
成功调用该方法后,本地会触发 onRemoteAudioStateChanged 回调,reason 为 5 ( 停止 ) /6 ( 发送 )
muteAllRemoteAudioStreams
接收/停止接收所有的远端音频流。
rtcEngine.muteAllRemoteAudioStreams ( mute ) ;
详情
成功调用该方法后,本地会触发 onRemoteAudioStateChanged 回调,reason 为 5 ( 停止 ) /6 ( 发送 )
视频管理
enableVideo
启用视频模块。
rtcEngine.enableVideo ( ) ;
详情
该方法用于启用视频模式。可以在加入频道前或者通话中调用,在加入频道前调用 enableVideo ( ) ,则自动开启视频模式
disableVideo
禁用视频模块
rtcEngine.disableVideo ( ) ;
详情
该方法用于禁用视频模式。
setVideoEncoderConfiguration
设置视频编码属性。
rtcEngine.setVideoEncoderConfiguration ( {width:100,height:100...} ) ;
参数 | 说明 |
---|---|
config | 视频编码属性配置项 参数如下: width :宽度 ( 类型: number ) height :高度 ( 类型: number ) frameRate :视频编码的帧率 ( fps ) 默认值为 15 ,建议不要超过 30 ( 类型: number ) bitrate :视频编码的码率 ( 类型: number ,单位 Kbps ) minFrameRate :最低帧率 ( 类型: number ) minBitrate :最低码率 ( 类型: number ) degradationPreference :带宽受限时 视频编码的降低偏好 ( 类型: number ) 取值如下: 0=降低编码帧率以保证视频质量 1= 降低视频质量以保证编码帧率 2=在编码帧率和视频质量之间保持平衡 orientationMode :视频旋转模式 ( 类型: number ) 取值如下:0=默认自适应;1=横屏模式;2=竖屏模式 deviceId: 可选,配置某一个视频的编码属性 ( 类型: string ) |
详情
该方法设置视频编码参数。所有设置的参数均为理想情况下的最大值。当视频引擎因设备、网络环境等原因无法达到设置的分辨率或帧率的最大值时,会取最接近最大值的那个值。 默认情况下,旋转模式为自适应,此时,如果采集的视频是横屏的 ( 宽大于高 ) ,则输出视频也是横屏,如果采集视频是竖屏的,则输出视频也是竖屏;如果旋转模式为横屏模式,则输出视频保持横屏,竖屏采集数据将被裁剪;如果旋转模式为竖屏,则输出视频保持竖屏,横屏采集数据将被裁剪。 在开启录制的情况下,旋转模式设置之后不应该改变。
setVideoMode
设置视频的显示模式。
rtcEngine.setVideoMode ( viewId: string, mode: number ) ;
参数 | 说明 |
---|---|
viewId | 显示视频的 dom 元素的 id |
mode | 显示模式 0 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉 1 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑 |
详情
播放视频后,可以调用该方法更新视频的显示模式。该方法只影响本地用户看到的视频画面,不影响本地发布的视频画面。
Note:
可以在通话中多次调用该方法。
setLocalVideoMirror
设置本地视频的镜像模式。
rtcEngine.setLocalVideoMirror ( mirror: boolean, options?: { viewId?: string }) ;
参数 | 说明 |
---|---|
mirror | 是否镜像 true 为镜像 false 为不镜像 |
options | 可选,其中 viewId 为显示视频的 dom 元素的 id |
详情
播放本地视频后,可以调用该方法更新本地视频的镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频画面。
Note:
可以在通话中多次调用该方法。
setupLocalVideo
开始播放本地视频。
rtcEngine.setupLocalVideo ( view: Element, options?: { deviceId?: string }) ;
参数 | 说明 |
---|---|
view | 盛放视频的 DOM 元素,该元素需要有 id |
options | 可选,其中 deviceId 为开始播放的摄像头 ID |
详情
调用该方法开始预览本地视频。需要预先调用 enableVideo 启动音频引擎, 再调用 enableLocalVideo(true) 开启本地视频采集。如果想要关闭本地视频采集,则可调用 enableLocalVideo(false)。开启本地视频采集后,可以调用该方法开始预览本地视频。
离开频道再次进入时,需要重新按照步骤调用方法才能再次开始预览本地视频。
Note:
如果你希望在通话中更新本地视频的显示或镜像模式,请使用 setVideoMode / setLocalVideoMirror 方法。
removeLocalVideo
停止播放本地视频。
rtcEngine.removeLocalVideo ( view: Element, options?: { deviceId?: string }) ;
参数 | 说明 |
---|---|
view | 本地视频的 DOM 元素 |
options | 可选,其中 deviceId 为停止播放的摄像头 ID |
setupRemoteVideo
开始播放远端视频。
rtcEngine.setupRemoteVideo ( uid: string, streamId: string, view: Element ) ;
参数 | 说明 |
---|---|
uid | 用户 ID,必须为 String |
streamId | 视频流 id (onRemoteVideoStateChanged 事件会返回 streamId) |
view | 显示视频的 dom 元素,该元素需要有 id |
详情
调用该方法开始播放远端视频。需要预先调用 enableVideo 启用视频引擎。
removeRemoteVideo
停止播放远端视频。
rtcEngine.removeRemoteVideo ( uid: string, streamId: string ) ;
参数 | 说明 |
---|---|
uid | 用户 ID,必须为 String |
streamId | 视频流 id |
enableLocalVideo
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
enableLocalVideo ( enable: boolean, options?: { deviceId?: string }) ;
详情
调用 enableVideo 后,本地视频即默认开启。你可以调用 enableLocalVideo ( false ) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo ( true ) 。
成功禁用或启用本地视频采集后。
参数 | 说明 |
---|---|
enable | true:开启本地视频采集和渲染 ( 默认 ) false:关闭本地视频采集和渲染。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流 |
options | 可选,其中 deviceId 为禁用或重新启用的摄像头 ID |
muteLocalVideoStream
发送/停止发送本地视频流。
rtcEngine.muteLocalVideoStream ( mute: boolean, options?: { deviceId?: string }) ;
参数 | 说明 |
---|---|
mute | true: 不发送本地视频流 false: 发送本地视频流 ( 默认 ) |
options | 可选,其中 deviceId 为发送/停止发送视频流对应的摄像头 ID |
详情
成功调用该方法后,远端会触发 onRemoteVideoStateChanged 回调,reason 为 5 ( 停止 ) /6 ( 发送 )
Note:
调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。该方法不影响本地视频流获取,没有禁用摄像头。
muteRemoteVideoStream
接收/停止接收指定的远端用户视频流。
rtcEngine.muteRemoteVideoStream(streamId, mute);
参数 | 说明 |
---|---|
streamId | 视频流id |
mute | true 不接收远端视频流 false 接收远端视频流(默认) |
详情
成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason 为 3 ( 停止 ) / 4 ( 发送 )
muteAllRemoteVideoStreams
是否接收/停止接收所有的远端用户视频流。
rtcEngine.muteAllRemoteVideoStreams ( mute ) ;
参数 | 说明 |
---|---|
mute | true: 不接收远端视频流 false: 接收远端视频流 ( 默认 ) |
详情
成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason 为 3 ( 停止 ) / 4 ( 发送 )
视频前处理及后处理
setBeautyEffectOptions
开启或关闭本地美颜功能,并设置美颜效果选项。
rtcEngine.setBeautyEffectOptions ( enable, options, deviceId = '' ) ;
参数 | 说明 |
---|---|
enable | boolean:是否开启 |
options | object:设置美颜选项。 options.lighteningContrastLevel: 0 | 1 | 2 对比度,与 lighteningLevel 搭配使用。取值越大,明暗对比越强烈 options.lighteningLevel: number 亮度,可用来实现美白等视觉效果。取值范围为 [0.0,1.0],其中 0.0 表示原始亮度,默认值为 0.7。 options.rednessLevel: number 红润度,可用来实现红润肤色等视觉效果。取值范围为 [0.0,1.0],其中 0.0 表示原始红润度,默认值为 0.1 options.smoothnessLevel: number 平滑度,可用来实现祛痘、磨皮等视觉效果。取值范围为 [0.0,1.0],其中 0.0 表示原始平滑等级,默认值为 0.5。 |
deviceId | string:摄像头 id |
setVideoEffectOptions
开启或关闭高级美颜功能,并设置美颜效果选项。
rtcEngine.setVideoEffectOptions ( enable, options, deviceId = '' ) ;
参数 | 说明 |
---|---|
enable | boolean:是否开启 |
options | object:设置美颜选项。 options.sharpLevel: number 锐化,取值范围为 [0.0,1.0],其中 0.0 表示原始效果,默认值为 0.5。可用来实现锐化等视觉效果 options.thinFaceLevel: number 瘦脸,取值范围为 [0.0,1.0],其中 0.0 表示原始效果,默认值为 0.5。可用来实现瘦脸等视觉效果 options.bigEyesLevel: number 大眼,取值范围为 [0.0,1.0],其中 0.0 表示原始效果,默认值为 0.5。可用来实现大眼等视觉效果 options.sticker: number 贴纸 1-公主面具 2-黑猫眼镜 3-卡通男孩 4-卡通女孩 5-搞怪宝宝 6-圣诞麋鹿 7-生日快乐 8-甜甜甜筒 9-招财猫 10-可爱猪猪 options.portraitBackground 虚拟背景 0-无 1-蓝天 2-草坪 3-白墙 |
deviceId | string:摄像头 id |
详情
成功调用该方法后会返回一个 number,
- 0:方法调用成功
- < 0:方法调用失败
多频道管理
createChannel
创建并获取一个 IChannel 对象。
你可以多次调用该方法,创建多个 IChannel 对象,再调用各 IChannel 对象中的 joinChannel 方法,实现同时加入多个频道。
加入多个频道后,你可以同时订阅各个频道的音、视频流;但是同一时间只能在一个频道发布一路音、视频流。
virtual IChannel* createChannel ( const char * channelId )
参数
参数 | 描述 |
---|---|
channelId | 标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围 ( 共 89 个字符 ) : • 26 个小写英文字母 a~z • 26 个大写英文字母 A~Z • 10 个数字 0~9 • 空格 • “!"、"#"、"$"、"%"、"&"、” ( “、” ) “、"+"、"-"、":"、";"、"<"、"="、”."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、" |
返回
- 方法调用成功,返回 IChannel 对象的指针
- 方法调用失败,返回一个空指针 NULL
- 如果将 channelId 设为空字符 “",SDK 会返回 ERR_REFUSED ( 5 )
详情
- 该参数没有默认值,请确保对参数设值。
- 请勿将该参数设为空字符 “",否则 SDK 会返回 ERR_REFUSED ( 5 )
桌面分享相关方法
getScreenDisplaysInfo
获取屏幕信息 该方法获取系统 ( macOS 或 Windows ) 屏幕 ID,以及相关信息。你可以使用获取到的屏幕 ID 进行屏幕共享。无需关注返回对象的具体内容,直接使用它进行屏幕共享即可。
console.log ( rtcEngine.getScreenDisplaysInfo ( )) ;
getScreenWindowsInfo
获取窗口信息 该方法获取系统 ( macOS 或 Windows ) 窗口 ID,以及相关信息。无需关注返回对象的具体内容,直接使用获取到的窗口 ID 当做 startScreenCaptureByDisplayId 中 excludeWindow 的参数 具体参考 startScreenCaptureByDisplayId。
console.log ( rtcEngine.getScreenWindowsInfo ( )) ;
startScreenCaptureByDisplayId
开始桌面分享。
rtcEngine.startScreenCaptureByDisplayId ( displayId,excludeWindow... ) ;
参数 | 说明 |
---|---|
displayId | 屏幕 id 根据 getScreenDisplaysInfo 获取的 displayId |
excludeWindow | 不分享的窗口 根据 getScreenWindowsInfo 获取的 windowId |
framerate | 帧率 fps |
bitrate | 码率 kbps |
isCaptrueCursor | 是否捕获鼠标 |
返回值
- -1 开始桌面分享失败
- 0 开始桌面分享成功
- 5 拒绝桌面分享
startScreenCaptureByWindowId
通过窗口信息共享屏幕
rtcEngine.startScreenCaptureByWindowId ( windowId,excludeWindow... ) ;
参数 | 说明 |
---|---|
windowId | 共享的 windowId |
excludeWindow | 不共享的窗口 id 只能不共享一个窗口 ( 默认为 0 ) |
framerate | 帧率 ( 默认为 5 ) |
bitrate | 码率 ( 默认为 1200 ) |
isCaptrueCursor | 是否捕获鼠标 ( 默认为 false ) |
返回值
- -1 通过窗口信息共享屏幕失败
- 0 通过窗口信息共享屏幕成功
- 5 拒绝通过窗口共享屏幕
stopScreenCapture
停止桌面分享。
rtcEngine.stopScreenCapture ( ) ;
startSpeakerCaptureWhileSharing
共享桌面时开启桌面声音
rtcEngine.startSpeakerCaptureWhileSharing ( ) ;
stopSpeakerCaptureWhileSharing
共享桌面时关闭桌面声音
rtcEngine.stopSpeakerCaptureWhileSharing ( ) ;
音乐文件播放
startPlayMovie
开始播放一个音乐文件。
rtcEngine.startPlayMovie ( ) ;
参数 | 说明 |
---|---|
mediaFile | 音乐文件的路径,可以是本地文件,也可以是 http 路径 ( 暂时不支持 https 协议 ) |
loopback | 是否只给自己听 |
cycle | 播放完毕后是否自动从头开始。默认为 false |
paused | 可选,表示是否开始后立即暂停 |
stopPlayMovie
停止播放一个音乐文件。
rtcEngine.stopPlayMovie ( ) ;
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
pausePlayMovie
暂停播放一个音乐文件。
rtcEngine.pausePlayMovie ( mediafile ) ;
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
resumePlayMovie
恢复播放一个音乐文件。
rtcEngine.resumePlayMovie ( mediafile ) ;
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
setupLocalMovie
本地观看自己播放的音乐文件。
rtcEngine.setupLocalMovie ( ) ;
参数 | 说明 |
---|---|
view | 显示电影的 dom 元素,该元素需要有 id |
mediaFile | 音乐文件的路径,可以是本地文件,也可以是 http 路径 ( 暂时不支持 https 协议 ) |
Note:
需要在调用 startPlayMovie 后调用此方法才会生效
removeLocalMovie
取消观看自己播放的音乐文件。
rtcEngine.removeLocalMovie ( ) ;
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
Note:
调用此方法不影响别人观看
setMoviePosition
设置音乐的当前进度
rtcEngine.setMoviePosition ( mediafile,pos ) ;
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
pos | 要移动的目标时间,以毫秒为单位 |
getMovieCurrentPosition
获取媒体当前播放时长
int64_t getMovieCurrentPosition ( const char* mediafile )
参数
参数 | 描述 |
---|---|
mediafile | 媒体路径 |
返回
媒体当前播放时长
getMovieInfo
获取媒体属性
int getMovieInfo ( const char* mediafile,
bool& hasAudio,
bool& hasVideo )
参数
参数 | 描述 |
---|---|
mediafile | 媒体路径 |
hasAudio | 是否有音频 |
hasVideo | 是否有视频 |
返回
- 0: 成功
- 非 0: 失败
getMovieDuration
获取电影时长。
rtcEngine.getMovieDuration ( mediaFile ) ;
参数 | 说明 |
---|---|
mediaFile | string:电影路径 |
详情
成功调用该方法后会返回一个 number
⾳效文件播放
getEffectsVolume
获取播放音效文件音量。
rtcEngine.getEffectsVolume ( ) ;
setEffectsVolume
设置播放音效文件音量。
rtcEngine.setEffectsVolume ( volume ) ;
参数 | 说明 |
---|---|
volume | 音效文件的音量。取值范围为 [0.0,100.0],100.0 为默认值,表示原始音量。 |
setVolumeOfEffect
设置单个音效文件的音量。
rtcEngine.setVolumeOfEffect ( soundId, volume ) ;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
volume | 音效文件的音量。取值范围为 [0.0,100.0]。100.0 为默认值 |
playEffect
播放指定音效文件。
该方法播放指定的本地或在线音效文件。你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益,以及远端用户是否能听到该音效。
你可以多次调用该方法,通过传入不同的音效文件的 soundID 和 filePath,同时播放多个音效文件,实现音效叠加。为获得最佳用户体验,我们建议同时播放的音效文件不要超过 3 个。
调用该方法播放音效结束后,SDK 会触发 audioEffectFinished 回调。
rtcEngine.playEffect ( soundId, filePath, loopcount, gain, publish, startTimeMS, endTimeMS ) ;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
filePath | 指定音效文件的绝对路径或 URL 地址 ( 包含文件后缀名 ) 。支持的音频格式包括:mp3、mp4、m4a、aac、3gp、mkv 及 wav |
loopcount | 设置音效循环播放的次数:0:播放音效一次1:播放音效两次-1:无限循环播放音效,直至调用 stopEffect 或 stopAllEffects 后停止 |
gain | 设置是否改变单个音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0。取值越小,则音效的音量越低 |
publish | 设置是否将音效传到远端:true:音效在本地播放的同时,会发布到云上,因此远端用户也能听到该音效false:音效不会发布到云上,因此只能在本地听到该音效 |
startTimeMS | 设置开始播放的时间 ( 毫秒 ) ,⽂件将从该处开始播放。 |
endTimeMS | 设置结束播放的时间 ( 毫秒 ) ,⽂件播放到该处时将结束。 |
stopEffect
停止播放指定音效文件。
rtcEngine.stopEffect ( soundId ) ;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
stopAllEffects
停止播放所有音效文件。
rtcEngine.stopAllEffects ( ) ;
preloadEffect
预加载音效文件。
rtcEngine.preloadEffect ( soundId: number, filePath: string ) : number;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
filePath | 音效文件的绝对路径 |
unloadEffect
释放音效文件。
rtcEngine.unloadEffect ( soundId: number ) : number;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
pauseEffect
暂停音效文件播放。
rtcEngine.pauseEffect ( soundId ) ;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
pauseAllEffects
暂停所有音效文件播放
rtcEngine.pauseAllEffects ( ) ;
resumeEffect
恢复播放指定音效文件。
rtcEngine.resumeEffect ( soundId ) ;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
resumeAllEffects
恢复播放指定音效文件。
rtcEngine.resumeAllEffects ( ) ;
人声效果
setLocalVoicePitch
设置本地语音音调
rtcEngine.setLocalVoicePitch ( pitch ) ;
参数
参数 | 描述 |
---|---|
pitch | number: 语音频率。可以在 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调 |
返回
- 0: 成功
- 非 0: 失败
setLocalVoiceEqualization
设置本地语音音效均衡
rtcEngine.setLocalVoiceEqualization ( bandFrequency, bandGain )
参数
参数 | 描述 |
---|---|
bandFrequency | 频谱子带索引,取值范围是 [0,7],分别代表 8 个 频带,对应的中心频率是 [70 150 250 500 1000 2000 4000 8000] Hz,详见 AUDIO_EQUALIZATION_BAND_FREQUENCY 。 |
gain | number: 增益 ( dB ) 。取值范围是 [-15,15],默认值为 0 |
返回
- 0: 成功
- 非 0: 失败
setLocalVoiceReverb
设置本地音效混响
rtcEngine.setLocalVoiceReverb ( reverbKey, value ) ;
参数
参数 | 描述 |
---|---|
reverbType | 混响音效类型,详见 AUDIO_REVERB_TYPE |
value | number: 设置混响音效的效果数值,各混响音效对应的取值范围请参考 AUDIO_REVERB_TYPE |
返回
- 0: 成功
- 非 0: 失败
setAudioEffectPreset
设置 SDK 预设的人声音效。
rtcEngine.setAudioEffectPreset ( preset ) : number
参数
参数 | 描述 |
---|---|
preset | 预设的音效选项,详见 AUDIO_EFFECT_PRESET |
返回
- 0: 成功
- 非 0: 失败
enableDeepLearningDenoise
开启或关闭 AI 降噪模式。
rtcEngine.enableDeepLearningDenoise ( enabled ) ;
参数
参数 | 描述 |
---|---|
enabled | 是否开启 AI 降噪模式: true: ( 默认 ) 开启。 false: 关闭。 |
返回
- 0: 成功
- 非 0: 失败
CDN 推流
addPublishStreamUrl
增加旁路推流地址。
调用该方法后,SDK 会在本地触发 streamPublished 回调,报告增加旁路推流地址的状态。
rtcEngine.addPublishStreamUrl ( url ) ;
参数 | 说明 |
---|---|
url | CDN 推流地址,格式为 RTMP。该字符长度不能超过 1024 字节,且不支持中文等特殊字符。 |
Note:
该方法仅适用于直播场景下的主播,请在加入频道后调用该方法。
1. 确保已开通旁路推流的功能。
2. 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
removePublishStreamUrl
删除旁路推流地址。
调用该方法后,SDK 会在本地触发 streamUnpublished 回调,报告删除旁路推流地址的状态。
rtcEngine.removePublishStreamUrl ( url: string ) ;
参数 | 说明 |
---|---|
url | 待删除的推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。 |
Note:
该方法只适用于直播场景下的主播。
1. 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
2. 推流地址不支持中文等特殊字符。
setLiveTranscoding
设置直播转码。
调用该方法更新 transcoding 参数时,SDK 会触发 transcodingUpdated 回调。
rtcEngine.setLiveTranscoding ( transcoding: TranscodingConfig ) ;
参数 | 说明 |
---|---|
transcoding | 旁路推流转码合图相关设置,详见 demo 实例 |
跨频道媒体流转发 ( 仅适用于互动直播 )
startChannelMediaRelay
开始跨频道媒体流转发,该方法可用于实现跨频道连麦等场景
rtcEngine.startChannelMediaRelay ( config ) ;
参数 | 说明 |
---|---|
config | config 属性有: name, data data 的属性有:action, destChannelInfos data.action: ‘start’ / ‘update’ / ‘stop’ data.destChannelInfos: data.destChannelInfos 中的 key 为目标频道 id, value 有属性 uid ( 转发到目标频道时使用的 UID【注意:不能与目标频道的用户 ID 相同,传 0 则服务器会自动生成一个随机 ID 】 ) |
详情
如果你希望将流转发到多个目标频道,data.destChannelInfos 中可添加多个 key ,成功调用该方法后,本频道 SDK 会触发 channelMediaRelayStateChanged 回调,并在回调中报告当前的跨频道媒体流转发状态。目标频道会收到 onUserJoined 回调,
updateChannelMediaRelay
更新媒体流转发的频道
rtcEngine.updateChannelMediaRelay ( config ) ;
参数 | 说明 |
---|---|
config | config 属性有: name, data name: ‘ChannelMediaRelayControl’ data 的属性有:action, destChannelInfos data.action: ‘start’ / ‘update’ / ‘stop’ data.destChannelInfos: data.destChannelInfos 中的 key 为目标频道 id, value 有属性 uid ( 转发到目标频道时使用的 UID【注意:不能与目标频道的用户 ID 相同,传 0 则服务器会自动生成一个随机 ID 】 ) |
详情
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以 调用该方法。
stopChannelMediaRelay
停止跨频道媒体流转发。
rtcEngine.stopChannelMediaRelay ( ) ;
详情
一旦停止,主播会退出所有目标频道。
音量提示
enableAudioVolumeIndication
启用/禁用说话者音量提示。
rtcEngine.enableAudioVolumeIndication ( interval ) ;
参数 | 说明 |
---|---|
interval | type: number指定音量提示的时间间隔:<= 0: 禁用音量提示功能> 0: 提示间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。启用该方法后,无论频道内是否有人说话,都会在 onAudioVolumeIndication 回调中按设置的时间间隔返回音量提示 |
smooth | type: number, 可选平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑 |
reportVad | type: boolean, 可选• true: 开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声 • false: 默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声 |
视频双流模式
enableDualStreamMode
开启或关闭大小流功能
rtcEngine.enableDualStreamMode ( isOpen ) ;
参数 | 说明 |
---|---|
isOpen | isOpen 是 boolean 类型,true:开启,false:关闭 |
setRemoteDefaultVideoStreamType
设置默认订阅的视频流类型
rtcEngine.setRemoteDefaultVideoStreamType ( type ) ;
参数 | 说明 |
---|---|
type | type 是 number 类型,0 代表大流,1 代表小流 |
setRemoteVideoStreamType
设置订阅的视频流类型
rtcEngine.setRemoteVideoStreamType ( uid, streamType ) ;
参数 | 说明 |
---|---|
uid | uid 是 string 类型,是用户 ID |
streamType | streamType 是 number 类型,视频流类型, 0 代表大流,1 代表小流 |
通话前网络测试
startLastmileProbeTest
开始通话前网络质量探测。
rtcEngine.startLastmileProbeTest ( config: LastmileProbeConfig ) ;
详情
启用该方法后,SDK 会向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。SDK 会一次返回如下两个回调:
- lastMileQuality:视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- lastmileProbeResult:视网络情况约 30 秒内返回。该回调通过客观数据反馈上下行网络质量,因此更客观。
该方法主要用于以下两种场景:
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
Note:
该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要同时使用该方法和 enableLastmileTest。
1. 调用该方法后,在收到 lastMileQuality 和 lastmileProbeResult 回调之前请不用调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
2. 直播场景下,如果本地用户为主播,请勿在加入频道后调用该方法。
stopLastmileProbeTest
停止通话前 last mile 网络质量探测。
rtcEngine.stopLastmileProbeTest ( ) ;
音频播放设备管理
setAudioPlaybackDevice
设置扬声器。
rtcEngine.setAudioPlaybackDevice ( deviceId ) ;
参数 | 说明 |
---|---|
deviceId | 扬声器 id ( getAudioPlaybackDevices ( ) 中返回的扬声器 id ) |
getAudioPlaybackDevices
获取扬声器列表。
console.log ( rtcEngine.getAudioPlaybackDevices ( )) ;
返回参数 | 说明 |
---|---|
devicename | 扬声器名称 |
deviceid | 扬声器 Id |
getCurrentAudioPlaybackDevice
获取当前扬声器。
console.log ( rtcEngine.getCurrentAudioPlaybackDevice ( ))
参数 | 说明 |
---|---|
devicename | 扬声器名称 |
deviceid | 扬声器 Id |
setAudioPlaybackDeviceMute
静音/取消静音音频播放设备
rtcEngine.setAudioPlaybackDeviceMute( mute )
参数
参数 | 描述 |
---|---|
mute | boolean值,true-静音 false-取消静音 |
getAudioPlaybackDeviceMute
获取音频播放设备的静音状态
rtcEngine.getAudioPlaybackDeviceMute()
setAudioPlaybackVolume
设置音频播放设备的音量
rtcEngine.setAudioPlaybackVolume(volume)
参数
参数 | 描述 |
---|---|
volume | number类型 0-255 |
getAudioPlaybackVolume
获取音频播放设备的音量
rtcEngine.getAudioPlaybackVolume()
返回
- volume 0-255
startAudioPlaybackDeviceTest
开始扬声器检测。
rtcEngine.startAudioPlaybackDeviceTest ( deviceId,filePath,options ) ;
参数 | 说明 |
---|---|
deviceId | 需要检测的扬声器 id ( getAudioPlaybackDevices ( ) 会返回所有扬声器信息 ) |
filePath | 播放的音频文件 需要绝对路径 |
options | 配置项 loop 是否循环播放 |
stopAudioPlaybackDeviceTest
停止扬声器检测。
rtcEngine.stopAudioPlaybackDeviceTest ( ) ;
startAudioDeviceLoopbackTest
开始音频设备回路测试。该方法测试本地的音频设备是否正常工作。
注:该方法仅在本地进行音频设备测试,不涉及网络连接。
rtcEngine.startAudioDeviceLoopbackTest ( interval ) ;
参数
参数 | 说明 |
---|---|
interval | 时间间隔 ( 单位:ms 默认 200ms ) |
返回
- 0: 成功
- 非0: 失败
stopAudioDeviceLoopbackTest
停止音频设备回路测试。
rtcEngine.stopAudioDeviceLoopbackTest ( ) ;
返回
- 0: 成功
- 非0: 失败
音频采集设备管理
setAudioRecordingDevice
设置麦克风。
rtcEngine.setAudioRecordingDevice ( deviceId ) ;
参数 | 说明 |
---|---|
deviceId | 麦克风 id ( getAudioRecordingDevices ( ) 中返回的麦克风 id ) |
getAudioRecordingDevices
获取麦克风列表。
console.log ( rtcEngine.getAudioRecordingDevices ( )) ;
返回参数 | 说明 |
---|---|
devicename | 麦克风名称 |
deviceid | 麦克风 Id |
getCurrentAudioRecordingDevice
获取当前麦克风。
console.log ( rtcEngine.getCurrentAudioRecordingDevice ( ))
参数 | 说明 |
---|---|
devicename | 麦克风名称 |
deviceid | 麦克风 Id |
setAudioRecordingDeviceMute
静音/取消静音录音设备
rtcEngine.setAudioRecordingDeviceMute(mute)
参数
参数 | 描述 |
---|---|
mute | boolean值,true-静音 false-取消静音 |
getAudioRecordingDeviceMute
获取录音设备的静音状态
rtcEngine.getAudioRecordingDeviceMute()
返回
- true / false
setAudioRecordingVolume
设置录音设备的音量
rtcEngine.setAudioRecordingVolume(volume)
参数
参数 | 描述 |
---|---|
volume | number类型 0-255 |
getAudioRecordingVolume
获取录音设备的音量
rtcEngine.getAudioRecordingVolume()
返回
- volume 0-255
startAudioRecordingDeviceTest
开始麦克风检测。
rtcEngine.startAudioRecordingDeviceTest ( deviceId,interval ) ;
参数 | 说明 |
---|---|
deviceId | 需要检测的麦克风 id ( getAudioRecordingDevices ( ) 会返回所有麦克风信息 ) |
interval | 返回音量的间隔 ( 单位:ms 默认 200ms ) |
stopAudioRecordingDeviceTest
停止麦克风检测。
rtcEngine.stopAudioRecordingDeviceTest ( ) ;
视频设备管理
enableMultiStream
启用多摄像头
rtcEngine.enableMultiStream ( enable: boolean ) ;
参数 | 说明 |
---|---|
enable | true 开启 false 关闭 |
setVideoDevice
设置摄像头。
rtcEngine.setVideoDevice ( deviceId ) ;
参数 | 说明 |
---|---|
deviceId | 摄像头 id ( getVideoDevices ( ) 中返回的摄像头 id ) |
getVideoDevices
获取摄像头列表。
console.log ( rtcEngine.getVideoDevices ( )) ;
返回参数 | 说明 |
---|---|
devicename | 摄像头名称 |
deviceid | 摄像头 Id |
getCurrentVideoDevice
获取当前摄像头。
console.log ( rtcEngine.getCurrentVideoDevice ( )) ;
返回参数 | 说明 |
---|---|
devicename | 摄像头名称 |
deviceid | 摄像头 Id |
startVideoDeviceTest
开始摄像头检测。
rtcEngine.startVideoDeviceTest ( deviceId,view,onCallback ) ;
参数 | 说明 |
---|---|
deviceId | 需要检测的摄像头 id ( getVideoDevices ( ) 会返回所有摄像头信息 ) |
view | 显示视频的 dom 元素 |
onCallback | 开始检测后的回调函数 |
stopVideoDeviceTest
停止摄像头检测。
rtcEngine.stopVideoDeviceTest ( ) ;
发布管理
publish
开始发布本地音视频。
rtcEngine.publish ( options?: { deviceId?: string, streamInfo?: {} }) ;
参数 | 说明 |
---|---|
options | 可选,其中有以下值:deviceId: 可选, 要发布的摄像头 IDstreamInfo: 可选, 需要携带的自定义数据 |
详情
将自己的音视频发布到频道中,让其他人观看和收听。发布成功后,本地会收到 onLocalVideoStateChanged 回调。远端会收到 onRemoteVideoStateChanged 回调
Note:
只有在加入频道成功后,才能调用此方法。
unPublish
停止发布本地音视频。
rtcEngine.unPublish ( options?: { deviceId?: string }) ;
参数 | 说明 |
---|---|
options | 可选,其中 deviceId 为停止发布的摄像头 ID |
详情
停止发布自己的音视频。停止发布后,本地会收到 onLocalVideoStateChanged 回调。远端如会收到 onRemoteVideoStateChanged 回调。
Note:
只有在加入频道成功后,才能调用此方法。
录制相关方法
startServerRecord
开始录制
rtcEngine.startServerRecord ( ) ;
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
stopServerRecord
停止录制
rtcEngine.stopServerRecord ( ) ;
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
pauseServerRecord
暂停录制
rtcEngine.pauseServerRecord ( ) ;
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
resumeServerRecord
恢复录制
rtcEngine.resumeServerRecord ( ) ;
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
设备相关方法
高级信令方法
Note:
这些方法都必须在加入频道成功后调用。
setProperty
为频道内某个用户设置自定义属性。
rtcEngine.setProperty ( uid,toId,prop ) ;
参数 | 说明 |
---|---|
uid | 目标用户的 uid,必须为 String |
toId | 要通知的用户。为空则通知频道内的所有人。如果指定某个用户的 uid ,则只通知指定的用户。默认为空 |
prop | 自定义属性,必须是 json 字符串 |
详情
自定义属性有两种设置方法:
- 用户加入频道时,在 joinChannel 中指定 properties ;
- 用户加入频道后,调用 setProperty ,则用户会收到 onSetProperty 回调。
设置成功后,被通知的用户和被设置的用户都会收到通知。除此以外,新进入频道的用户也会在 onUserJoined 回调中获得该用户的这些属性。
Note:
- 如果多次指定相同用户的不同属性,则这些属性都会被记录,并通过 onUserJoined 回调发送给之后新进入频道的用户。
- 如果多次指定相同用户的相同属性,则后设置的属性会覆盖之前设置的属性。比如为用户 A 重复设置两次,分别传入{ “test」: true }和{ “test」: false },则新进入频道的用户 B,在收到关于用户 A 的 onUserJoined 回调中,会得到用户 A 的属性{ “test」: false }。
sendChatMsg
发送聊天消息。
rtcEngine.setChatMsg ( toId,message,extraData ) ;
参数
参数 | 说明 |
---|---|
toId | 要通知的用户。为空则通知频道内的所有人。如果指定某个用户的 uid ,则只通知指定通知的用户 |
message | 聊天消息文本 |
extraData | 该条消息自定义属性。必须是 json 字符串。可以为空 |
详情
通常可以使用 extraData 来传递一些字体、头像等信息。 频道内的用户会收到 onChatMsg 回调。
pubMsg
发布一条自定义消息。
rtcEngine.pubMsg ( msgName,msgId... ) ;
参数 | 说明 |
---|---|
msgName | 消息名称 |
msgId | 消息 id ,是一条消息在频道内的唯一标识 |
toId | 要通知的用户。有以下值: ‘__all’: 发送信息给频道中的所有人 ‘__allExceptSender’: 发送信息给除自己以外的频道中所有人 ‘__none’: 只发送信息到信令服务器,不发给任何人 userId: 某用户 ID。Note: 只发送信息给此用户 |
data | 消息内容。需要是 json 对象 |
associatedUserId | 关联用户的 uid ,一旦一条消息和一个用户关联,则该用户退出时,此条消息自动被删除 |
associatedMsgId | 关联消息的 id ,一旦一条消息和另一条消息关联,则被关联的消息被删除时,此条消息自动被删除 |
save | 是否保存。如果保存,则之后进入频道的用户会在 onPubMsg 回调中收到这条信令,直至此条消息被用 delMsg 方法删除 |
extendInfo | 保留参数 |
详情
pubMsg 机制类似于一个留言板,用于保存和同步频道内的业务状态。无论是已经在频道内的用户,还是之后新加入的用户,都可以通过 pubMsg 回调收到当前频道内已经发布的自定义消息。
Note:
只有 toId 为 ‘__all’ 或者 ‘__allExceptSender’, 并且 save 为 true 时录制回放里才会保存该消息
delMsg
删除一条自定义消息。
rtcEngine.delMsg ( msgName,msgId... ) ;
参数 | 说明 |
---|---|
msgName | 消息名称 |
msgId | 要删除消息 id 。通过 pubMsg 方法发布消息时会指定其 id |
toId | 要通知的用户。为空则通知频道内的所有人。如果指定某个用户的 uid,则只通知指定通知的用户。 |
data | 保留参数 |
详情
调用成功后,已经在频道内的用户,会收到 onDelMsg 消息。
Note:
删除一条不存在的消息会失败。
evictUser
将一个用户踢出频道。
rtcEngine.evictUser ( uid,reason ) ;
参数 | 说明 |
---|---|
uid | 被踢用户的 uid,必须为 String |
reason | 自定义字段 |
详情
调用成功后,被踢用户会收到 onLocalUserEvicted 回调。其他用户会收到 onUserLeaved 回调。
其他方法
getVersion
获取 SDK 版本号。
rtcEngine.getVersion ( ) ;