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

RTC 实时音视频


CloudHubSDK Android

频道管理

initEngine

初始化SDK引擎。

public static int initEngine(Context context, RtcEngineListener listener,String configs,String appId,boolean enableMultiCamera)

参数

参数说明
contextAndroid应用程序上下文
listener实现了RtcEngineListener接口的事件监听器
configs保留参数
appIdCloudHub 为 app 开发者提供的 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个RtcEngine
enableMultiCamera是否允许多个摄像头同时发布

返回

详情

请在主线程调用RtcEngine类的接口方法。

当允许多摄像头发布时,发布每个流必须指定摄像头的设备id,并且该流发布后不能切换到其他设备,除非重新发布; 如果不允许多摄像头发布,那只能发布一路视频流,但这路流可以切换到其他设备,并且在各个包含cameraId参数的API方法中,cameraId参数是忽略的。

Note

initEngine3

初始化SDK引擎。

public static int initEngine3(Context context, RtcEngineListener listener,String configs,String appId,boolean enableMultiCamera)

参数

参数说明
contextAndroid应用程序上下文
listener实现了RtcEngineListener接口的事件监听器
configs保留参数
appIdCloudHub 为 app 开发者提供的 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个RtcEngine3
enableMultiCamera是否允许多个摄像头同时发布

返回

详情

请在主线程调用RtcEngine3类的接口方法。

当允许多摄像头发布时,发布每个流必须指定摄像头的设备id,并且该流发布后不能切换到其他设备,除非重新发布; 如果不允许多摄像头发布,那只能发布一路视频流,但这路流可以切换到其他设备,并且在各个包含cameraId参数的API方法中,cameraId参数是忽略的。

Note

setChannelProfile

设置频道场景。

public static int setChannelProfile(int profile)

参数

参数说明
profile频道场景,取值如下:

* CHANNEL_PROFILE_COMMUNICATION(0), 通信场景
* CHANNEL_PROFILE_LIVE_BROADCASTING(1), 直播场景

返回

详情

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

Note

setClientRole

设置用户角色。

public static int setClientRole(int role)

参数

参数说明
role直播场景用户角色,取值如下:

* CLIENT_ROLE_BROADCASTER(1), 主播
* CLIENT_ROLE_AUDIENCE(2), 听众

返回

详情

加入频道前,用户需要通过本方法设置观众(默认)或主播角色。加入频道后,用户可以通过本方法切换用户角色。
如果在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 onClientRoleChanged 回调; 远端会触发 onUserLeftonUserJoined 回调。

Note

joinChannel

加入频道。

public static int joinChannel(String channelId, String uid, String token, String properties,boolean autoSubscribeAudio,boolean autoSubscribeVideo)

参数

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

返回

详情

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。
加入频道后,本地会触发 onJoinChannelSuccess 回调; 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。
在网络状况不理想的情况下,客户端可能会与服务器失去连接。SDK 会自动尝试重连并产生 onConnectionLost 回调,重连成功后,本地会触发 onRejoinChannelSuccess 回调。

Note

leaveChannel

离开频道。

public static int leaveChannel()

返回

详情

离开频道,即挂断或退出通话。

当调用 joinChannel 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用本方法。 该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。
成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调; 通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserLeft 回调。

renewToken

更新token。

public static int renewToken(String token)

参数

参数说明
token开发者服务侧生成的token

返回

详情

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

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

getConnectionState

获取当前网络连接状态。

public static int getConnectionState()

返回

setListener

更换事件回调监听器。

public static int setListener(RtcEngineListener listener)

参数

参数说明
listener新的的事件监听器对象

返回

详情

使用新的listener替换旧的listener。

Note

listener可以设置为null,但要注意,如果listener为null,则无法收到引擎的事件通知。

音频管理

enableAudio

开/关音频引擎。

public static int enableAudio(boolean enable)

参数

参数说明
enabletrue开启音频引擎
false关闭音频引擎

返回

adjustRecordingSignalVolume

调节音频采集信号音量

int adjustRecordingSignalVolume(int volume)

参数

参数描述
volume录音信号音量
• 0: 静音
• 400: 原始音量

返回

adjustUserPlaybackSignalVolume

调节本地播放的指定远端用户信号音量

int adjustUserPlaybackSignalVolume(String uid, int volume)

参数

参数描述
uid远端用户的 ID
volume播放音量
• 0: 静音
• 100: 原始音量

返回

adjustPlaybackSignalVolume

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

int adjustPlaybackSignalVolume(int volume)

参数

参数描述
volume播放音量
• 0: 静音
• 400: 原始音量

返回

enableLocalAudio

开/关本地音频采集。

public static int enableLocalAudio(boolean enable)

参数

参数说明
enable* true开启本地语音采集
* false停止本地语音采集

返回

详情

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

Note

该方法与 muteLocalAudioStream 的区别在于:

共同点在于,它们都只影响 publishStream 之后发布的音频流。

muteLocalAudioStream

开/关本地音频发送。

public static int muteLocalAudioStream(boolean mute)

参数

参数说明
mute* true停止本地音频发送
* false开启本地音频发送

返回

详情

该方法用于允许/禁止向网络发送本地音频流。成功调用该方法后,远端会触发 onRemoteAudioStateChanged 回调
(reason为REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED / REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED )。

Note

该方法不影响录音状态,并没有禁用麦克风。

muteRemoteAudioStream

接收/停止接收指定的远端音频流。

public static int muteRemoteAudioStream(String uid, boolean mute)

参数

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

返回

Note

如果之前有调用过 muteAllRemoteAudioStreams(true) 对所有远端音频进行静音,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams(false)。 muteAllRemoteAudioStreams 是全局控制, muteRemoteAudioStream 是精细控制。

muteAllRemoteAudioStreams

接收/停止接收所有的远端音频流。

public static int muteAllRemoteAudioStreams(boolean mute)

参数

参数说明
mute是否停止接收所有的远端声音

返回

setDefaultMuteAllRemoteAudioStreams

设置是否接收/停止接收所有的远端音频流的默认值。

public static int setDefaultMuteAllRemoteAudioStreams(boolean mute)

参数

参数说明
mute* True默认停止接收远端的音频流
* False默认接收远端的音频流

返回

视频管理

enableVideo

启用/禁用视频模块。

public static int enableVideo(boolean enable)

参数

参数说明
enabletrue启用,false禁用

返回

详情

该方法用于启用/禁用视频模式。可以在加入频道前或者通话中调用,在加入频道前调用 enableVideo(true),则自动开启视频模式,在通话中调用 enableVideo(true)则由音频模式切换为视频模式。调用 enableVideo(false)可关闭视频模式。

Note

setVideoEncoderConfiguration

设置视频编码属性。

public static int setVideoEncoderConfiguration(String cameraId, int maxWidth, int maxHeight, int maxFps, int orientationMode)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
maxWidth允许的最大宽度
maxHeight允许的最大高度
maxFps允许的最大帧率
orientationMode视频旋转模式,取值如下:

* ORIENTATION_MODE_ADAPTIVE(0), 默认自适应;
* ORIENTATION_MODE_FIXED_LANDSCAPE(1), 横屏模式
* ORIENTATION_MODE_FIXED_PORTRAIT(2), 竖屏模式

返回

详情

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

startPlayingLocalVideo

开始播放本地视频。

public static int startPlayingLocalVideo(String cameraId, RtcSurfaceViewRenderer renderer, int renderMode, int mirrorMode)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
renderer用于显示视频的视图窗口
renderMode显示模式,取值如下:

* RENDER_MODE_HIDDEN(1), 填满视窗,可能会裁剪图像
* RENDER_MODE_FIT(2), 全部展示,视窗可能会有黑边
mirrorMode镜像模式,取值如下:

* VIDEO_MIRROR_MODE_ENABLED(1)
* VIDEO_MIRROR_MODE_DISABLED(2)

返回

详情

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

Note

如果你希望在通话中更新本地视频的显示或镜像模式,请使用 setLocalVideoRenderMode / setLocalVideoMirrorMode 方法。

startPlayingRemoteVideo

开始播放远端视频。

public static int startPlayingRemoteVideo(String streamId, RtcSurfaceViewRenderer renderer, int renderMode, int mirrorMode)

参数

参数说明
streamId远端视频流的ID
mediaType远端流的媒体类型,取值如下:
* MEDIA_TYPE_AUDIO_ONLY(1)
*MEDIA_TYPE_AUDIO_AND_VIDEO(3)
*MEDIA_TYPE_ONLINE_MOVIE_VIDEO(4)
*MEDIA_TYPE_OFFLINE_MOVIE_VIDEO(5)
*MEDIA_TYPE_SCREEN_VIDEO(6)
renderer用于显示视频的视图窗口
renderMode参见 startPlayingLocalVideo
mirrorMode参见 startPlayingLocalVideo

返回

详情

调用该方法开始播放远端视频。需要预先调用 enableVideo 启用视频引擎。

Note

如果希望在通话中更新远端用户视频的显示或镜像模式,请使用 setRemoteVideoRenderMode / setRemoteVideoMirrorMode 方法。

setLocalVideoRenderMode

设置本地视频的显示模式。

public static int setLocalVideoRenderMode(String cameraId, int renderMode)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
renderMode参见 startPlayingLocalVideo

返回

详情

播放本地视频后,可以调用该方法更新本地视频的显示模式。该方法只影响本地用户看到的视频画面,不影响本地发布的视频画面。

Note

setLocalVideoMirrorMode

设置本地视频的镜像模式。

public static int setLocalVideoMirrorMode(String cameraId, int mirrorMode)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
mirrorMode参见 startPlayingLocalVideo

返回

详情

播放本地视频后,可以调用该方法更新本地视频的镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频画面。

Note

setRemoteVideoRenderMode

设置远端视频的显示模式。

public static int setRemoteVideoRenderMode(String streamId, int renderMode)

参数

参数说明
streamId远端视频流的ID
renderMode参见 startPlayingLocalVideo

返回

详情

播放远端用户视频后,可以调用该方法更新远端用户视频在本地显示时的显示模式。该方法只影响本地用户看到的视频画面。

Note

setRemoteVideoMirrorMode

设置远端视频的镜像模式。

public static int setRemoteVideoMirrorMode(String streamId, int mirrorMode)

参数

参数说明
streamId远端视频流的ID
mirrorMode参见 startPlayingLocalVideo

返回

详情

播放远端用户视频后,可以调用该方法更新远端用户视频在本地显示时的镜像模式。该方法只影响本地用户看到的视频画面。

Note

stopPlayingLocalVideo

停止播放本地视频。

public static int stopPlayingLocalVideo(String cameraId)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略

返回

stopPlayingRemoteVideo

停止播放远端视频。

public static int stopPlayingRemoteVideo(String streamId)

参数

参数说明
streamId远端视频流的ID
mediaType参见 startPlayingRemoteVideo

返回

enableLocalVideo

开启/停止本地视频采集。

public static int enableLocalVideo(String cameraId, boolean enable)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
enable是否启用本地视频采集

* true: 开启本地视频采集和渲染(默认)
* false: 关闭本地摄像头设备。关闭后,远端用户会接收不到本地用户的视频流; 但本地用户依然可以接收远端用户的视频流。设置为false时,该方法不需要本地有摄像头。

返回

详情

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

muteLocalVideoStream

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

public static int muteLocalVideoStream(String cameraId,boolean mute)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
mute* true: 不发送本地视频流
* false: 发送本地视频流(默认)

返回

详情

成功调用该方法后,远端会触发 onRemoteVideoStateChanged 回调,reason为 REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED / REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED

Note

调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。相比于 enableLocalVideo 用于控制本地视频流发送的方法,该方法响应速度更快。该方法不影响本地视频流获取,没有禁用摄像头。

muteRemoteVideoStream

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

public static int muteRemoteVideoStream(String streamId, boolean mute)

参数

参数说明
streamId远端视频流的ID
mute* true不接收远端视频流
* false接收远端视频流(默认)

返回

详情

成功调用该方法后,本地会触发 onRemoteVideoStateChanged 回调,reason为 REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED / REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED

muteAllRemoteVideoStreams

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

public static int muteAllRemoteVideoStreams(boolean mute)

参数

参数说明
mute* true不接收远端视频流
* false接收远端视频流(默认)

返回

setDefaultMuteAllRemoteVideoStreams

设置是否接收/停止接收所有的远端用户视频流的默认值

public static int setDefaultMuteAllRemoteVideoStreams (boolean mute)

参数

参数说明
mute* true默认停止接收远端的视频流
* false默认接收远端的视频流

返回

hookLocalVideoFrame

允许/禁止本地视频数据回调。

public static int hookLocalVideoFrame(String cameraId,boolean hook)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
hook是否允许本地视频数据回调。

* true: 允许
* false: 禁止(默认)

返回

详情

该方法控制本地摄像头的原始视频数据是否回调到应用层,但并不控制采集行为的启动或停止。

setLocalVideoHD

设置本地视频高清采集。

public static int setLocalVideoHD(String cameraId)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略

返回

详情

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

视频前处理及后处理

setBeautyEffectOptions

public static int setBeautyEffectOptions(String cameraId, boolean enabled, BeautyOptions options)

设置美颜

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
enabled是否开启美颜功能:

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

返回

setVideoEffectOptions

public static int setVideoEffectOptions(boolean enabled, Structs.VideoEffectOptions options, String sourceID)

设置高级美颜

参数

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

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

返回

子频道管理

createChannel

创建并获取一个 RtcChannel 对象 public static RtcChannel createChannel(String channelId)

参数说明
channelId频道id

返回

详情

音乐文件播放

startPlayingMovie

开始播放一个音乐文件。

public static int startPlayingMovie(String mediaFile, boolean toPublish, boolean cycle, boolean paused, RtcSurfaceViewRenderer rendererOrNull)

参数

参数说明
mediaFile音乐文件的路径,可以是本地文件,也可以是http/https路径
toPublish是否发布出去
paused是否在启动后立即暂停。默认为false
cycle播放完毕后是否自动从头开始。默认为false
rendererOrNull如果是mp4视频文件,用于显示视频的视图窗口。可以为null

返回

stopPlayingMovie

停止播放一个音乐文件。

public static int stopPlayingMovie(String mediaFile)

参数

参数说明
mediaFile详见 startPlayingMovie

返回

pausePlayingMovie

暂停/恢复播放一个音乐文件。

public static int pausePlayingMovie(String mediaFile, boolean pause)

参数

参数说明
mediaFile详见 startPlayingMovie
pausetrue暂停播放; false恢复播放

返回

getMovieInfo

获取音乐文件的信息

public static int getMovieInfo(String mediaFile, Structs.LocalMovieInfo info)

参数

参数说明
mediaFile详见 startPlayingMovie
info媒体文件信息。详见 LocalMovieInfo

返回

getMovieCurrentPosition

获取音乐文件的播放进度。

public static long getMovieCurrentPosition(String mediaFile)

参数

参数说明
mediaFile详见 startPlayingMovie

返回

播放进度(以毫秒为单位)

setMoviePosition

继续播放一个音乐文件。

public static int setMoviePosition(String mediaFile, long pos)

参数

参数说明
mediaFile详见 startPlayingMovie
pos要移动的目标时间,以毫秒为单位

返回

音效文件播放

getEffectsVolume

获取音效文件播放音量。

public static int getEffectsVolume()

返回

setEffectsVolume

设置音效文件播放音量。

public static int setEffectsVolume(int volume)

参数

参数说明
volume音量值,范围为[0, 100],默认为100。

返回

setVolumeOfEffect

实时调整音效文件播放音量,范围为[0,100]

public static int setVolumeOfEffect(int soundId, int volume)

参数

参数说明
soundIdplayEffect 时传入的音效ID。
volume音量值,范围为[0, 100],默认为100。

playEffect

开始播放一个音效文件。

public static int playEffect(int soundId, String filePath, int loopCount,double pitch,double pan, int gain, boolean toPublish, long startTimeMS, long endTimeMS)

参数

参数说明
soundId自行设定的音效ID,需要保持唯一性。
filePath音效文件的路径,可以是本地文件,也可以是http/https链接。
loopCount设置音效文件循环播放的次数:

* 0: 播放音效文件一次
* 1: 循环播放音效文件两次
* -1: 无限循环播放音效文件,直至调用 stopEffectstopAllEffects 后停止
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。取值越小,则音效的音量越低。
toPublish设置是否将音效传到远端

* true:音效文件中本地播放的同时,远端用户也能听到该音效
* false:只能在本地听到该音效
startTimeMS设置开始播放的时间(毫秒),文件将从该处开始播放。
endTimeMS设置结束播放的时间(毫秒),文件播放到该处时将结束。

返回

详情

该方法可以播放指定的本地或在线音效文件来给应用增加音效,比如游戏中特定操作的音效。

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

调用该方法播放音效结束后,会触发 onAudioEffectFinish 回调。

stopEffect

停止播放一个音效文件。

public static int stopEffect(int soundId)

参数

参数说明
soundIdplayEffect 时传入的音效ID。

返回

stopAllEffects

停止播放全部音效文件。

public static int stopAllEffects()

返回

preloadEffect

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

public static int preloadEffect (int soundId, String filePath)

参数

参数说明
soundId自行设定的音效ID,需要保持唯一性。
filePath音效文件的路径,可以是本地文件,也可以是http/https链接。

返回

unloadEffect

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

public static int unloadEffect (int soundId)

参数

参数说明
soundId自行设定的音效ID,需要保持唯一性。

返回

pauseEffect

暂停播放一个音效文件。

public static int pauseEffect(int soundId)

参数

参数说明
soundIdplayEffect 时传入的音效ID。

返回

pauseAllEffects

暂停播放全部音效文件。

public static int pauseAllEffects()

返回

resumeEffect

继续播放一个音效文件。

public static int resumeEffect(int soundId)

参数

参数说明
soundIdplayEffect 时传入的音效ID。

返回

resumeAllEffects

恢复播放全部音效文件。

public static int resumeAllEffects()

返回

人声效果

要使用此功能,请先联系我们帮您开通

setAudioQuality

设置本地发送音频质量

int setAudioQuality(int quality)

参数

参数说明
quality音频质量,详见 AUDIO_QUALITY

返回

setLocalVoicePitch

设置本地语音音调

public static int setLocalVoicePitch(double pitch)

参数

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

返回

setLocalVoiceEqualization

设置本地语音音效均衡

public static int setLocalVoiceEqualization(int bandFrequency, int gain)

参数

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

返回

setLocalVoiceReverb

设置本地音效混响

public static int setLocalVoiceReverb(int reverbType, double value)

参数

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

返回

setAudioEffectPreset

设置SDK预设得美声效果

public static int setAudioEffectPreset(int preset)

参数说明
preset预设的音效选项,详见 AUDIO_EFFECT_PRESET

返回

详情

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

enableDeepLearningDenoise

开启/关闭AI降噪模式

public static int enableDeepLearningDenoise(boolean enabled)

参数

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

返回

听声辨位

enableSoundPositionIndication

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

public static int enableSoundPositionIndication(boolean enabled)

参数

参数说明
enabledtrue:开启
false:关闭

返回

详情

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

setRemoteVoicePosition

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

public static int setRemoteVoicePosition(String uid, double pan, double gain)

参数

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

返回

详情

跨频道媒体流转发

startChannelMediaRelay

开始跨频道媒体流转发。

public static int startChannelMediaRelay(Structs.ChannelMediaRelayConfiguration config)

参数

参数说明
config跨频道媒体流转发参数配置,详见 ChannelMediaRelayConfiguration

返回

详情

成功调用该方法后,SDK会触发 onChannelMediaRelayStateChanged 回调,并在回调中报告当前的跨频道媒体流转发状态和事件。

Note

updateChannelMediaRelay

更新媒体流转发的频道。

public static int updateChannelMediaRelay(Structs.ChannelMediaRelayConfiguration config)

参数

参数说明
config跨频道媒体流转发参数配置,详见 ChannelMediaRelayConfiguration

返回

详情

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

Note

stopChannelMediaRelay

停止跨频道媒体流转发。

public static int stopChannelMediaRelay()

返回

详情

一旦停止,主播会退出所有目标频道。
成功调用该方法后,SDK会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE(0)RELAY_ERROR_OK(0),则表示已停止转发媒体流。

音量提示

enableAudioVolumeIndication

启用/禁用说话者音量提示。

public static int enableAudioVolumeIndication(int interval)

参数

参数说明
interval指定音量提示的时间间隔:

* <= 0: 禁用音量提示功能
* > 0: 提示间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。启用该方法后,无论频道内是否有人说话,都会在 onAudioVolumeIndication 回调中按设置的时间间隔返回音量提示

返回

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

setEnableSpeakerphone

设置当前是否允许使用扬声器。

public static int setEnableSpeakerphone(boolean enabled)

参数

参数说明
enabled当前是否允许使用扬声器(默认为true)

返回

详情

该方法设置是否允许将语音路由到扬声器(外放)。该方法可以在joinChannel 之前调用。

isSpeakerphoneEnabled

获得当前是否允许使用扬声器。

public static boolean isSpeakerphoneEnabled()

返回

详情

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

耳返控制

enableInEarMonitoring

打开或关闭耳返功能

public static int enableInEarMonitoring(boolean enabled)

参数

参数说明
enabledtrue: 开启耳返功能
false: (默认)关闭耳返功能

返回

Note

用户必须使用有线耳机才能听到耳返效果

setInEarMonitoringVolume

设置耳返音量

public static int setInEarMonitoringVolume(int volume)

参数

参数说明
volume设置耳返音量,取值范围在 0 到 100 间。默认值为 100

返回

通话前网络测试

startEchoTest

开始语音通话回路测试。

public static int startEchoTest(int intervalInSeconds)

参数

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

返回

详情

需要预先调用 enableVideoenableAudio

stopEchoTest

停止语音通话回路测试。

public static int stopEchoTest()

返回

startLastmileProbeTest

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

public static int startLastmileProbeTest(Structs.LastmileProbeConfig config)

参数

参数说明
config测试参数,详见 LastmileProbeConfig

返回

详情

开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
启用该方法后,SDK 会依次返回如下 2 个回调:

Note 请在加入频道之前进行该测试。需要预先调用 enableVideoenableAudio

stopLastmileProbeTest

停止通话前网络质量探测。

public static int stopLastmileProbeTest()

返回

音频自采集

setExternalAudioSource

public static int setExternalAudioSourceParameters(int sampleRate, int channels)

设置pushAudioFrame数据格式

该方法设置 pushAudioFrame 传入的外部音频格式。

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

参数

参数说明
sampleRate指定推送数据的采样率,可设置为 8000、 16000、 32000、 44100 或 48000
channels指定推送数据的通道数,可设置为 1 或 2 (1: 单声道 2: 双声道)

返回

pushSourceAudioFrame

public static int pushSourceAudioFrame(byte[] data) 推送外部音频帧,需先调用setRecordingAudioFrameParameters 。

参数

参数说明
data帧的有效数据

返回

音频自渲染(仅 Pull 模式)

pullPlaybackAudioFrame

public static int pullPlaybackAudioFrame(byte[] data10ms)

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

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

参数

参数说明
data10ms10ms的有效帧数据

返回

setExternalAudioSink

public static int setExternalAudioSinkParameters(int sampleRate, int channels)

设置pullAudioFrame拉取的数据格式。 该方法设置 pullAudioFrame 拉取的音频格式。

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

参数

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

返回

原始音频数据

setRecordingAudioFrameParameters

public static int setRecordingAudioFrameParameters(int sampleRate, int channel, int samplesPerCall)

该方法设置 onRecordAudioFrame 回调的采集音频格式。

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

参数

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

返回

setPlaybackAudioFrameParameters

public static int setPlaybackAudioFrameParameters(int sampleRate, int channel, int samplesPerCall)

该方法设置 OnPlaybackAudioFrame 回调的采集音频格式。

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

参数

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

返回

录制声音片段

startRecordingVoiceClip

开始录制声音片段

public static int startRecordingVoiceClip(String clipBaseName, int clipDurationSeconds, int fileType)

参数

参数说明
clipBaseName声音片段basename
clipDurationSeconds每个声音片段时长
fileType文件类型 MEDIAFILE_TYPE

返回

详情

调用成功后,用户会收到 onVoiceClipFileReady 回调。

stopRecordingVoiceClip

停止录制声音片段

public static int stopRecordingVoiceClip(String clipBaseName)

参数

参数说明
clipBaseName声音片段basename

返回

摄像头控制

switchCamera

切换前置/后置摄像头。

public static int switchCamera()

返回

详情

该方法只适用于单摄像头模式,请在本地视频采集开启的情况下调用该方法。

isFrontFacingCameraFired

判断是否是前置摄像头

public static boolean isFrontFacingCameraFired(String cameraId)

参数说明
cameraId设备id

返回

setCameraFlipMode

设置摄像头的翻转模式。

public static int setCameraFlipMode(String cameraId, boolean horizontalFlip, boolean verticalFlip)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
horizontalFlip是否启用水平翻转
verticalFlip是否启用垂直翻转

返回

详情

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

correctCameraKeystoning

校正摄像头的梯形畸变。

public static int correctCameraKeystoning(String cameraId, float fromX, float fromY, float toX, float toY)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略
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

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

public static int resetCameraKeystoning(String cameraId)

参数

参数说明
cameraId指定要操作的摄像头ID。如果是单摄像头模式,该参数忽略

返回

详情

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

getLocalCameraIds

获取本地的摄像头ID列表。

public String[] getLocalCameraIds()

返回

详情

多摄像头模式下,可以用该方法枚举所有的摄像头,然后打开其中的一个或多个用于发布。

流消息

sendStreamMessage

public static int sendStreamMessage( byte[] message )

发送数据流。

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

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

参数

参数说明
message待发送的数据

返回

发布管理

setPublishStreamInfo

setPublishStreamInfo(String streamInfo, String cameraId)

设置本地视频信息

参数

参数说明
streamInfo本地视频信息(json格式)
cameraId指定要发布的摄像头ID。如果是单摄像头模式,该参数忽略

返回

详情

把描述视频流的信息与设备绑定,让其他人能接受到。如果你有这需求,必须在joinChannel成功后publishStream之前调用。 如果远端成功订阅此视频流, 将会在onRemoteVideoStateChanged回调中的streamInfo参数中体现此视频流的信息。

publishStream

开始发布本地音视频。

public static int publishStream(String cameraId))

参数

参数说明
cameraId指定要发布的摄像头ID。如果是单摄像头模式,该参数忽略

返回

详情

将自己的音视频发布到频道中,让其他人观看和收听。发布成功后,本地会收到 onLocalVideoStateChanged 回调。 远端如果关闭了自动订阅(详见 setAutoSubscribe ),会收到 onUserPublished 回调。 此时对方如果决定收看此人,则需要调用subscribeStream, 成功后将收到 onRemoteVideoStateChanged 回调。 远端如果未关闭自动订阅,会直接收到 onRemoteVideoStateChanged 回调。

Note

只有在加入频道成功后,才能调用此方法。

unpublishStream

停止发布本地音视频。

public static int unpublishStream(String cameraId)

参数

参数说明
cameraId指定要发布的摄像头ID。如果是单摄像头模式,该参数忽略

返回

详情

停止发布自己的音视频。停止发布后,本地会收到 onLocalVideoStateChanged 回调。远端如果关闭了自动订阅(详见 setAutoSubscribe ),会收到 onUserUnpublished 回调。另外不论远端是否关闭自动订阅,都会收到 onRemoteVideoStateChanged 回调。

Note

只有在加入频道成功后,才能调用此方法。

订阅管理(仅用于手动订阅模式)

subscribeStream

开始订阅一路音视频。

public static int subscribeStream(String streamId)

参数

参数说明
streamId该路音视频流在频道内的唯一ID。此ID可从 onUserPublished 回调获得

返回

详情

请在收到 onUserPublished 回调后调用。

unsubscribeStream

停止订阅一路音视频。

public static int unsubscribeStream(String streamId)

参数

参数说明
streamId该路音视频流在频道内的唯一ID。此ID可从 onUserPublished / onUserUnpublished 回调获得

返回

详情

在收到 onUserPublished 回调后,可以反复调用 subscribeStream / unsubscribeStream 方法来建立/移除对这路音视频流的订阅。
在收到 onUserUnpublished 回调后,无需手工调用unsubscribe方法。

setAutoSubscribe

开启/关闭自动订阅模式(默认开启)。

public static int setAutoSubscribe(boolean autoSubscribe)

参数

参数说明
autoSubscribe是否开启自动订阅模式

返回

详情

如果自动订阅模式被开启,则每当频道内有新的媒体流发布,本地sdk就会自动完成网络链路建立和音视频数据的解码工作,并会触发 onRemoteVideoStateChanged 回调(状态为 REMOTE_VIDEO_STATE_STARTING),此时只需要调用对应的播放方法即可。
如果自动订阅模式被关闭,则每当频道内有新的媒体流发布,本地只会收到 onUserPublished 回调,并不会自动触发链路的创建和数据解码的开始。开发者可以自行决定是否/何时订阅。

服务器录制

当频道内有人调用开始/停止/暂停/恢复服务器录制接口,使得服务器录制状态发生改变时,频道内的所有人都会收到 onServerRecordStateChange 回调通知。

当房间处于录制中/录制暂停这两种状态时,新进入房间的人也会收到 onServerRecordStateChange 回调通知。

startServerRecord

开始服务器录制。

public static int startServerRecord()

返回

stopServerRecord

停止服务器录制。

public static int stopServerRecord()

返回

pauseServerRecord

暂停服务器录制。

public static int pauseServerRecord()

返回

resumeServerRecord

恢复服务器录制。

public static int resumeServerRecord()

返回

高级信令方法

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

setProperty

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

public static int setProperty(String uid, String tellWhom, String properties)

参数

参数说明
uid目标用户的uid
tellWhom要通知的用户。为空则通知频道内的所有人。如果指定某个用户的uid,则只通知指定的用户。默认为空
properties自定义属性,必须是json字符串

返回

详情

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

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

Note

sendChatMsg

发送聊天消息。

public static int sendChatMsg(String toId, String message, String extraData)

参数

参数说明
toId要通知的用户。为空则通知频道内的所有人。如果指定某个用户的uid,则只通知指定通知的用户
message聊天消息文本
extraData该条消息自定义属性。必须是json字符串。可以为空

返回

详情

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

pubMsg

发布一条自定义消息。

public static int pubMsg(String msgId, String msgName, String toId, String data, String associatedUserId, String associatedMsgId, boolean save, String extendInfo)

参数

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

返回

详情

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

delMsg

删除一条自定义消息。

public static int delMsg(String msgId, String msgName, String toId, String data)

参数

参数说明
msgId要删除消息id。通过pubMsg方法发布消息时会指定其id
msgName消息名称
toId要通知的用户。为空则通知频道内的所有人。如果指定某个用户的uid,则只通知指定通知的用户。
data保留参数

返回

详情

调用成功后,已经在频道内的用户,会收到 onDelMsg 消息。

Note

删除一条不存在的消息会失败。

evictUser

将一个用户踢出频道。

public static int evictUser(String uid, int reason)

参数

参数说明
uid被踢用户的uid
reason自定义字段

返回

详情

调用成功后,被踢用户会收到 onLocalUserEvicted 回调。其他用户会收到 onUserLeft 回调。

CDN推流

addPublishStreamUrl

增加推流地址。

public static int addPublishStreamUrl(String url)

参数

参数说明
urlCDN推流地址,格式为RTMP。该字符串长度不能超过1024字节。URL不支持中文等特殊字符。

返回

removePublishStreamUrl

删除推流地址。

public static int removePublishStreamUrl(String url)

参数

参数说明
urlCDN推流地址,格式为RTMP。该字符串长度不能超过1024字节。
URL不支持中文等特殊字符。

返回

setLiveTranscoding

设置推流转码参数。

public static int setLiveTranscoding(Structs.LiveTranscoding transcoding)

参数

参数说明
transcoding转码参数,详见 LiveTranscoding

返回

其他方法

getSdkVersion

获取SDK版本号。

public static String getSdkVersion()

返回

当前版本号。