GameRTCEngine

public abstract class com.ss.video.rtc.engine.GameRTCEngine

GameRTCEngine 类

静态函数

返回	名称
static synchronized GameRTCEngine	create
static synchronized void	destroy
static String	getSdkVersion
static void	setRtcNativeLibraryLoader

成员函数

返回	名称
abstract int	joinRoom
abstract int	leaveRoom
abstract int	updateToken
abstract int	updateReceiveRange
abstract int	updatePosition
abstract int	enableMicrophone
abstract int	enableAudioSend
abstract int	enableSpeakerphone
abstract int	enableAudioReceive
abstract int	setRecordingVolume
abstract int	setPlaybackVolume
abstract int	setRemoteAudioPlaybackVolume
abstract boolean	setExternalAudioDevice
abstract boolean	pushExternalAudioFrame
abstract boolean	pullExternalAudioFrame

函数说明

create

public static synchronized GameRTCEngine com.ss.video.rtc.engine.GameRTCEngine.create(
    Context context,
    GameRTCEngineConfig config,
    IGameRTCEventHandler eventHandler,
    String params)

创建 GameRTCEngine 实例。
创建 GameRTCEngine 实例后，你才可以使用 SDK 提供的其他能力。

传入参数

参数名	类型	说明
context	Context	Android Context
config	GameRTCEngineConfig	引擎配置参数，参看 GameRTCEngineConfig
eventHandler	IGameRTCEventHandler	SDK 回调给应用层的 Callback 对象，参看 IGameRTCEventHandler 。
params	String	预留字段，json 字符串，通常填空字符串即可。使用时，联系技术支持人员。

返回值

创建成功时，返回一个可用的 GameRTCEngineImpl 实例；
创建失败时，返回 null

注意

你应先创建 eventHandler，再调用本接口创建 GameRTCEngine 实例；并在销毁 GameRTCEngine 实例之后，销毁 eventHandler 实例。
如果已创建了 GameRTCEngine 实例且未销毁，后续再调用时，均返回这个实例。如果已创建的实例被销毁，后续再调用时，会重新创建新的实例。

destroy

public static synchronized void com.ss.video.rtc.engine.GameRTCEngine.destroy()

销毁引擎
销毁由 GameRTCEngine.create 所创建引擎实例，并释放所有相关资源

注意

你必须在所有业务场景的最后阶段调用该方法。该方法在调用之后，会销毁所有 SDK 相关的内存，并且停止与媒体服务器的任何交互。
你不可以在回调线程中直接调用本方法；也不可以在回调方法中等待主线程的执行而同时在主线程调用本方法，否则会造成死锁。原因是本方法为阻塞调用，会阻塞当前线程直到 SDK 彻底完成退出逻辑。

getSdkVersion

public static String com.ss.video.rtc.engine.GameRTCEngine.getSdkVersion()

获取 SDK 当前的版本号。

返回值 SDK 当前的版本号。

setRtcNativeLibraryLoader

public static void com.ss.video.rtc.engine.GameRTCEngine.setRtcNativeLibraryLoader(
    RtcNativeLibraryLoader rtcNativeLibraryLoader)

设置 native library 加载器，需要在其他所有静态方法调用之前被调用。

传入参数

参数名	类型	说明
rtcNativeLibraryLoader	RtcNativeLibraryLoader	本地动态连接库加载器，参看 rtcNativeLibraryLoader

joinRoom

public abstract int com.ss.video.rtc.engine.GameRTCEngine.joinRoom(
    String roomId,
    String userId,
    String token,
    GameRTCRoomConfig config)

加入实时语音房间。
在使用实时语音的通话功能时，必须先加入实时语音房间

传入参数

参数名	类型	说明
roomId	String	房间 ID ，用户调用此接口加入的房间的房间 ID。房间 ID 为最大长度为 128 字节的非空字符串，支持的字符集范围为: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线"_", at符"@", 减号"-"。
userId	String	用户ID ，用户调用此接口加入的房间时使用的用户ID 。用户ID 为最大长度为128字节的非空字符串，支持的字符集范围为: 1. 26个大写字母 A ~ Z 。 2. 26个小写字母 a ~ z 。 3. 10个数字 0 ~ 9 。 4. 下划线"_", at符"@", 减号"-"。
token	String	动态密钥，用于对登录用户进行鉴权验证。进入房间需要携带 Token。测试时可使用控制台生成临时 Token ，正式上线需要使用密钥 SDK 在您的服务端生成并下发 Token
config	GameRTCRoomConfig	房间配置参数，参看 GameRTCRoomConfig

返回值 方法调用结果

0: 成功
-1: roomId 为空，失败
-2: userId 为空，失败
-3: Engine 创建失败

注意

使用不同 App ID 的 App 是不能互通的。
请务必保证生成 Token 使用的 App ID 和创建引擎时使用的 App ID 相同，否则会导致加入房间失败。
用户加入房间成功后，在本端网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本端会收到 onJoinRoomSuccess 回调。
同一个 App ID 的同一个房间内，每个用户的用户ID 必须是唯一的。如果两个用户的用户ID 相同，则后加入房间的用户会将先加入房间的用户踢出房间，并且先加入房间的用户会收到 onRoomError 回调通知。

leaveRoom

public abstract int com.ss.video.rtc.engine.GameRTCEngine.leaveRoom(
    String roomId)

离开房间
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
调用 joinRoom 方法加入房间后，在通话结束时必须调用此方法，并收到 onLeaveRoom 回调确认结束通话，否则无法开始下一次通话。
无论当前是否在房间中，都可以调用此方法。重复调用此方法不会有负面影响。

传入参数

参数名	类型	说明
roomId	String	房间 ID ，用户调用此接口加入的房间的房间 ID 房间 ID 为最大长度为 128 字节的非空字符串，支持的字符集范围为: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线"_", at符"@", 减号"-"。

返回值 方法调用结果

0：成功
-1：引擎已经被销毁或者未创建，或者是房间 ID 不存在

updateToken

public abstract int com.ss.video.rtc.engine.GameRTCEngine.updateToken(
    String roomId,
    String token)

更新进房 token。
在进房时如果收到错误码为 ROOM_ERROR_INVALID_TOKEN 的 onRoomError 回调，表示 token 过期导致进房失败。此时，你应调用此接口，以新 token 进房。

传入参数

参数名	类型	说明
roomId	String	房间 ID ，用户调用此接口加入的房间的房间 ID 房间 ID 为最大长度为 128 字节的非空字符串，支持的字符集范围为: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线"_", at符"@", 减号"-"。
token	String	动态密钥，用于对登录用户进行鉴权验证。进入房间需要携带 Token。测试时可使用控制台生成临时 Token ，正式上线需要使用密钥 SDK 在您的服务端生成并下发 Token

返回值 方法调用结果

0：成功
-1：引擎已经被销毁或者未创建，或者是房间 ID 为空

updateReceiveRange

public abstract int com.ss.video.rtc.engine.GameRTCEngine.updateReceiveRange(
    String roomId,
    GameRTCReceiveRange range)

在世界房间中，使用范围语音功能时，设定语音的接收范围和衰减信息。

传入参数

参数名	类型	说明
roomId	String	房间 ID
range	GameRTCReceiveRange	语音的收听范围，参看 GameRTCReceiveRange

返回值 方法调用结果

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

注意你应在加入房间时，通过参数设置，加入世界房间，并开启范围语音:

关于世界房间，参看 RoomType 中的参数 RTC_ROOM_WORLD。

关于范围语音，参看 [enableRangeAudio](keytype.html#enablerangeaudio)。

updatePosition

public abstract int com.ss.video.rtc.engine.GameRTCEngine.updatePosition(
    String roomId,
    GameRTCPositionInfo info)

使用范围语音功能时，设置玩家的坐标。

传入参数

参数名	类型	说明
roomId	String	房间 ID
info	GameRTCPositionInfo	玩家坐标值，参看 GameRTCPositionInfo

返回值 方法调用结果

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

enableMicrophone

public abstract int com.ss.video.rtc.engine.GameRTCEngine.enableMicrophone(
    String roomId,
    boolean enable)

控制本地音频采集和发布状态。
改变该状态后，房间内其他用户会收到 onMicrophoneEnabled 回调

传入参数

参数名	类型	说明
roomId	String	房间 ID。
enable	boolean	本地音频采集和发布状态： • true：开始采集本地音频，并向房间内发布。 • false: 停止采集本地音频，并停止发布。

返回值 方法调用结果

0：成功
-1：引擎已经被销毁或者未创建，或者是房间 ID 为空

enableAudioSend

public abstract int com.ss.video.rtc.engine.GameRTCEngine.enableAudioSend(
    String roomId,
    boolean enable)

控制本地语音的发送状态：发送/不发送
使用此方法后，房间中的其他用户会收到回调 onAudioSendEnabled。

传入参数

参数名	类型	说明
roomId	String	房间 ID
enable	boolean	发送状态，标识是否发送语音： • true：发布语音 • false: 不发布语音

返回值 方法调用结果

0：方法调用成功
<0：方法调用失败

注意初次调用本方法发送本地语音时，会开启本地音频采集功能。之后再次调用本方法时，仅控制本地音频流的发送状态，不会影响本地音频采集状态。

enableSpeakerphone

public abstract int com.ss.video.rtc.engine.GameRTCEngine.enableSpeakerphone(
    String roomId,
    boolean enable)

设置对来自远端的语音的接收状态。
使用此方法后，房间中的其他用户会收到回调 onSpeakerphoneEnabled。

传入参数

参数名	类型	说明
roomId	String	房间 ID
enable	boolean	接收状态： • true：接收 • false: 不接收

返回值 方法调用结果：

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

注意本方法只控制本地是否接收远端音频流，并不影响本地音频播放设备的工作状态。

enableAudioReceive

public abstract int com.ss.video.rtc.engine.GameRTCEngine.enableAudioReceive(
    String roomId,
    String userId,
    boolean enable)

设置对来自指定远端用户的语音的接收状态。

传入参数

参数名	类型	说明
roomId	String	房间 ID
userId	String	指定远端用户的 ID
enable	boolean	接收状态： • true：接收 • false: 不接收

返回值 方法调用结果

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

注意本方法只控制本地是否接收远端音频流，并不影响本地音频播放设备的工作状态。

setRecordingVolume

public abstract int com.ss.video.rtc.engine.GameRTCEngine.setRecordingVolume(
    int volume)

调节音频采集音量。

传入参数

参数名	类型	说明
volume	int	音频采集音量，调节范围：[0,400] • 0：静音 • 100：原始音量 • 400: 最大可为原始音量的 4 倍(自带溢出保护)

返回值 方法调用结果

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

注意为保证更好的通话质量，建议将 volume 值设为 [0,100]。

setPlaybackVolume

public abstract int com.ss.video.rtc.engine.GameRTCEngine.setPlaybackVolume(
    int volume)

调节本地播放的所有远端用户混音后的音量。

传入参数

参数名	类型	说明
volume	int	播放音量，调节范围：[0,400] • 0：静音 • 100：原始音量 • 400: 最大可为原始音量的 4 倍(自带溢出保护)

返回值 方法调用结果

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

注意为保证更好的通话质量，建议将 volume 值设为 [0,100]。

setRemoteAudioPlaybackVolume

public abstract int com.ss.video.rtc.engine.GameRTCEngine.setRemoteAudioPlaybackVolume(
    String roomId,
    String userId,
    int volume)

调节来自指定远端用户的音频播放音量，默认为 100。

传入参数

参数名	类型	说明
roomId	String	房间 ID
userId	String	指定远端用户的 ID
volume	int	播放音量，调节范围：[0,400] • 0: 静音 • 100: 原始音量 • 400: 最大可为原始音量的 4 倍(自带溢出保护)

返回值 方法调用结果

0：成功
-1：失败。引擎已经被销毁或者未创建，或者是房间 ID 为空

注意开启范围语音后，此接口不生效。

setExternalAudioDevice

public abstract boolean com.ss.video.rtc.engine.GameRTCEngine.setExternalAudioDevice(
    boolean enable,
    int sampleRate,
    int recordChannelNum,
    int playoutChannelNum)

设置是否启用外部音频采集渲染

传入参数

参数名	类型	说明
enable	boolean	• true: 启用自定义音频采集渲染 • false: 不启用自定义音频采集渲染
sampleRate	int	音频采样率（单位 Hz），可以设置的值有 8000，16000，32000，44100，48000
recordChannelNum	int	外部音频采集通道数，支持单声道(1)和双声道(2)
playoutChannelNum	int	外部音频渲染通道数，支持单声道(1)和双声道(2)

返回值 设置是否成功

true: 成功
false: 失败

注意

该方法应该在 joinRoom 前使用。
启用自定义音频采集渲染后，使用 pushExternalAudioFrame 推送音频数据。
启用自定义音频采集渲染后，使用 pullExternalAudioFrame 拉取音频数据。

pushExternalAudioFrame

public abstract boolean com.ss.video.rtc.engine.GameRTCEngine.pushExternalAudioFrame(
    byte[] audioFrame,
    int frameNum)

推送音频数据。
推送的音频格式是 PCM。推送间隔是 10ms。音频采样格式是 S16。

传入参数

参数名	类型	说明
audioFrame	byte[]	PCM 数据。内存大小应该为 frameNum * 音频采集通道数 * 2。其中，音频采集通道数在 setExternalAudioDevice 中设置。
frameNum	int	采样点数量。采样点数量应为采样率（每秒采样数）/100。采样率在 setExternalAudioDevice 中设置。

返回值 方法调用结果

true: 方法调用成功
false：方法调用失败

注意

推送外部音频数据前，你必须先开启外部音频采集渲染，参看 setExternalAudioDevice。
你必须自行创建子线程，并在此线程中定时推送音频数据；而不是在主线程中推送音频数据。

pullExternalAudioFrame

public abstract boolean com.ss.video.rtc.engine.GameRTCEngine.pullExternalAudioFrame(
    byte[] audioFrame,
    int frameNum)

拉取音频数据。
拉取的音频格式是 PCM。拉取间隔是 10ms。音频采样格式是 S16。

传入参数

参数名	类型	说明
audioFrame	byte[]	PCM 数据。内存大小应该为 frameNum * 音频采集通道数 * 2。其中，音频采集通道数在 setExternalAudioDevice 中设置。
frameNum	int	采样点数量。采样点数量应为采样率（每秒采样数）/100。采样率在 setExternalAudioDevice 中设置。

返回值 方法调用结果

true: 方法调用成功
false：方法调用失败

注意

拉取音频数据前，你必须先开启外部音频采集渲染，参看 setExternalAudioDevice。
你必须自行创建子线程，并在此线程中定时拉取音频数据；而不是在主线程中拉取音频数据。