接口文档

为方便 Cocos Creator 开发者调试和接入腾讯云游戏多媒体引擎产品 API，本文为通过 Cocos Service 服务面板，接入腾讯云 GME 的接口文档。

• 此文档对应 GME SDK 的版本为 2.5.2。
• 函数原型为 GME Cocos SDK 接口文档 中定义的接口，Cocos Service 接入时设置了一个全局变量 tencentGME.tencentGMEInst，可参考示例代码接入。

GME 的重要接口

说明

• GME 使用前请对工程进行配置，否则 SDK 不生效。

• GME 的接口调用成功后返回值为 GME SDK 定义的枚举值 AV_OK，数值为 0。

• GME 的接口调用要在同一个线程下，任意 JS 线程均可，JSB 层封装和回调的消息均在 JS 线程完成。

• GME 加入房间需要鉴权，请参考文档关于 鉴权初始化 内容。

• GME 需要周期性的调用 poll 接口触发事件回调。

• GME 回调信息，请参考 回调消息 列表。

• 设备的操作要在进房成功之后。

• 错误码详情可参考腾讯云官方文档 错误码。

实时语音流程图

初始化相关接口

未初始化前，SDK 处于未初始化阶段，需要通过接口 init 进行初始化，才可以使用实时语音及离线语音。

使用问题可参考腾讯云官方文档 一般性问题。

init

此接口用于初始化 SDK。参数获取请查看腾讯云官方文档 接入指引。

此接口需要来自腾讯云控制台的 AppID、Key 和 openId 作为参数。这里的 openId 是唯一标识一个用户，规则由 App 开发者自行制定，App 内不重复即可（目前只支持 INT64）。

初始化 SDK 之后才可以进房。

函数原型

TencentGME.fn.init = function(appId: string, key: string, openId: string) {...}

示例代码

var appId = '1400089356';
var key = '1cfbfxxxxx03a53e';
var openId = '123456';
tencentGME.tencentGMEInst.init(appId, key, openId);

poll

此接口用于触发事件回调。通过在 update 里面周期的调用 poll 可以触发事件回调。

函数原型

TencentGME.fn.poll = function() {...}

示例代码

tencentGME.tencentGMEInst.poll();

pause

此接口用于系统暂停。当系统发生 pause 事件时，需要同时通知引擎进行 pause。

函数原型

TencentGME.fn.pause = function() {...}

示例代码

tencentGME.tencentGMEInst.pause();

resume

此接口用于系统恢复。当系统发生 resume 事件时，需要同时通知引擎进行 resume。resume 接口只恢复实时语音。

函数原型

TencentGME.fn.resume = function() {...}

示例代码

tencentGME.tencentGMEInst.resume();

uninit

此接口用于反初始化 SDK，进入未初始化状态。切换账号需要反初始化。

函数原型

TencentGME.fn.uninit = function() {...}

示例代码

tencentGME.tencentGMEInst.uninit();

实时语音房间相关接口

初始化 完毕，SDK 调用 enterRoom 进入房间后，才可以进行实时语音通话。

使用问题可参考腾讯云官方文档 实时语音相关问题。

enterRoom

此接口用于加入房间。如果普通语音进房，业务方面无涉及范围语音需求，则使用普通进房接口。详细信息请查看腾讯云官方文档 范围语音。

若需要使用离线语音功能，通过生成的 鉴权信息 进房，会收到消息为 ITMG_MAIN_EVENT_TYPE_ENTER_ROOM 的回调。加入房间默认不开启麦克风及扬声器。返回值为 AV_OK 的时候代表成功。

函数原型

TencentGME.fn.enterRoom = function(roomId: string, type: number) {...}

房间音频类型请参考腾讯云官方文档 音质选择。

示例代码

var roomId = '123';
tencentGME.tencentGMEInst.enterRoom(roomId, 1);

isRoomEntered

通过调用此接口可以判断是否已经进入房间，返回值为 boolean 类型。

函数原型

TencentGME.fn.isRoomEntered = function() {...}

示例代码

var isRoomEntered = tencentGME.tencentGMEInst.isRoomEntered();

exitRoom

通过调用此接口可以退出所在房间。这是一个异步接口，返回值为 AV_OK 的时候代表退出房间成功。

如果应用中有退房后立即进房的场景，在接口调用流程上，开发者不需要等待 exitRoom 的回调 RoomExitComplete 通知，直接调用接口即可。

函数原型

TencentGME.fn.exitRoom = function() {...}

示例代码

tencentGME.tencentGMEInst.exitRoom();

changeRoomType

此接口用于修改用户房间音频类型，结果参见回调事件，事件类型为 ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE。

函数原型

TencentGME.fn.changeRoomType = function(roomType: number) {...}

示例代码

tencentGME.tencentGMEInst.changeRoomType(4);

getRoomType

此接口用于获取用户房间音频类型，返回值为房间音频类型。当返回值为 0 时，代表获取用户房间音频类型发生错误，房间音频类型参考 enterRoom 接口。

函数原型

TencentGME.fn.getRoomType = function() {...}

示例代码

var roomType = tencentGME.tencentGMEInst.getRoomType();

实时语音音频接口

初始化 SDK 之后进房，在房间中，才可以调用实时音频语音相关接口。

当用户在界面单击开启/关闭麦克风/扬声器的按钮时：

• 对于大部分的 游戏类 App，推荐调用 enableMic 及 enableSpeaker 接口，相当于同时调用enableAudioCaptureDevice/EnableAudioSend 和 enableAudioPlayDevice/enableAudioRecv 接口。

• 其他类型的 移动端 App，例如社交类型 App，开启或者关闭采集设备，会伴随整个设备（采集及播放）重启，如果此时 App 正在播放背景音乐，那么背景音乐的播放也会被中断。利用控制上下行的方式来实现开关麦克风效果，不会中断播放设备。

  具体调用方式为：在进房的时候调用 enableAudioCaptureDevice(true) && enableAudioPlayDevice(true) 一次，单击开关麦克风时只调用 enableAudioSend/enableAudioRecv 来控制音频流是否发送/接收。

• 如果想 单独释放采集/播放设备，请参考下方的 enableAudioCaptureDevice 和 enableAudioPlayDevice 接口介绍。

• 调用 pause 暂停音频，调用 resume 恢复音频。

enableMic

此接口用来开启/关闭麦克风。加入房间时默认不开启麦克风及扬声器。

调用 enableMic 接口，相当于同时调用 enableAudioCaptureDevice 和 enableAudioSend 两个接口。

函数原型

TencentGME.fn.enableMic = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableMic(true);

getMicState

此接口用于获取麦克风的状态。

• 返回值为 0 时表示麦克风处于 关闭 状态。

• 返回值为 1 时表示麦克风为 开启 状态。

函数原型

TencentGME.fn.getMicState = function() {...}

示例代码

var micState = tencentGME.tencentGMEInst.getMicState();

enableAudioCaptureDevice

此接口用来开启/关闭采集设备。加入房间默认不开启设备。

• 只能在进房后调用此接口，退房会自动关闭设备。
• 在移动端，开启采集设备通常会伴随权限申请，音量类型调整等操作。

函数原型

TencentGME.fn.enableAudioCaptureDevice = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableAudioCaptureDevice(true);

isAudioCaptureDeviceEnabled

此接口用于获取采集设备的状态。

函数原型

TencentGME.fn.isAudioCaptureDeviceEnabled = function() {...}

示例代码

var isAudioCaptureDeviceEnabled = tencentGME.tencentGMEInst.isAudioCaptureDeviceEnabled();

enableAudioSend

此接口用于开启或关闭音频上行。

• 如果采集设备已经开启，那么会发送采集到的音频数据。
• 如果采集设备没有开启，那么仍旧无声。

采集设备的开启/关闭，请参考接口 EnableAudioCaptureDevice。

函数原型

TencentGME.fn.enableAudioSend = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableAudioSend(true);

isAudioSendEnabled

此接口用于获取音频上行的状态。

函数原型

TencentGME.fn.isAudioSendEnabled = function() {...}

示例代码

var isAudioSendEnabled = tencentGME.tencentGMEInst.isAudioSendEnabled();

getMicLevel

此接口用于获取麦克风实时音量，返回值为 number 类型。

函数原型

TencentGME.fn.getMicLevel = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.getMicLevel();

getSendStreamLevel

此接口用于获取音频上行实时音量。返回值为 number 类型，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.getSendStreamLevel = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.getSendStreamLevel();

setMicVolume

此接口用于设置麦克风的音量。参数 volume 用于设置麦克风的音量，默认数值为 100。

• 当数值为 0 时，表示静音。
• 当数值为 100 时，则表示音量不增不减。

函数原型

TencentGME.fn.setMicVolume = function(volume: number) {...}

示例代码

tencentGME.tencentGMEInst.setMicVolume(100);

getMicVolume

此接口用于获取麦克风的音量，返回值为一个 number 类型数值。

• 返回值为 1～100 时，表示正常音量。
• 若返回值为 101，则表示没调用过接口 setMicVolume。

函数原型

TencentGME.fn.getMicVolume = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.getMicVolume();

enableSpeaker

此接口用于开启/关闭扬声器。

函数原型

TencentGME.fn.enableSpeaker = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableSpeaker(true);

getSpeakerState

此接口用于获取扬声器状态。

• 返回值为 0 时，表示扬声器处于 关闭 状态。
• 返回值 1 时，表示扬声器为 开启 状态。
• 返回值为 2 时，表示扬声器处于 正在操作 状态。

函数原型

TencentGME.fn.getSpeakerState = function() {...}

示例代码

var speakerState = tencentGME.tencentGMEInst.getSpeakerState();

enableAudioPlayDevice

此接口用于开启/关闭播放设备。

函数原型

TencentGME.fn.enableAudioPlayDevice = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableAudioPlayDevice(true);

isAudioPlayDeviceEnabled

此接口用于获取播放设备状态。

函数原型

TencentGME.fn.isAudioPlayDeviceEnabled = function() {...}

示例代码

var isAudioPlayDeviceEnabled = tencentGME.tencentGMEInst.isAudioPlayDeviceEnabled();

enableAudioRecv

此接口用于开启/关闭音频下行。

• 如果播放设备已经开启，那么会播放房间里其他人的音频数据。
• 如果播放设备没有开启，那么仍旧无声。

播放设备的开启/关闭请参考接口 EnableAudioPlayDevice 。

函数原型

TencentGME.fn.enableAudioRecv = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableAudioRecv(true);

isAudioRecvEnabled

此接口用于获取音频下行状态。

函数原型

TencentGME.fn.isAudioRecvEnabled = function() {...}

示例代码

var isAudioRecvEnabled = tencentGME.tencentGMEInst.isAudioRecvEnabled();

getSpeakerLevel

此接口用于获取扬声器实时音量。返回值为 number 类型数值，表示扬声器实时音量。

函数原型

TencentGME.fn.getSpeakerLevel = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.getSpeakerLevel();

getRecvStreamLevel

此接口用于获取房间内其他成员下行实时音量，返回值为 number 类型，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.getRecvStreamLevel = function(openId: string) {...}

示例代码

var volume = tencentGME.tencentGMEInst.getRecvStreamLevel();

setSpeakerVolume

此接口用于设置扬声器音量，参数 volume 用于设置扬声器的音量。

• 当数值为 0 时，表示静音。
• 当数值为 100 时，表示音量不增不减，默认数值为 100。

函数原型

TencentGME.fn.setSpeakerVolume = function(volume: number) {...}

示例代码

tencentGME.tencentGMEInst.setSpeakerVolume(100);

getSpeakerVolume

此接口用于获取扬声器音量。返回值为 number 类型数值。

• 返回值为 1～100 时，表示正常音量。
• 若返回值为 101，则代表没调用过接口 setSpeakerVolume。

函数原型

TencentGME.fn.getSpeakerVolume = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.getSpeakerVolume();

enableLoopBack

此接口用于开启/关闭耳返。

函数原型

TencentGME.fn.enableLoopBack = function(bEnabled: boolean) {...}

示例代码

tencentGME.tencentGMEInst.enableLoopBack(true);

离线语音语音转文字流程图

离线语音

未初始化前，SDK 处于未初始化阶段，需要通过接口 init 初始化 SDK，才可以使用实时语音及离线语音。

使用问题可参考腾讯云官方文档 离线语音相关问题。

初始化相关接口

离线语音相关接口

applyPTTAuthbuffer

此接口用于鉴权初始化。在 初始化 SDK 之后调用鉴权初始化。

函数原型

TencentGME.fn.applyPTTAuthbuffer = function() {...}

示例代码

tencentGME.tencentGMEInst.applyPTTAuthbuffer();

pttSetMaxMessageLength

此接口用于限制最大语音消息的长度，最大支持 60 秒。

函数原型

TencentGME.fn.pttSetMaxMessageLength = function(msTime: number) {...}

示例代码

tencentGME.tencentGMEInst.pttSetMaxMessageLength();

pttStartRecording

此接口用于启动流式录音。需要将录音文件上传后才可以进行语音转文字等操作。

函数原型

TencentGME.fn.pttStartRecording = function(fileDir: string) {...}

示例代码

var fileDir = '*****';
tencentGME.tencentGMEInst.pttStartRecording(fileDir);

pttStartRecordingWithStreamingRecognition

此接口用于启动流式语音识别。同时在回调中会有实时的语音转文字返回，可以指定语言进行识别，也可以将语音中识别到的信息翻译成指定的语言返回。

函数原型

TencentGME.fn.pttStartRecordingWithStreamingRecognition = function(fileDir: string, [speechLanguage: string, translateLanguage: string]) {...}

示例代码

var fileDir = '*****';
tencentGME.tencentGMEInst.pttStartRecordingWithStreamingRecognition(fileDir);

pttPauseRecording

此接口用于暂停录音。如需恢复录音请调用接口 ResumeRecording。

函数原型

TencentGME.fn.pttPauseRecording = function() {...}

示例代码

tencentGME.tencentGMEInst.pttPauseRecording();

pttResumeRecording

此接口用于恢复录音。

函数原型

TencentGME.fn.pttResumeRecording = function() {...}

示例代码

tencentGME.tencentGMEInst.pttResumeRecording();

pttStopRecording

此接口用于停止录音。此接口为异步接口，停止录音后会有录音完成回调，回调成功之后录音文件才可用。

函数原型

TencentGME.fn.pttStopRecording = function() {...}

示例代码

tencentGME.tencentGMEInst.pttStopRecording();

pttCancelRecording

此接口用于取消录音，取消之后没有回调。

函数原型

TencentGME.fn.pttCancelRecording = function() {...}

示例代码

tencentGME.tencentGMEInst.pttCancelRecording();

pttGetMicLevel

此接口用于获取离线语音麦克风的实时音量，返回值为 number 类型，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.pttGetMicLevel = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.pttGetMicLevel();

pttSetMicVolume

此接口用于设置离线语音录制的音量，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.pttSetMicVolume = function(volume: number) {...}

示例代码

tencentGME.tencentGMEInst.pttSetMicVolume(100);

pttGetMicVolume

此接口用于获取离线语音录制的音量。返回值为 number 类型，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.pttGetMicVolume = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.pttGetMicVolume();

pttGetSpeakerLevel

此接口用于获取离线语音扬声器实时音量。返回值为 number 类型，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.pttGetSpeakerLevel = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.pttGetSpeakerLevel();

pttSetSpeakerVolume

此接口用于设置离线语音播放音量，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.pttSetSpeakerVolume = function(volume: number) {...}

示例代码

tencentGME.tencentGMEInst.pttSetSpeakerVolume(100);

pttGetSpeakerVolume

此接口用于获取离线语音播放音量。返回值为 number 类型，取值范围为 0 ~ 100。

函数原型

TencentGME.fn.pttGetSpeakerVolume = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.pttGetSpeakerVolume();

pttUploadRecordedFile

此接口用于上传语音文件。

函数原型

TencentGME.fn.pttUploadRecordedFile = function(filePath: string) {...}

示例代码

var filePath = '*****';
tencentGME.tencentGMEInst.pttUploadRecordedFile(filePath);

pttDownloadRecordedFile

此接口用于下载语音文件。

函数原型

TencentGME.fn.pttDownloadRecordedFile = function(fileId: string, filePath: string) {...}

示例代码

var filePath = '*****';
var fileId = '***';
tencentGME.tencentGMEInst.pttDownloadRecordedFile(fileId, filePath);

pttPlayRecordedFile

此接口用于开始播放语音。

函数原型

TencentGME.fn.pttPlayRecordedFile = function(filePath: string) {...}

返回错误码

示例代码

var filePath = '*****';
tencentGME.tencentGMEInst.pttPlayRecordedFile(filePath);

pttStopPlayFile

此接口用于停止播放语音。停止播放语音也会有播放完成的回调。

函数原型

TencentGME.fn.pttStopPlayFile = function() {...}

示例代码

var volume = tencentGME.tencentGMEInst.pttStopPlayFile();

pttGetFileSize

此接口用于获取语音文件大小。

函数原型

TencentGME.fn.pttGetFileSize = function(filePath: string) {...}

示例代码

var filePath = '*****';
tencentGME.tencentGMEInst.pttGetFileSize(filePath);

pttGetVoiceFileDuration

此接口用于获取语音文件时长，单位为 毫秒。

函数原型

TencentGME.fn.pttGetVoiceFileDuration = function(filePath: string) {...}

示例代码

var filePath = '*****';
tencentGME.tencentGMEInst.pttGetVoiceFileDuration(filePath);

pttSpeechToText

此接口用于将指定的语音文件翻译成文字。可以指定语言进行识别，也可以将语音中识别到的信息翻译成指定的语言返回。

函数原型

TencentGME.fn.pttStartRecordingWithStreamingRecognition = function(fileID: string, [speechLanguage: string, translateLanguage: string]) {...}

示例代码

var fileID = '*****';
tencentGME.tencentGMEInst.pttStartRecordingWithStreamingRecognition(fileID);

高级 API

getQualityTips

获取音视频通话的实时通话质量的相关信息。该接口主要用来查看实时通话质量、排查问题等，业务侧可以忽略。

函数原型

TencentGME.fn.getQualityTips = function() {...}

示例代码

var qualityTips = tencentGME.tencentGMEInst.getQualityTips();

getSDKVersion

此接口用于获取版本号。

函数原型

TencentGME.fn.getSDKVersion = function() {...}

示例代码

var version = tencentGME.tencentGMEInst.getSDKVersion();

setLogLevel

此接口用于设置打印日志等级。建议保持默认等级。

函数原型

TencentGME.fn.setLogLevel = function(logLevelWrite: number, logLevelPrint: number) {...}

参数含义

示例代码

tencentGME.tencentGMEInst.setLogLevel(4, 4);

setLogLevel

此接口用于设置打印日志路径。各平台的默认路径为：

函数原型

TencentGME.fn.setLogLevel = function(logPath: string) {...}

示例代码

var logPath = '****';
tencentGME.tencentGMEInst.setLogLevel(logPath);

addAudioBlackList

此接口用于将某个 ID 加入音频数据黑名单。返回值为 0 时表示调用成功。

函数原型

TencentGME.fn.addAudioBlackList = function(openId: string) {...}

示例代码

var openId = '****';
tencentGME.tencentGMEInst.addAudioBlackList(openId);

removeAudioBlackList

此接口用于将某个 ID 从音频数据黑名单中移除。返回值为 0 时表示调用成功。

函数原型

TencentGME.fn.removeAudioBlackList = function(openId: string) {...}

示例代码

var openId = '****';
tencentGME.tencentGMEInst.removeAudioBlackList(openId);

回调消息

消息列表

Data 列表