为方便开发者调试和接入腾讯云游戏多媒体引擎产品 API,这里向您介绍 Unity 工程快速接入文档。
GME 快速入门文档只提供最主要的接入接口,协助用户进行接入。
使用 GME 重要事项
GME 分为两个部分,提供实时语音服务、语音消息及转文本服务,使用这两个服务都依赖 Init 和 Poll 等核心接口。
关于 Init 接口
例如使用了实时语音服务,同时也需要使用语音消息服务,只需要调用一次 Init 初始化接口。
接口调用流程图
?
?
?接入步骤
集成SDK
核心接口
?初始化 GME?
实时语音
?加入实时语音房间?
?打开或关闭麦克风?
?打开或关闭扬声器?
?退出语音房间?
语音消息
?鉴权初始化?
?启动流式语音识别?
?停止录制?
?反初始化 GME?
核心接口接入
1. 下载 SDK
2. 引入头文件
using GME;
3. 获取 Context 实例
请使用 ITMGContext 的方法获取 Context 实例,不要直接使用 QAVContext.GetInstance() 去获取实例。
示例代码
int ret = ITMGContext.GetInstance().Init(sdkAppId, openID);
4. 初始化 SDK
4. 初始化 SDK
未初始化前,SDK 处于未初始化阶段,需要通过接口 Init 初始化 SDK,才可以使用实时语音服务、语音消息服务及转文本服务。调用 Init 接口的线程必须于其他接口在同一线程,建议都在主线程调用接口。
接口原型
//class ITMGContextpublic abstract int Init(string sdkAppID, string openID);
示例代码
int ret = ITMGContext.GetInstance().Init(sdkAppId, openID);//通过返回值判断是否初始化成功if (ret != QAVError.OK){Debug.Log("SDK初始化失败:"+ret);return;}
5. 触发事件回调
5. 触发事件回调
通过在 update 里面周期的调用 Poll 可以触发事件回调。Poll 是 GME 的消息泵,GME 需要周期性的调用 Poll 接口触发事件回调。如果没有调用 Poll ,将会导致整个 SDK 服务运行异常。详情请参见 Sample Project 中的 EnginePollHelper 文件。
示例代码
public void Update(){ITMGContext.GetInstance().Poll();}
6. 监听进房、退房通知
6. 监听进房、退房通知
进房通知
//委托函数:public delegate void QAVEnterRoomComplete(int result, string error_info);//事件函数:public abstract event QAVEnterRoomComplete OnEnterRoomCompleteEvent;
退房通知
委托函数:public delegate void QAVExitRoomComplete();事件函数:public abstract event QAVExitRoomComplete OnExitRoomCompleteEvent;
7. 本地鉴权计算
接口原型
QAVAuthBuffer GenAuthBuffer(int appId, string roomId, string openId, string key)
参数 | 类型 | 含义 |
appId | int | 来自腾讯云控制台的 AppId 号码。 |
roomId | string | 房间号,最大支持127字符(离线语音房间号参数必须填 null)。 |
openId | string | 用户标识。与 Init 时候的 openId 相同。 |
key | string |
示例代码
public static byte[] GetAuthBuffer(string AppID, string RoomID,string OpenId, string AuthKey){return QAVAuthBuffer.GenAuthBuffer(int.Parse(AppID), RoomID, OpenId, AuthKey);}
实时语音接入
1. 加入房间
1. 加入房间
用生成的鉴权信息进房,加入房间默认不打开麦克风及扬声器。返回值为 AV_OK 的时候代表调用成功,不代表进房成功。
接口原型
ITMGContext EnterRoom(string roomId, int roomType, byte[] authBuffer)
参数 | 类型 | 含义 |
roomId | String | 房间号,最大支持127字符 |
roomType | ITMGRoomType | 只需填 ITMGRoomType.ITMG_ROOM_TYPE_FLUENCY |
authBuffer | byte[] | 鉴权码 |
示例代码
ITMGContext.GetInstance().EnterRoom(strRoomId, ITMGRoomType.ITMG_ROOM_TYPE_FLUENCY, byteAuthbuffer);
加入房间事件回调
加入房间完成后会通过回调返回进房结果,监听进房结果事件后进行处理。如果回调为成功,即此时进房成功,开始进行计费。
示例代码:回调处理相关参考代码。
//对事件进行监听:ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);//监听处理:void OnEnterRoomComplete(int err, string errInfo){if (err != 0) {ShowLoginPanel("错误码:" + err + " 错误信息:" + errInfo);return;}else{//进房成功}}
错误码
错误码值 | 原因及建议方案 |
7006 | 鉴权失败,原因如下: AppID 不存在或者错误 authbuff 鉴权错误 鉴权过期 openId 不符合规范 |
7007 | 已经在其它房间 |
1001 | 已经在进房过程中,然后又重复了此操作。建议在进房回调返回之前不要再调用进房接口 |
1003 | 已经进房了在房间中,又调用一次进房接口 |
1101 | 确保已经初始化 SDK,确保 openId 是否符合规则,或者确保在同一线程调用接口,以及确保 Poll 接口正常调用 |
2. 开启或关闭麦克风
2. 开启或关闭麦克风
此接口用来开启关闭麦克风。加入房间默认不打开麦克风及扬声器。
示例代码
//对事件进行监听:ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);//监听处理:void OnEnterRoomComplete(int err, string errInfo){if (err != 0) {ShowLoginPanel("错误码:" + err + " 错误信息:" + errInfo);return;}else{//进房成功//打开麦克风ITMGContext.GetInstance().GetAudioCtrl().EnableMic(true);}}
3. 开启或关闭扬声器
3. 开启或关闭扬声器
此接口用于开启关闭扬声器。
示例代码
//对事件进行监听:ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);//监听处理:void OnEnterRoomComplete(int err, string errInfo){if (err != 0) {ShowLoginPanel("错误码:" + err + " 错误信息:" + errInfo);return;}else{//进房成功//打开扬声器ITMGContext.GetInstance().GetAudioCtrl().EnableSpeaker(true);}}
4. 退出房间
4. 退出房间
通过调用此接口可以退出所在房间。需等待退房回调并进行处理。
示例代码
ITMGContext.GetInstance().ExitRoom();
退出房间回调
退出房间完成后会有回调,示例代码如下:
对事件进行监听:ITMGContext.GetInstance().OnExitRoomCompleteEvent += new QAVExitRoomComplete(OnExitRoomComplete);监听处理:void OnExitRoomComplete(){//退出房间后的处理}
语音消息接入
1. 鉴权初始化
1. 鉴权初始化
在初始化 SDK 之后调用鉴权初始化,authBuffer 的获取参见上文实时语音鉴权信息接口 genAuthBuffer。
接口原型
ITMGPTT int ApplyPTTAuthbuffer (byte[] authBuffer)
参数 | 类型 | 含义 |
authBuffer | String | 鉴权 |
示例代码
UserConfig.SetAppID(transform.Find ("appId").GetComponent<InputField> ().text);UserConfig.SetUserID(transform.Find ("userId").GetComponent<InputField> ().text);UserConfig.SetAuthKey(transform.Find("authKey").GetComponent<InputField>().text);byte[] authBuffer = UserConfig.GetAuthBuffer(UserConfig.GetAppID(), UserConfig.GetUserID(), null,UserConfig.GetAuthKey());ITMGContext.GetInstance ().GetPttCtrl ().ApplyPTTAuthbuffer(authBuffer);
2. 启动流式语音识别
2. 启动流式语音识别
此接口用于启动流式语音识别,同时在回调中会有实时的语音转文字返回。停止录音调用 StopRecording,停止之后才有回调。
接口原型
ITMGPTT int StartRecordingWithStreamingRecognition(string filePath)
参数 | 类型 | 含义 |
filePath | String | 存放的语音路径 |
示例代码
string recordPath = Application.persistentDataPath + string.Format("/{0}.silk", sUid++);int ret = ITMGContext.GetInstance().GetPttCtrl().StartRecordingWithStreamingRecognition(recordPath);
流式语音识别回调
启动流式语音识别后,需要通过在 OnStreamingSpeechComplete 或者 OnStreamingSpeechisRunning 通知中监听回调消息,事件消息分为以下两个:
OnStreamingSpeechComplete
是在停止录制并完成识别后才返回文字,相当于一段话说完才会返回识别的文字。OnStreamingSpeechisRunning
是在录音过程中就会实时返回识别到的文字,相当于边说话边返回识别到的文字。根据需求在 OnEvent 函数中对相应事件消息进行判断。传递的参数包含以下4个信息。
消息名称 | 含义 |
result | 用于判断流式语音识别是否成功的返回码 |
text | 语音转文字识别的文本 |
file_path | 录音存放的本地地址 |
file_id | 录音在后台的 url 地址,录音在服务器存放90天 |
示例代码
//对事件进行监听:ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechComplete +=new QAVStreamingRecognitionCallback (OnStreamingSpeechComplete);ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechisRunning += new QAVStreamingRecognitionCallback (OnStreamingRecisRunning);//监听处理:void OnStreamingSpeechComplete(int code, string fileid, string filepath, string result){//启动流式语音识别的回调}void OnStreamingRecisRunning(int code, string fileid, string filePath, string result){if (code == 0){setBtnText(mStreamBtn, "流式");InputField field = transform.Find("recordFilePath").GetComponent<InputField>();field.text = filePath;field = transform.Find("downloadUrl").GetComponent<InputField>();field.text = "Stream is Running";field = transform.Find("convertTextResult").GetComponent<InputField>();field.text = result;showWarningText("录制中");}}
错误码
错误码 | 含义 | 处理方式 |
32775 | 流式语音转文本失败,但是录音成功 | 调用 UploadRecordedFile 接口上传录音,再调用 SpeechToText 接口进行语音转文字操作 |
32777 | 流式语音转文本失败,但是录音成功,上传成功 | 返回的信息中有上传成功的后台 url 地址,调用 SpeechToText 接口进行语音转文字操作 |
32786 | 流式语音转文本失败 | 在流式录制状态当中,请等待流式录制接口执行结果返回 |
3. 停止录音
3. 停止录音
此接口用于停止录音。此接口为异步接口,停止录音后会有录音完成回调,成功之后录音文件才可用。
接口原型
ITMGPTT int StopRecording()
示例代码
ITMGContext.GetInstance().GetPttCtrl().StopRecording();
?