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

RTC 实时音视频


CloudHubSDK Electron

频道管理

initialize

初始化 SDK 引擎。

rtcEngine.initialize ( appId ) ;
参数说明
appIdCloudHub 为 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 会失效。当以下任意一种情况发生时:

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

返回

adjustRecordingSignalVolume

调节麦克风采集信号音量, 该方法在加入频道前后都能调用。

rtcEngine.adjustRecordingSignalVolume(volume)

参数

参数描述
volumenumber类型 0-400.
0: 静音
100:(默认)原始音量
400: 原始音量的 4 倍(自带溢出保护)

返回

adjustPlaybackSignalVolume

调节本地播放的所有远端用户信号音量, 该方法在加入频道前后都能调用。

rtcEngine.adjustPlaybackSignalVolume(volume)

参数

参数描述
volumenumber类型 0-400.
0: 静音
100:(默认)原始音量
400: 原始音量的 4 倍(自带溢出保护)

返回

adjustUserPlaybackSignalVolume

调节本地播放的指定远端用户音量, 请在加入频道后,调用该方法。 你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的 音量,则需多次调用该方法。

rtcEngine.adjustUserPlaybackSignalVolume(uid, volume)

参数

参数描述
uidstring : 远端用户 ID
volumenumber类型 0-100.
0: 静音
100: 原始音量

返回

enableLocalAudio

开/关本地音频采集。

rtcEngine.enableLocalAudio ( mute ) ;
参数说明
enabletrue 开启本地语音采集 false 停止本地语音采集

详情

该方法不影响接收或播放远端音频流,enableLocalAudio ( false ) 适用于只听不发的用户场景。

muteLocalAudioStream

开/关本地音频发送。

rtcEngine.muteLocalAudioStream ( mute ) ;
参数说明
mutetrue 停止本地音频发送 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 ) 。

成功禁用或启用本地视频采集后。

参数说明
enabletrue:开启本地视频采集和渲染 ( 默认 )
false:关闭本地视频采集和渲染。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流
options可选,其中 deviceId 为禁用或重新启用的摄像头 ID

muteLocalVideoStream

发送/停止发送本地视频流。

rtcEngine.muteLocalVideoStream ( mute: boolean, options?: { deviceId?: string }) ;
参数说明
mutetrue: 不发送本地视频流 false: 发送本地视频流 ( 默认 )
options可选,其中 deviceId 为发送/停止发送视频流对应的摄像头 ID

详情

成功调用该方法后,远端会触发 onRemoteVideoStateChanged 回调,reason 为 5 ( 停止 ) /6 ( 发送 )

Note:

调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。该方法不影响本地视频流获取,没有禁用摄像头。

muteRemoteVideoStream

接收/停止接收指定的远端用户视频流。

rtcEngine.muteRemoteVideoStream(streamId, mute); 
参数说明
streamId视频流id
mutetrue 不接收远端视频流 false 接收远端视频流(默认)

详情

成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason 为 3 ( 停止 ) / 4 ( 发送 )

muteAllRemoteVideoStreams

是否接收/停止接收所有的远端用户视频流。

rtcEngine.muteAllRemoteVideoStreams ( mute ) ;
参数说明
mutetrue: 不接收远端视频流
false: 接收远端视频流 ( 默认 )

详情

成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason 为 3 ( 停止 ) / 4 ( 发送 )

视频前处理及后处理

setBeautyEffectOptions

开启或关闭本地美颜功能,并设置美颜效果选项。

rtcEngine.setBeautyEffectOptions ( enable, options, deviceId = '' ) ;
参数说明
enableboolean:是否开启
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。
deviceIdstring:摄像头 id

setVideoEffectOptions

开启或关闭高级美颜功能,并设置美颜效果选项。

rtcEngine.setVideoEffectOptions ( enable, options, deviceId = '' ) ;
参数说明
enableboolean:是否开启
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-白墙
deviceIdstring:摄像头 id

详情

成功调用该方法后会返回一个 number,

多频道管理

createChannel

创建并获取一个 IChannel 对象。

你可以多次调用该方法,创建多个 IChannel 对象,再调用各 IChannel 对象中的 joinChannel 方法,实现同时加入多个频道。

加入多个频道后,你可以同时订阅各个频道的音、视频流;但是同一时间只能在一个频道发布一路音、视频流。

virtual IChannel* createChannel ( const char * channelId )

参数

参数描述
channelId标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围 ( 共 89 个字符 ) :
• 26 个小写英文字母 a~z
• 26 个大写英文字母 A~Z
• 10 个数字 0~9
• 空格
• “!"、"#"、"$"、"%"、"&"、” ( “、” ) “、"+"、"-"、":"、";"、"<"、"="、”."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"

返回

详情

桌面分享相关方法

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是否捕获鼠标

返回值

startScreenCaptureByWindowId

通过窗口信息共享屏幕

rtcEngine.startScreenCaptureByWindowId ( windowId,excludeWindow... ) ;
参数说明
windowId共享的 windowId
excludeWindow不共享的窗口 id 只能不共享一个窗口 ( 默认为 0 )
framerate帧率 ( 默认为 5 )
bitrate码率 ( 默认为 1200 )
isCaptrueCursor是否捕获鼠标 ( 默认为 false )

返回值

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是否有视频

返回

getMovieDuration

获取电影时长。

rtcEngine.getMovieDuration ( mediaFile ) ;
参数说明
mediaFilestring:电影路径

详情

成功调用该方法后会返回一个 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 ) ;

参数

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

返回

setLocalVoiceEqualization

设置本地语音音效均衡

rtcEngine.setLocalVoiceEqualization ( bandFrequency, bandGain )

参数

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

返回

setLocalVoiceReverb

设置本地音效混响

rtcEngine.setLocalVoiceReverb ( reverbKey, value ) ;

参数

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

返回

setAudioEffectPreset

设置 SDK 预设的人声音效。

rtcEngine.setAudioEffectPreset ( preset ) : number

参数

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

返回

enableDeepLearningDenoise

开启或关闭 AI 降噪模式。

rtcEngine.enableDeepLearningDenoise ( enabled ) ;

参数

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

返回

CDN 推流

addPublishStreamUrl

增加旁路推流地址。

调用该方法后,SDK 会在本地触发 streamPublished 回调,报告增加旁路推流地址的状态。

rtcEngine.addPublishStreamUrl ( url ) ;
参数说明
urlCDN 推流地址,格式为 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 ) ;
参数说明
configconfig 属性有: 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 ) ;
参数说明
configconfig 属性有: 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 ) ;
参数说明
intervaltype: number
指定音量提示的时间间隔:
<= 0: 禁用音量提示功能
> 0: 提示间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。启用该方法后,无论频道内是否有人说话,都会在 onAudioVolumeIndication 回调中按设置的时间间隔返回音量提示
smoothtype: number, 可选
平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑
reportVadtype: boolean, 可选
• true: 开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声
• false: 默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声

视频双流模式

enableDualStreamMode

开启或关闭大小流功能

rtcEngine.enableDualStreamMode ( isOpen ) ;
参数说明
isOpenisOpen 是 boolean 类型,true:开启,false:关闭

setRemoteDefaultVideoStreamType

设置默认订阅的视频流类型

rtcEngine.setRemoteDefaultVideoStreamType ( type ) ;
参数说明
typetype 是 number 类型,0 代表大流,1 代表小流

setRemoteVideoStreamType

 设置订阅的视频流类型

rtcEngine.setRemoteVideoStreamType ( uid, streamType ) ;
参数说明
uiduid 是 string 类型,是用户 ID
streamTypestreamType 是 number 类型,视频流类型, 0 代表大流,1 代表小流

通话前网络测试

startLastmileProbeTest

开始通话前网络质量探测。

rtcEngine.startLastmileProbeTest ( config: LastmileProbeConfig ) ;

详情

启用该方法后,SDK 会向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。SDK 会一次返回如下两个回调:

该方法主要用于以下两种场景:

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 )

参数

参数描述
muteboolean值,true-静音 false-取消静音

getAudioPlaybackDeviceMute

获取音频播放设备的静音状态

rtcEngine.getAudioPlaybackDeviceMute()

setAudioPlaybackVolume

设置音频播放设备的音量

rtcEngine.setAudioPlaybackVolume(volume)

参数

参数描述
volumenumber类型 0-255

getAudioPlaybackVolume

获取音频播放设备的音量

rtcEngine.getAudioPlaybackVolume()

返回

startAudioPlaybackDeviceTest

开始扬声器检测。

rtcEngine.startAudioPlaybackDeviceTest ( deviceId,filePath,options ) ;
参数说明
deviceId需要检测的扬声器 id ( getAudioPlaybackDevices ( ) 会返回所有扬声器信息 )
filePath播放的音频文件 需要绝对路径
options配置项 loop 是否循环播放

stopAudioPlaybackDeviceTest

停止扬声器检测。

rtcEngine.stopAudioPlaybackDeviceTest ( ) ;

startAudioDeviceLoopbackTest

开始音频设备回路测试。该方法测试本地的音频设备是否正常工作。

注:该方法仅在本地进行音频设备测试,不涉及网络连接。

rtcEngine.startAudioDeviceLoopbackTest ( interval ) ;

参数

参数说明
interval时间间隔 ( 单位:ms 默认 200ms )

返回

stopAudioDeviceLoopbackTest

停止音频设备回路测试。

rtcEngine.stopAudioDeviceLoopbackTest ( ) ;

返回

音频采集设备管理

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)

参数

参数描述
muteboolean值,true-静音 false-取消静音

getAudioRecordingDeviceMute

获取录音设备的静音状态

rtcEngine.getAudioRecordingDeviceMute()

返回

setAudioRecordingVolume

设置录音设备的音量

rtcEngine.setAudioRecordingVolume(volume)

参数

参数描述
volumenumber类型 0-255

getAudioRecordingVolume

获取录音设备的音量

rtcEngine.getAudioRecordingVolume()

返回

startAudioRecordingDeviceTest

开始麦克风检测。

rtcEngine.startAudioRecordingDeviceTest ( deviceId,interval ) ;
参数说明
deviceId需要检测的麦克风 id ( getAudioRecordingDevices ( ) 会返回所有麦克风信息 )
interval返回音量的间隔 ( 单位:ms 默认 200ms )

stopAudioRecordingDeviceTest

停止麦克风检测。

rtcEngine.stopAudioRecordingDeviceTest ( ) ;

视频设备管理

enableMultiStream

启用多摄像头

rtcEngine.enableMultiStream ( enable: boolean ) ;
参数说明
enabletrue 开启 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: 可选, 要发布的摄像头 ID
streamInfo: 可选, 需要携带的自定义数据

详情

将自己的音视频发布到频道中,让其他人观看和收听。发布成功后,本地会收到 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 字符串

详情

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

设置成功后,被通知的用户和被设置的用户都会收到通知。除此以外,新进入频道的用户也会在 onUserJoined 回调中获得该用户的这些属性。

Note:

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 ( ) ;