CloudHubSDK Electron
频道管理
initialize
初始化 SDK 引擎。
rtcChannel.initialize(appId);
参数 | 说明 |
---|---|
appId | CloudHub 为 app 开发者提供的 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 rtcChannel |
详情
请在主线程调用 rtcChannel 类的接口方法。
setClientRole
设置用户角色。
rtcChannel.setClientRole(role);
参数 | 说明 |
---|---|
role | 直播场景用户角色,取值如下:1:主播 2:观众 |
详情
加入频道前,用户需要通过本方法设置观众(默认)或主播角色。加入频道后,用户可以通过本方法切换用户角色。 如果在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 onClientRoleChanged 回调;远端会触发 onUserLeaved 和 onUserJoind 回调。
Note: 该方法仅适用于直播场景。
setChannelProfile
设置频道场景。
rtcChannel.setChannelProfile(profile);
参数 | 说明 |
---|---|
profile | 频道场景,取值如下:0:(默认)通信 1:直播 2:游戏 |
详情
rtcChannel 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
Note:
- 同频道内的用户必须使用同一种频道场景。
- 该方法必须在加入频道前调用,进入频道后无法再设置频道场景。
joinChannel
加入频道。
rtcChannel.joinChannel(token,info,uid,channelMediaOptions);
参数 | 说明 |
---|---|
token | 开发者服务侧生成的 token 。如果对安全性要求不高,可以传空 |
info | 用户自定义属性。会被同步给频道内的其他用户,必须是json字符串,可以传空 |
uid | 用户在频道内的唯一标识。必须是字母、数字的组合。如果传空,SDK会自动生成一个 GUID 做为 uid ,并通过 onJoinChannel 回调告知,必须为 String |
channelMediaOptions | 频道媒体设置选项: autoSubscribeAudio:设置是否自动订阅频道内所有远端音频流: •true: (默认)订阅 •false: 不订阅 •该成员功能与 muteAllRemoteAudioStreams 相同。加入频道后, 你可以通过 muteAllRemoteAudioStreams 方法重新设置是否订阅频道内的远端音频流。 autoSubscribeVideo:设置是否自动订阅频道内所有远端视频流: •true: (默认)订阅 •false: 不订阅 •该成员功能与 muteAllRemoteVideoStreams 相同。加入频道后, 你可以通过 muteAllRemoteVideoStreams 方法重新设置是否订阅频道内的远端音频流。 publishLocalAudio:设置是否在频道内发布本地音频流: •true: 发布 •false: (默认)不发布 publishLocalVideo: 设置是否在频道内发布本地视频流: •true: 发布 •false: (默认)不发布 |
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。 加入频道后,本地会触发 onJoinChannel 回调;通信场景下的用户和直播场景下的主播加入频道后,远端会触发onUserJoined 回调。
Note: 频道内的各用户之间 uid 不能重复。如果重复,后面相同 uid 的用户进入时,会触发前面的用户自动离开频道。此时前面的用户会收到 onLocalUserEvicted 回调。
当设置了自动发布音频(publishLocalAudio为true)或者自动发布视频(publishLocalVideo为true)时, 自动发布功能被起用。
当自动发布功能起用时, 如果音频流或者视频流没有被自动发布(publishLocalAudio为false或者publishLocalVideo为false),其状态为muted(相当于调用了muteLocalAudioStream/muteLocalVideoStream并传递参数为true)。
当自动发布功能起用时, 你可以通过 muteLocalAudioStream/muteLocalVideoStream 方法重新设置是否在频道内发布本地音频流。
单流模式下: 当自动发布功能起用时, 在unPublish方法被调用前,SDK将不再相应publish方法。
多流模式下: 将只发布一路摄像头(设备枚举结果中index为0的设备)。
leaveChannel
离开频道。
rtcChannel.leaveChannel();
详情
离开频道,即挂断或退出通话。
当调用 joinChannel 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用本方法。该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。 成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserLeaved 回调。
renewToken
更新token。
rtcChannel.renewToken(token);
详情
该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。当以下任意一种情况发生时:
onRequestToken 回调;
App 应重新获取 Token,然后调用该 API 更新 Token,否则 SDK 将无法和服务器建立连接;
视频管理
enableVideo
启用视频模块。
rtcChannel.enableVideo();
详情
该方法用于启用视频模式。可以在加入频道前或者通话中调用,在加入频道前调用 enableVideo() ,则自动开启视频模式
disableVideo
禁用视频模块
rtcChannel.disableVideo();
详情
该方法用于禁用视频模式。
enableLocalVideo
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
enableLocalVideo(enable: boolean,options?: { deviceId?: string });
详情
调用 enableVideo 后,本地视频即默认开启。你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(true)。
成功禁用或启用本地视频采集后。
参数 | 说明 |
---|---|
enable | true:开启本地视频采集和渲染(默认) false:关闭本地视频采集和渲染。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流 |
options | 可选,其中deviceId为禁用或重新启用的摄像头ID |
setVideoEncoderConfiguration
设置视频编码属性。
rtcChannel.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) |
详情
该方法设置视频编码参数。所有设置的参数均为理想情况下的最大值。当视频引擎因设备、网络环境等原因无法达到设置的分辨率或帧率的最大值时,会取最接近最大值的那个值。 默认情况下,旋转模式为自适应,此时,如果采集的视频是横屏的(宽大于高),则输出视频也是横屏,如果采集视频是竖屏的,则输出视频也是竖屏;如果旋转模式为横屏模式,则输出视频保持横屏,竖屏采集数据将被裁剪;如果旋转模式为竖屏,则输出视频保持竖屏,横屏采集数据将被裁剪。 在开启录制的情况下,旋转模式设置之后不应该改变。
setupLocalVideo
开始播放本地视频。
rtcChannel.setupLocalVideo(view: Element, options?: { deviceId?: string });
参数 | 说明 |
---|---|
view | 本地视频的DOM元素 |
options | 可选,其中deviceId为开始播放的摄像头ID |
详情
调用该方法开始预览本地视频。需要预先调用 enableVideo 启动音频引擎, 再调用 enableLocalVideo(true) 开启本地视频采集。如果想要关闭本地视频采集,则可调用 enableLocalVideo(false)。开启本地视频采集后,可以调用该方法开始预览本地视频。
离开频道再次进入时,需要重新按照步骤调用方法才能再次开始预览本地视频。
Note:
如果你希望在通话中更新本地视频的显示或镜像模式,请使用 setVideoMode / setLocalVideoMirror 方法。
removeLocalVideo
停止播放本地视频。
rtcChannel.removeLocalVideo(view: Element, options?: { deviceId?: string });
参数 | 说明 |
---|---|
view | 本地视频的DOM元素 |
options | 可选,其中deviceId为停止播放的摄像头ID |
setVideoMode
设置视频的显示模式。
rtcChannel.setVideoMode(viewId: string, mode: number);
参数 | 说明 |
---|---|
viewId | 显示视频的dom元素的id |
mode | 显示模式 0 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉 1 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑 |
详情
播放视频后,可以调用该方法更新视频的显示模式。该方法只影响本地用户看到的视频画面,不影响本地发布的视频画面。
Note:
可以在通话中多次调用该方法。
setLocalVideoMirror
设置本地视频的镜像模式。
rtcChannel.setLocalVideoMirror(mirror: boolean, options?: { viewId?: string });
参数 | 说明 |
---|---|
mirror | 是否镜像 true为镜像 false为不镜像 |
options | 可选,其中viewId为显示视频的dom元素的id |
详情
播放本地视频后,可以调用该方法更新本地视频的镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频画面。
Note:
可以在通话中多次调用该方法。
setupRemoteVideo
开始播放远端视频。
rtcChannel.setupRemoteVideo(uid: string, streamId: string, view: Element);
参数 | 说明 |
---|---|
uid | 用户ID,必须为 String |
streamId | 视频流id |
view | 显示视频的 dom 元素 |
详情
调用该方法开始播放远端视频。需要预先调用 enableVideo 启用视频引擎。
removeRemoteVideo
停止播放远端视频。
rtcChannel.removeRemoteVideo(uid: string, streamId: string);
参数 | 说明 |
---|---|
uid | 用户ID,必须为 String |
streamId | 视频流id |
muteLocalVideoStream
发送/停止发送本地视频流。
rtcChannel.muteLocalVideoStream(mute: boolean, options?: { deviceId?: string });
参数 | 说明 |
---|---|
mute | true: 不发送本地视频流 false: 发送本地视频流(默认) |
options | 可选,其中deviceId为发送/停止发送的摄像头ID |
详情
成功调用该方法后,远端会触发 onRemoteVideoStateChanged 回调,reason 为 5 (停止)/6(发送)
Note:
调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。该方法不影响本地视频流获取,没有禁用摄像头。
muteRemoteVideoStream
接收/停止接收指定的远端用户视频流。
rtcChannel.muteRemoteVideoStream(streamId, mute);
参数 | 说明 |
---|---|
streamId | 视频流id |
mute | true 不接收远端视频流 false 接收远端视频流(默认) |
详情
成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason 为 3 (停止)/ 4 (发送)
muteAllRemoteVideoStreams
是否接收/停止接收所有的远端用户视频流。
rtcChannel.muteAllRemoteVideoStreams(mute);
参数 | 说明 |
---|---|
mute | true 不接收远端视频流 false 接收远端视频流(默认) |
详情
成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason 为 3 (停止)/ 4 (发送)
音频管理
enableLocalAudio
开/关本地音频采集。
rtcChannel.enableLocalAudio(mute);
参数 | 说明 |
---|---|
enable | true 开启本地语音采集 false 停止本地语音采集 |
详情
该方法不影响接收或播放远端音频流,enableLocalAudio (false) 适用于只听不发的用户场景。
muteLocalAudioStream
开/关本地音频发送。
rtcChannel.muteLocalAudioStream(mute);
参数 | 说明 |
---|---|
mute | true 停止本地音频发送 false 开启本地音频发送 |
详情
该方法用于允许/禁止向网络发送本地音频流。成功调用该方法后,远端会触发 onRemoteAudioStateChanged 回调 reason 为 5 (停止)/6(发送)。
Note:
该方法不影响录音状态,并没有禁用麦克风。
muteRemoteAudioStream
接收/停止接收指定的远端音频流。
rtcChannel.muteRemoteAudioStream(uid,mute);
参数 | 说明 |
---|---|
uid | 要操作的用户id,必须为 String |
mute | 是否停止接收该用户的声音 |
详情
成功调用该方法后,本地会触发 onRemoteAudioStateChanged 回调,reason 为5(停止)/6(发送)
muteAllRemoteAudioStreams
接收/停止接收所有的远端音频流。
rtcChannel.muteAllRemoteAudioStreams(mute);
详情
成功调用该方法后,本地会触发 onRemoteAudioStateChanged 回调,reason 为5(停止)/6(发送)
enableAudioVolumeIndication
启用/禁用说话者音量提示。
rtcChannel.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 参数不会报告是否在本地检测到人声 |
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户音量, 请在加入频道后,调用该方法。 你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的 音量,则需多次调用该方法。
rtcEngine.adjustUserPlaybackSignalVolume(uid, volume)
参数
参数 | 描述 |
---|---|
uid | string : 远端用户 ID |
volume | number类型 0-100. 0: 静音 100: 原始音量 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
发布管理
publish
开始发布本地音视频。
rtcChannel.publish(options?: { deviceId?: string });
参数 | 说明 |
---|---|
options | 可选,其中deviceId为发布的摄像头ID |
详情
将自己的音视频发布到频道中,让其他人观看和收听。发布成功后,本地会收到 onLocalVideoStateChanged 回调。远端会收到 onRemoteVideoStateChanged 回调
Note:
只有在加入频道成功后,才能调用此方法。
unPublish
停止发布本地音视频。
rtcChannel.unPublish(options?: { deviceId?: string });
参数 | 说明 |
---|---|
options | 可选,其中deviceId为停止发布的摄像头ID |
详情
停止发布自己的音视频。停止发布后,本地会收到 onLocalVideoStateChanged 回调。远端如会收到 onRemoteVideoStateChanged 回调。
Note:
只有在加入频道成功后,才能调用此方法。
音乐文件播放
startPlayMovie
开始播放一个音乐文件。
rtcChannel.startPlayMovie();
参数 | 说明 |
---|---|
mediaFile | 音乐文件的路径,可以是本地文件,也可以是 http 路径(暂时不支持 https 协议) |
loopback | 是否只给自己听 |
cycle | 播放完毕后是否自动从头开始。默认为 false |
paused | 可选,表示是否开始后立即暂停 |
setupLocalMovie
本地观看自己播放的音乐文件。
rtcChannel.setupLocalMovie();
参数 | 说明 |
---|---|
view | 显示电影的 dom 元素 |
mediaFile | 音乐文件的路径,可以是本地文件,也可以是 http 路径(暂时不支持 https 协议) |
Note:
需要在调用 startPlayMovie 后调用此方法才会生效
stopPlayMovie
停止播放一个音乐文件。
rtcChannel.stopPlayMovie();
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
removeLocalMovie
取消观看自己播放的音乐文件。
rtcChannel.removeLocalMovie();
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
Note:
调用此方法不影响别人观看
pausePlayMovie
暂停播放一个音乐文件。
rtcChannel.pausePlayMovie(mediafile);
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
resumePlayMovie
恢复播放一个音乐文件。
rtcChannel.resumePlayMovie(mediafile);
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
getMovieDuration
获取电影时长。
rtcChannel.getMovieDuration(mediaFile);
参数 | 说明 |
---|---|
mediaFile | string:电影路径 |
详情
成功调用该方法后会返回一个 number
getMovieCurrentPosition
获取媒体当前播放时长
int64_t getMovieCurrentPosition(const char* mediafile)
参数
参数 | 描述 |
---|---|
mediafile | 媒体路径 |
返回
媒体当前播放时长
getMovieInfo
获取媒体属性
int getMovieInfo(const char* mediafile,
bool& hasAudio,
bool& hasVideo)
参数
参数 | 描述 |
---|---|
mediafile | 媒体路径 |
hasAudio | 是否有音频 |
hasVideo | 是否有视频 |
返回
- 0: 成功
- 非0: 失败
setMoviePosition
设置音乐的当前进度
rtcChannel.setMoviePosition(mediafile,pos);
参数 | 说明 |
---|---|
mediaFile | 详见 startPlayMovie |
pos | 要移动的目标时间,以毫秒为单位 |
⾳效文件播放
playEffect
播放指定音效文件。
该方法播放指定的本地或在线音效文件。你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益,以及远端用户是否能听到该音效。
你可以多次调用该方法,通过传入不同的音效文件的 soundID 和 filePath,同时播放多个音效文件,实现音效叠加。为获得最佳用户体验,我们建议同时播放的音效文件不要超过 3 个。
调用该方法播放音效结束后,SDK 会触发 audioEffectFinished 回调。
rtcChannel.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
停止播放指定音效文件。
rtcChannel.stopEffect(soundId);
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
stopAllEffects
停止播放所有音效文件。
rtcChannel.stopAllEffects();
pauseEffect
暂停音效文件播放。
rtcChannel.pauseEffect(soundId);
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
pauseAllEffects
暂停所有音效文件播放
rtcChannel.pauseAllEffects();
resumeEffect
恢复播放指定音效文件。
rtcChannel.resumeEffect(soundId);
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
resumeAllEffects
恢复播放指定音效文件。
rtcChannel.resumeAllEffects();
getEffectsVolume
获取播放音效文件音量。
rtcChannel.getEffectsVolume();
setEffectsVolume
设置播放音效文件音量。
rtcChannel.setEffectsVolume(volume);
参数 | 说明 |
---|---|
volume | 音效文件的音量。取值范围为 [0.0, 100.0],100.0 为默认值,表示原始音量。 |
setVolumeOfEffect
设置单个音效文件的音量。
rtcChannel.setVolumeOfEffect(soundId, volume);
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
volume | 音效文件的音量。取值范围为 [0.0, 100.0]。100.0 为默认值 |
unloadEffect
释放音效文件。
rtcChannel.unloadEffect(soundId: number): number;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
preloadEffect
预加载音效文件。
rtcChannel.preloadEffect(soundId: number, filePath: string): number;
参数 | 说明 |
---|---|
soundId | 指定音效的 ID。每个音效均有唯一的 ID |
filePath | 音效文件的绝对路径 |
CDN推流
addPublishStreamUrl
增加旁路推流地址。
调用该方法后,SDK 会在本地触发 streamPublished 回调,报告增加旁路推流地址的状态。
rtcChannel.addPublishStreamUrl(url, transcodingEnabled);
参数 | 说明 |
---|---|
url | CDN 推流地址,格式为 RTMP。该字符长度不能超过 1024 字节,且不支持中文等特殊字符。 |
transcodingEnabled | 设置是否转码:true: 转码。转码是指在旁路推流时对音视频流进行转码处理后, 再推送到其他 RTMP 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景。如果设为 true,需先调用 setLiveTranscoding 方法。 |
false: 不转码。 |
返回
- 0: 成功
- 非0: 失败
Note:
该方法仅适用于直播场景下的主播,请在加入频道后调用该方法。
1. 确保已开通旁路推流的功能。
2. 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
removePublishStreamUrl
删除旁路推流地址。
调用该方法后,SDK 会在本地触发 streamUnpublished 回调,报告删除旁路推流地址的状态。
rtcChannel.removePublishStreamUrl(url: string);
参数 | 说明 |
---|---|
url | 待删除的推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。 |
Note:
该方法只适用于直播场景下的主播。
1. 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
2. 推流地址不支持中文等特殊字符。
setLiveTranscoding
设置直播转码。
调用该方法更新 transcoding 参数时,SDK 会触发 transcodingUpdated 回调。
rtcChannel.setLiveTranscoding(transcoding: TranscodingConfig);
参数 | 说明 |
---|---|
transcoding | 旁路推流转码合图相关设置,详见demo实例 |
通话前网络测试
startLastmileProbeTest
开始通话前网络质量探测。
rtcChannel.startLastmileProbeTest(config: LastmileProbeConfig);
详情
启用该方法后,SDK 会向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。SDK 会一次返回如下两个回调:
- lastMileQuality:视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- lastmileProbeResult:视网络情况约 30 秒内返回。该回调通过客观数据反馈上下行网络质量,因此更客观。
该方法主要用于以下两种场景:
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
Note:
该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要同时使用该方法和 enableLastmileTest。
1. 调用该方法后,在收到 lastMileQuality 和 lastmileProbeResult 回调之前请不用调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
2. 直播场景下,如果本地用户为主播,请勿在加入频道后调用该方法。
stopLastmileProbeTest
停止通话前 last mile 网络质量探测。
rtcChannel.stopLastmileProbeTest();
高级信令方法
Note:
这些方法都必须在加入频道成功后调用。
setProperty
为频道内某个用户设置自定义属性。
rtcChannel.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
发送聊天消息。
rtcChannel.setChatMsg(toId,message,extraData);
参数
参数 | 说明 |
---|---|
toId | 要通知的用户。为空则通知频道内的所有人。如果指定某个用户的 uid ,则只通知指定通知的用户 |
message | 聊天消息文本 |
extraData | 该条消息自定义属性。必须是 json 字符串。可以为空 |
详情
通常可以使用 extraData 来传递一些字体、头像等信息。
频道内的用户会收到 onChatMsg 回调。
pubMsg
发布一条自定义消息。
rtcChannel.pubMsg(msgName, msgId, toId, data, associatedUserId, associatedMsgId, bSave, extraInfo);
参数 | 说明 |
---|---|
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
删除一条自定义消息。
rtcChannel.delMsg(msgName, msgId, toId, data);
参数 | 说明 |
---|---|
msgName | 消息名称 |
msgId | 要删除消息 id 。通过 pubMsg 方法发布消息时会指定其id |
toId | 要通知的用户。为空则通知频道内的所有人。如果指定某个用户的 uid,则只通知指定通知的用户。 |
data | 保留参数 |
详情
调用成功后,已经在频道内的用户,会收到 onDelMsg 消息。
Note:
删除一条不存在的消息会失败。
evictUser
将一个用户踢出频道。
rtcChannel.evictUser(uid,reason);
参数 | 说明 |
---|---|
uid | 被踢用户的uid,必须为 String |
reason | 自定义字段 |
详情
调用成功后,被踢用户会收到 onLocalUserEvicted 回调。其他用户会收到 onUserLeaved 回调。
录制相关方法
startServerRecord
开始录制
rtcChannel.startServerRecord();
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
stopServerRecord
停止录制
rtcChannel.stopServerRecord();
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
pauseServerRecord
暂停录制
rtcChannel.pauseServerRecord();
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
resumeServerRecord
恢复录制
rtcChannel.resumeServerRecord();
详情
调用成功后 会返回 onRecordMsg 事件,具体参数详见 onRecordMsg 事件
设备相关方法
getVideoDevices
获取摄像头列表。
console.log(rtcChannel.getVideoDevices());
返回参数 | 说明 |
---|---|
devicename | 摄像头名称 |
deviceid | 摄像头Id |
getAudioRecordingDevices
获取麦克风列表。
console.log(rtcChannel.getAudioRecordingDevices());
返回参数 | 说明 |
---|---|
devicename | 麦克风名称 |
deviceid | 麦克风Id |
getAudioPlaybackDevices
获取扬声器列表。
console.log(rtcChannel.getAudioPlaybackDevices());
返回参数 | 说明 |
---|---|
devicename | 扬声器名称 |
deviceid | 扬声器 Id |
getCurrentVideoDevice
获取当前摄像头。
console.log(rtcChannel.getCurrentVideoDevice());
返回参数 | 说明 |
---|---|
devicename | 摄像头名称 |
deviceid | 摄像头 Id |
getCurrentAudioRecordingDevice
获取当前麦克风。
console.log(rtcChannel.getCurrentAudioRecordingDevice())
参数 | 说明 |
---|---|
devicename | 麦克风名称 |
deviceid | 麦克风 Id |
getCurrentAudioPlaybackDevice
获取当前扬声器。
console.log(rtcChannel.getCurrentAudioPlaybackDevice())
参数 | 说明 |
---|---|
devicename | 扬声器名称 |
deviceid | 扬声器Id |
setVideoDevice
设置摄像头。
rtcChannel.setVideoDevice(deviceId);
参数 | 说明 |
---|---|
deviceId | 摄像头 id ( getVideoDevices() 中返回的摄像头 id ) |
setAudioRecordingDevice
设置麦克风。
rtcChannel.setAudioRecordingDevice(deviceId);
参数 | 说明 |
---|---|
deviceId | 麦克风id( getAudioRecordingDevices() 中返回的麦克风 id ) |
setAudioPlaybackDevice
设置扬声器。
rtcChannel.setAudioPlaybackDevice(deviceId);
参数 | 说明 |
---|---|
deviceId | 扬声器id( getAudioPlaybackDevices() 中返回的扬声器 id ) |
startVideoDeviceTest
开始摄像头检测。
rtcChannel.startVideoDeviceTest(deviceId,view,onCallback);
参数 | 说明 |
---|---|
deviceId | 需要检测的摄像头 id ( getVideoDevices() 会返回所有摄像头信息) |
view | 显示视频的 dom 元素 |
onCallback | 开始检测后的回调函数 |
stopVideoDeviceTest
停止摄像头检测。
rtcChannel.stopVideoDeviceTest();
startAudioRecordingDeviceTest
开始麦克风检测。
rtcChannel.startAudioRecordingDeviceTest(deviceId,interval);
参数 | 说明 |
---|---|
deviceId | 需要检测的麦克风 id ( getAudioRecordingDevices() 会返回所有麦克风信息) |
interval | 返回音量的间隔(单位:ms 默认200ms) |
stopAudioRecordingDeviceTest
停止麦克风检测。
rtcChannel.stopAudioRecordingDeviceTest();
startAudioPlaybackDeviceTest
开始扬声器检测。
rtcChannel.startAudioPlaybackDeviceTest(deviceId,filePath,options);
参数 | 说明 |
---|---|
deviceId | 需要检测的扬声器 id ( getAudioPlaybackDevices() 会返回所有扬声器信息) |
filePath | 播放的音频文件 需要绝对路径 |
options | 配置项 loop 是否循环播放 |
stopAudioPlaybackDeviceTest
停止扬声器检测。
rtcChannel.stopAudioPlaybackDeviceTest();
桌面分享相关方法
getScreenWindowsInfo
获取窗口信息 该方法获取系统( macOS 或 Windows )窗口 ID,以及相关信息。无需关注返回对象的具体内容,直接使用获取到的窗口 ID 当做 startScreenCaptureByDisplayId 中 excludeWindow 的参数 具体参考 startScreenCaptureByDisplayId。
console.log(rtcChannel.getScreenWindowsInfo());
getScreenDisplaysInfo
获取屏幕信息 该方法获取系统( macOS 或 Windows )屏幕 ID,以及相关信息。你可以使用获取到的屏幕 ID 进行屏幕共享。无需关注返回对象的具体内容,直接使用它进行屏幕共享即可。
console.log(rtcChannel.getScreenDisplaysInfo());
startScreenCaptureByDisplayId
开始桌面分享。
rtcChannel.startScreenCaptureByDisplayId(displayId, excludeWindow, framerate, bitrate, isCaptureCursor);
参数 | 说明 |
---|---|
displayId | 屏幕id 根据 getScreenDisplaysInfo 获取的displayId |
excludeWindow | 不分享的窗口 根据 getScreenWindowsInfo 获取的 windowId |
framerate | 帧率 fps |
bitrate | 码率 kbps |
isCaptrueCursor | 是否捕获鼠标 |
返回值
- -1 通过窗口信息共享屏幕失败
- 0 通过窗口信息共享屏幕成功
- 5 拒绝通过窗口共享屏幕
startScreenCaptureByWindowId
通过窗口信息共享屏幕
rtcChannel.startScreenCaptureByWindowId(windowId, excludeWindow = 0, framerate = 5, bitrate = 1200, isCaptureCursor = false);
参数 | 说明 |
---|---|
windowId | 共享的 windowId |
excludeWindow | 不共享的窗口id 只能不共享一个窗口(默认为0) |
framerate | 帧率(默认为 5 ) |
bitrate | 码率(默认为 1200 ) |
isCaptrueCursor | 是否捕获鼠标(默认为 false ) |
返回值
- -1 通过窗口信息共享屏幕失败
- 0 通过窗口信息共享屏幕成功
- 5 拒绝通过窗口共享屏幕
stopScreenCapture
停止桌面分享。
rtcChannel.stopScreenCapture();
startSpeakerCaptureWhileSharing
共享桌面时开启桌面声音
rtcChannel.startSpeakerCaptureWhileSharing();
stopSpeakerCaptureWhileSharing
共享桌面时关闭桌面声音
rtcChannel.stopSpeakerCaptureWhileSharing();
美颜
setBeautyEffectOptions
开启或关闭本地美颜功能,并设置美颜效果选项。
rtcChannel.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 |
详情
成功调用该方法后会返回一个 number,
- 0:方法调用成功
- < 0:方法调用失败
人声效果
setLocalVoicePitch
设置本地语音音调
rtcChannel.setLocalVoicePitch(pitch);
参数
参数 | 描述 |
---|---|
pitch | number: 语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调 |
返回
- 0: 成功
- 非0: 失败
setLocalVoiceEqualization
设置本地语音音效均衡
rtcChannel.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
设置本地音效混响
rtcChannel.setLocalVoiceReverb(reverbKey, value);
参数
参数 | 描述 |
---|---|
reverbType | 混响音效类型,详见 AUDIO_REVERB_TYPE |
value | number: 设置混响音效的效果数值,各混响音效对应的取值范围请参考 AUDIO_REVERB_TYPE |
返回
- 0: 成功
- 非0: 失败
setAudioEffectPreset
设置 SDK 预设的人声音效。
rtcChannel.setAudioEffectPreset(preset): number
参数
参数 | 描述 |
---|---|
preset | 预设的音效选项,详见 AUDIO_EFFECT_PRESET |
返回
- 0: 成功
- 非0: 失败
enableDeepLearningDenoise
开启或关闭 AI 降噪模式。
rtcChannel.enableDeepLearningDenoise(enabled);
参数
参数 | 描述 |
---|---|
enabled | 是否开启 AI 降噪模式: true: (默认)开启。 false: 关闭。 |
返回
- 0: 成功
- 非0: 失败
跨频道媒体流转发(仅适用于互动直播)
startChannelMediaRelay
开始跨频道媒体流转发,该方法可用于实现跨频道连麦等场景
rtcChannel.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
更新媒体流转发的频道
rtcChannel.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
停止跨频道媒体流转发。
rtcChannel.stopChannelMediaRelay();
详情
一旦停止,主播会退出所有目标频道。
其他方法
on
绑定监听事件。
rtcChannel.on("onJoinChannel",onJoinChannel);
参数 | 说明 |
---|---|
event | 绑定的事件名称 |
callback | 绑定的事件监听器 |
Note:
需要在相应事件调用前进行监听 例如监听 joinchannel 回调 必须在调用 joinChannel 方法前 进行监听 rtcChannel.on(“onJoinChannel”,onJoinChannel) 这样在加入房间后才会有回调返回。
off
取消绑定监听事件。
rtcChannel.off("onJoinChannel",onJoinChannel);
offAll
取消绑定event所有的监听事件。
rtcChannel.offAll("joinchannel");
getVersion
获取SDK版本号。
rtcChannel.getVersion();