tencent cloud

为方便开发者调试和接入腾讯云游戏多媒体引擎产品 API，这里向您介绍 Unity 工程快速接入文档。

GME 快速入门文档只提供最主要的接入接口，协助用户进行接入。

使用 GME 重要事项

GME 分为两个部分，提供实时语音服务、语音消息及转文本服务，使用这两个服务都依赖 Init 和 Poll 等核心接口。

关于 Init 接口

例如使用了实时语音服务，同时也需要使用语音消息服务，只需要调用一次 Init 初始化接口。

接口调用流程图

接入步骤

集成SDK

参考 Unity SDK 集成文档 将 SDK 集成到工程中。

核心接口

• 初始化 GME接口：Init
• 周期性调用 Poll 触发回调接口：Poll
• 监听进房、退房的通知监听：QAVEnterRoomComplete

实时语音

语音消息

• 反初始化 GME接口：UnInit

核心接口接入

1. 下载 SDK

进入下载指引页面，下载对应的 客户端 SDKDownLoad。

2. 引入头文件

using GME;

3. 获取 Context 实例

请使用 ITMGContext 的方法获取 Context 实例，不要直接使用 QAVContext.GetInstance() 去获取实例。

示例代码

int ret = ITMGContext.GetInstance().Init(sdkAppId, openID);

4. 初始化 SDK

未初始化前，SDK 处于未初始化阶段，需要通过接口 Init 初始化 SDK，才可以使用实时语音服务、语音消息服务及转文本服务。调用 Init 接口的线程必须于其他接口在同一线程,建议都在主线程调用接口。

接口原型

//class ITMGContext
public abstract int Init(string sdkAppID, string openID);

参数	类型	含义
sdkAppId	string	来自 腾讯云控制台 的 GME 服务提供的 AppID，获取请参考 服务开通指引。
openID	string	openID 只支持 Int64 类型（转为 string 传入），规则由 App 开发者自行制定，App 内不重复即可。如需使用字符串作为 Openid 传入，可 提交工单 联系开发者。

示例代码

int ret = ITMGContext.GetInstance().Init(sdkAppId, openID);
//通过返回值判断是否初始化成功
if (ret != QAVError.OK)
 {
     Debug.Log("SDK初始化失败:"+ret);
     return;
 }

5. 触发事件回调

通过在 update 里面周期的调用 Poll 可以触发事件回调。Poll 是 GME 的消息泵，GME 需要周期性的调用 Poll 接口触发事件回调。如果没有调用 Poll ，将会导致整个 SDK 服务运行异常。详情请参见 Sample Project 中的 EnginePollHelper 文件。

示例代码

public void Update()
  {
      ITMGContext.GetInstance().Poll();
  }

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. 本地鉴权计算

生成 AuthBuffer，用于相关功能的加密和鉴权，如正式发布请使用后台部署密钥，后台部署请参考 鉴权密钥。

接口原型

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. 加入房间

用生成的鉴权信息进房，加入房间默认不打开麦克风及扬声器。返回值为 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. 开启或关闭麦克风

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

示例代码

//对事件进行监听：
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. 开启或关闭扬声器

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

示例代码

//对事件进行监听：
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. 退出房间

通过调用此接口可以退出所在房间。需等待退房回调并进行处理。

示例代码

ITMGContext.GetInstance().ExitRoom();

退出房间回调

退出房间完成后会有回调，示例代码如下：

对事件进行监听：
ITMGContext.GetInstance().OnExitRoomCompleteEvent += new QAVExitRoomComplete(OnExitRoomComplete);
监听处理：
void OnExitRoomComplete(){
//退出房间后的处理
}

语音消息接入

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. 启动流式语音识别

此接口用于启动流式语音识别，同时在回调中会有实时的语音转文字返回。停止录音调用 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. 停止录音

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

接口原型

ITMGPTT int StopRecording()

示例代码

ITMGContext.GetInstance().GetPttCtrl().StopRecording();