GameRTCEngineKit

@interface GameRTCEngineKit : NSObject

成员变量

类型	名称
id	delegate

静态函数

返回	名称
instancetype	sharedEngineWithConfig:delegate:parameters:
void	destroy
NSString*	getSdkVersion

成员函数

返回	名称
int	joinRoom:uid:token:config:
int	leaveRoom:
int	updateToken:room:
int	updateReceiveRange:room:
int	updatePosition:room:
int	enableMicrophone:room:
int	enableAudioSend:room:
int	enableSpeakerphone:room:
int	enableAudioReceive:room:uid:
int	setRecordingVolume:
int	setPlaybackVolume:
int	setRemoteAudioPlaybackVolume:room:uid:
BOOL	pushExternalAudioFrame:frameNum:
BOOL	pullExternalAudioFrame:frameNum:
BOOL	setExternalAudioDevice:sampleRate:recordChannelNum:playoutChannelNum:

变量说明

delegate

@property (nonatomic, weak) id<GameRTCEngineDelegate> delegate;

函数说明

sharedEngineWithConfig:delegate:parameters:

+ (instancetype)sharedEngineWithConfig:(GameRTCEngineConfig *)config delegate:(id<GameRTCEngineDelegate>)delegate parameters:(NSString *)params;

创建 GameRTCEngine 实例。
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个 GameRTCEngine 实例，来使用 SDK 的其他能力。

传入参数

参数名	类型	说明
config	GameRTCEngineConfig*	配置信息，参看 GameRTCEngineConfig
delegate	id	SDK 回调给应用层的 delegate。
params	NSString*	预留字段，json 字符串，通常填空字符串即可。使用时，联系技术支持人员。

返回值 GameRTCEngine 实例。

注意该方法在第一次调用时初始化一个 RTCEngine 单例，除非调用 destroy 方法，否则后续的所有调用均返回同一个内部实例。

destroy

+ (void)destroy;

销毁引擎
销毁引擎实例，并释放所有相关资源

注意

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

getSdkVersion

+ (NSString *)getSdkVersion;

获取 SDK 当前的版本号。

返回值 SDK 当前的版本号。

joinRoom:uid:token:config:

- (int)joinRoom:(NSString *)roomId uid:(NSString *)uid token:(NSString *)token config:(GameRTCRoomConfig *)config;

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

传入参数

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

返回值 方法调用结果

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

注意

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

leaveRoom:

- (int)leaveRoom:(NSString *)roomId;

离开房间
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
调用 joinRoom 方法加入房间后，在通话结束时必须调用此方法结束通话，否则无法开始下一次通话。无论当前是否在房间中，都可以调用此方法。重复调用此方法不会有负面影响。
此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本端会收到 rtcEngine:onLeaveRoom: 回调通知。

传入参数

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

返回值 方法调用结果

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

updateToken:room:

- (int)updateToken:(NSString *)token room:(NSString *)roomId;

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

传入参数

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

返回值 方法调用结果

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

updateReceiveRange:room:

- (int)updateReceiveRange:(GameRTCReceiveRange *)range room:(NSString *)roomId;

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

传入参数

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

返回值 方法调用结果

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

注意你应在加入房间时，通过参数设置，加入世界房间，并开启范围语音: - 关于世界房间，参看 GameRTCRoomType 的 GameRTCRoomTypeWorld 参数。

关于范围语音，参看 enableRangeAudio。

updatePosition:room:

- (int)updatePosition:(GameRTCPositionInfo *)position room:(NSString *)roomId;

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

传入参数

参数名	类型	说明
position	GameRTCPositionInfo*	玩家坐标值，参看 GameRTCPositionInfo
roomId	NSString*	房间 ID

返回值 方法调用结果

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

enableMicrophone:room:

- (int)enableMicrophone:(BOOL)enable room:(NSString *)roomId;

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

传入参数

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

返回值 方法调用结果

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

enableAudioSend:room:

- (int)enableAudioSend:(BOOL)enable room:(NSString *)roomId;

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

传入参数

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

返回值 方法调用结果

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

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

enableSpeakerphone:room:

- (int)enableSpeakerphone:(BOOL)enable room:(NSString *)roomId;

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

传入参数

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

返回值 方法调用结果：

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

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

enableAudioReceive:room:uid:

- (int)enableAudioReceive:(BOOL)enable room:(NSString *)roomId uid:(NSString*)uid;

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

传入参数

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

返回值 方法调用结果

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

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

setRecordingVolume:

- (int)setRecordingVolume:(int)volume;

调节音频采集音量。

传入参数

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

返回值 方法调用结果

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

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

setPlaybackVolume:

- (int)setPlaybackVolume:(int)volume;

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

传入参数

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

返回值 方法调用结果

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

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

setRemoteAudioPlaybackVolume:room:uid:

- (int)setRemoteAudioPlaybackVolume:(int)volume room:(NSString *)roomId uid:(NSString *)uid;

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

传入参数

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

返回值 方法调用结果

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

pushExternalAudioFrame:frameNum:

- (BOOL)pushExternalAudioFrame:(void* _Nonnull)audioFrame frameNum:(int)frameNum;

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

传入参数

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

返回值 方法调用结果

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

注意

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

pullExternalAudioFrame:frameNum:

- (BOOL)pullExternalAudioFrame:(void* _Nonnull)audioFrame frameNum:(int)frameNum;

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

传入参数

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

返回值 方法调用结果

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

注意

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

setExternalAudioDevice:sampleRate:recordChannelNum:playoutChannelNum:

- (BOOL)setExternalAudioDevice:(BOOL) enable sampleRate:(int) sampleRate recordChannelNum:(int) recordChannelNum playoutChannelNum:(int) playoutChannelNum;

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

传入参数

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

返回值 设置是否成功

true: 成功
false: 失败

注意

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