游戏多媒体引擎 Unreal SDK 快速接入-快速接入语音-文档中心-腾讯云

为方便开发者调试和接入腾讯云游戏多媒体引擎产品 API，这里向您介绍 Unreal Engine 工程快速接入文档。
GME 快速入门文档只提供最主要的接入接口，协助用户进行接入。
使用 GME 重要事项
GME 分为两个部分，提供实时语音服务、语音消息及转文本服务，使用这两个服务都依赖 Init 和 Poll 等核心接口。
关于 Init 接口
例如使用了实时语音服务，同时也需要使用语音消息服务，只需要调用一次 Init 初始化接口。
接口调用流程图
﻿
接入步骤
集成SDK
参考 Unreal SDK 集成文档 将 SDK 集成到工程中。
核心接口
﻿初始化 GME﻿
﻿周期性调用 Poll 触发回调﻿
﻿监听进房、退房的通知﻿
实时语音
﻿加入实时语音房间﻿
﻿打开或关闭麦克风﻿
﻿打开或关闭扬声器﻿
﻿退出语音房间﻿
语音消息
﻿鉴权初始化﻿
﻿启动流式语音识别﻿
﻿停止录制﻿
﻿反初始化 GME﻿
核心接口接入
1. 下载 SDK
进入下载指引页面，下载对应的 客户端  SDK。
2. 引入头文件
#include "GMESDK/tmg_sdk.h"
﻿
class UEDEMO1_API AUEDemoLevelScriptActor : public ALevelScriptActor, public ITMGDelegate
{
public:
...
private:
...
｝
3. 设置单例
在 EnterRoom 函数调用之前要先获取 ITMGContext ，所有调用都从 ITMGContext 开始，由ITMGDelegate 回调回传给应用，必须首先设置。
示例代码
ITMGContext* context = ITMGContextGetInstance();
context->SetTMGDelegate(this);
4. 初始化 SDK
此接口用于初始化 GME 服务，建议应用侧在应用初始化时候调用。
**参数 sdkAppId 获取请参见 语音服务开通指引**。
OpenId 用于唯一标识一个用户，目前只支持 INT64，规则由 App 开发者自行制定，App 内不重复即可。
如果用户切换登录账号，需要调用Uninit后用新的 OpenId 重新 Init GME 服务。
函数原型
//class ITMGContext
ITMGContext virtual int Init(const char* sdkAppId, const char* openId)
参数
类型
含义
sdkAppId
const char*
来自 腾讯云控制台 的 GME 服务提供的 AppId。
OpenId
const char*
OpenId 只支持 Int64 类型（转为 string 传入）。
示例代码
std::string appid = "1400XXXXXX";
std::string userId = "10000000";
ITMGContextGetInstance()->Init(appid.c_str(), userId.c_str());
5. 触发事件回调
通过在 update 里面周期的调用 Poll 可以触发事件回调。GME 需要周期性的调用 Poll 接口触发事件回调。如果没有调用 Poll ，将会导致整个 SDK 服务运行异常。
详情请参见 Demo 中的 UEDemoLevelScriptActor.cpp 文件。
示例代码
//头文件中的声明
virtual void Tick(float DeltaSeconds);
﻿
void AUEDemoLevelScriptActor::Tick(float DeltaSeconds) {
  Super::Tick(DeltaSeconds);  
  ITMGContextGetInstance()->Poll();
}
6. 设置回调
接口类采用 Delegate 方法用于向应用程序发送回调通知，消息类型参考 ITMG_MAIN_EVENT_TYPE，data 在 Windows 平台下是 json 字符串格式， 具体 key-value 参见说明文档。
示例代码
//函数实现：
//UEDemoLevelScriptActor.h:
class UEDEMO1_API AUEDemoLevelScriptActor : public ALevelScriptActor, public SetTMGDelegate
{
public:
  void OnEvent(ITMG_MAIN_EVENT_TYPE eventType, const char* data);
｝
﻿
//UEDemoLevelScriptActor.cpp:
void AUEDemoLevelScriptActor::OnEvent(ITMG_MAIN_EVENT_TYPE eventType, const char* data){
  //在此对eventType进行判断及操作
}
7. 鉴权信息
生成 AuthBuffer，用于相关功能的加密和鉴权。语音消息及转文本获取鉴权时，房间号参数必须填 null。
函数原型
int  QAVSDK_AuthBuffer_GenAuthBuffer(unsigned int dwSdkAppID, const char* strRoomID, const char* strOpenID,
  const char* strKey, unsigned char* strAuthBuffer, unsigned int bufferLength);
参数
类型
含义
dwSdkAppID
int
来自腾讯云控制台的 AppId 号码
strRoomID
char*
房间号，最大支持127字符（离线语音房间号参数必须填 null）
strOpenID
char*
用户标识。与 Init 时候的 openID相同。
strKey
char*
来自腾讯云 控制台 的权限密钥
strAuthBuffer
char*
返回的 authbuff
bufferLength
int
传入的 authbuff 长度，建议为 500
示例代码
unsigned int bufferLen = 512;
unsigned char retAuthBuff[512] = {0};
QAVSDK_AuthBuffer_GenAuthBuffer(atoi(SDKAPPID3RD), roomId, "10001", AUTHKEY,retAuthBuff,bufferLen);
实时语音接入
1. 加入房间
用生成的鉴权信息进房。加入房间默认不打开麦克风及扬声器。接口返回值为 0 代表调用接口成功，不代表进房成功。
房间音频类型请参考 音质选择。
函数原型
ITMGContext virtual int EnterRoom(const char*  roomID, ITMG_ROOM_TYPE roomType, const char* authBuff, int buffLen)
参数
类型
含义
roomID
char*
房间号，最大支持127字符
roomType
ITMG_ROOM_TYPE
房间音频类型
authBuffer
char*
鉴权码
buffLen
int
鉴权码长度
示例代码
ITMGContext* context = ITMGContextGetInstance();
context->EnterRoom(roomID, ITMG_ROOM_TYPE_FLUENCY, (char*)retAuthBuff,bufferLen);
加入房间事件回调
加入房间完成后会收到进房通知，在监听处理函数中进行判断后处理。如果回调 err = 0 为成功，即此时进房成功，开始进行计费；如果本日通话总时长 < 700 分钟则免费。
计费问题参考：
﻿购买指南。﻿
﻿计费相关问题。﻿
﻿使用实时语音后，如果客户端掉线了，是否还会继续计费？﻿
示例代码：回调处理相关参考代码。
void UBaseViewController::OnEvent(ITMG_MAIN_EVENT_TYPE eventType, const char *data) {
﻿
FString jsonData = FString(UTF8_TO_TCHAR(data));
TSharedPtr<FJsonObject> JsonObject;
TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(FString(UTF8_TO_TCHAR(data)));
FJsonSerializer::Deserialize(Reader, JsonObject);
﻿
﻿
if (eventType == ITMG_MAIN_EVENT_TYPE_ENTER_ROOM) {
  int32 result = JsonObject->GetIntegerField(TEXT("result"));
  FString error_info = JsonObject->GetStringField(TEXT("error_info"));
  if (result == 0) {
    GEngine->AddOnScreenDebugMessage(INDEX_NONE, 20.0f, FColor::Yellow, TEXT("Enter room success."));
  }
  else {
    FString msg = FString::Printf(TEXT("Enter room failed. result=%d, info = %ls"), result, *error_info);
    GEngine->AddOnScreenDebugMessage(INDEX_NONE, 20.0f, FColor::Yellow, *msg);
  }
  onEnterRoomCompleted(result, error_info);
}
}
错误码
错误码值
原因及建议方案
7006
鉴权失败，原因如下：
AppID 不存在或者错误
authbuff 鉴权错误
鉴权过期 
openId 不符合规范
7007
已经在其它房间
1001
已经在进房过程中，然后又重复了此操作。建议在进房回调返回之前不要再调用进房接口
1003
已经进房了在房间中，又调用一次进房接口
1101
确保已经初始化 SDK，确保 openId 是否符合规则，或者确保在同一线程调用接口，以及确保 Poll 接口正常调用
2. 开启或关闭麦克风
此接口用来开启关闭麦克风。加入房间默认不打开麦克风及扬声器。
示例代码
void UBaseViewController::OnEvent(ITMG_MAIN_EVENT_TYPE eventType, const char *data) {
﻿
  FString jsonData = FString(UTF8_TO_TCHAR(data));
  TSharedPtr<FJsonObject> JsonObject;
  TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(FString(UTF8_TO_TCHAR(data)));
  FJsonSerializer::Deserialize(Reader, JsonObject);
﻿
﻿
  if (eventType == ITMG_MAIN_EVENT_TYPE_ENTER_ROOM) {
    int32 result = JsonObject->GetIntegerField(TEXT("result"));
    FString error_info = JsonObject->GetStringField(TEXT("error_info"));
    if (result == 0) {
      GEngine->AddOnScreenDebugMessage(INDEX_NONE, 20.0f, FColor::Yellow, TEXT("Enter room success."));
      //打开麦克风
      ITMGContextGetInstance()->GetAudioCtrl()->EnableMic(true);
    }
    else {
      FString msg = FString::Printf(TEXT("Enter room failed. result=%d, info = %ls"), result, *error_info);
      GEngine->AddOnScreenDebugMessage(INDEX_NONE, 20.0f, FColor::Yellow, *msg);
    }
    onEnterRoomCompleted(result, error_info);
  }
}
3. 开启或关闭扬声器
此接口用于开启关闭扬声器。
示例代码
void UBaseViewController::OnEvent(ITMG_MAIN_EVENT_TYPE eventType, const char *data) {
﻿
  FString jsonData = FString(UTF8_TO_TCHAR(data));
  TSharedPtr<FJsonObject> JsonObject;
  TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(FString(UTF8_TO_TCHAR(data)));
  FJsonSerializer::Deserialize(Reader, JsonObject);
﻿
﻿
  if (eventType == ITMG_MAIN_EVENT_TYPE_ENTER_ROOM) {
    int32 result = JsonObject->GetIntegerField(TEXT("result"));
    FString error_info = JsonObject->GetStringField(TEXT("error_info"));
    if (result == 0) {
      GEngine->AddOnScreenDebugMessage(INDEX_NONE, 20.0f, FColor::Yellow, TEXT("Enter room success."));
      //打开扬声器
      ITMGContextGetInstance()->GetAudioCtrl()->EnableSpeaker(true);
    }
    else {
      FString msg = FString::Printf(TEXT("Enter room failed. result=%d, info = %ls"), result, *error_info);
      GEngine->AddOnScreenDebugMessage(INDEX_NONE, 20.0f, FColor::Yellow, *msg);
    }
    onEnterRoomCompleted(result, error_info);
  }
}
4. 退出房间
通过调用此接口可以退出所在房间。需等待退房回调并进行处理。
示例代码
ITMGContext* context = ITMGContextGetInstance();
context->ExitRoom();
退出房间回调
退出房间完成后会有回调，示例代码如下：
void TMGTestScene::OnEvent(ITMG_MAIN_EVENT_TYPE eventType,const char* data){
  switch (eventType) {
            case ITMG_MAIN_EVENT_TYPE_EXIT_ROOM:
    {
    //进行处理
    break;
    }
  }
}
语音消息接入
1. 鉴权初始化
在初始化 SDK 之后调用鉴权初始化，authBuffer 的获取参见上文实时语音鉴权信息接口 genAuthBuffer。
函数原型
ITMGPTT virtual int ApplyPTTAuthbuffer(const char* authBuffer, int authBufferLen)
参数
类型
含义
authBuffer
char*
鉴权
authBufferLen
int
鉴权长度
示例代码
ITMGContextGetInstance()->GetPTT()->ApplyPTTAuthbuffer(authBuffer,authBufferLen);
2. 启动流式语音识别
此接口用于启动流式语音识别，同时在回调中会有实时的语音转文字返回，可以指定语言进行识别，也可以将语音中识别到的信息翻译成指定的语言返回。停止录音调用 StopRecording，停止之后才有回调。
函数原型
ITMGPTT virtual int StartRecordingWithStreamingRecognition(const char* filePath) 
ITMGPTT virtual int StartRecordingWithStreamingRecognition(const char* filePath,const char* translateLanguage,const char* translateLanguage) 
参数
类型
含义
filePath
char*
存放的语音路径
speechLanguage
char*
识别成指定文字的语言参数，参数请参考 语音转文字的语言参数参考列表
translateLanguage
char*
翻译成指定文字的语言参数，参数请参考 语音转文字的语言参数参考列表（此参数暂不可用,请填写与 speechLanguage 相同的参数）
示例代码
ITMGContextGetInstance()->GetPTT()->StartRecordingWithStreamingRecognition(filePath,"cmn-Hans-CN","cmn-Hans-CN");
流式语音识别回调
启动流式语音识别后，需要在回调函数 OnEvent 中监听回调消息，事件消息分为 ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE ，在停止录制并完成识别后才返回文字，相当于一段话说完才会返回识别的文字。
根据需求在 OnEvent 函数中对相应事件消息进行判断。传递的参数包含以下4个信息。
消息名称
含义
result
用于判断流式语音识别是否成功的返回码
text
语音转文字识别的文本
file_path
录音存放的本地地址
file_id
录音在后台的 url 地址，录音在服务器存放90天
示例代码
void UBaseViewController::OnEvent(ITMG_MAIN_EVENT_TYPE eventType, const char *data) {
﻿
FString jsonData = FString(UTF8_TO_TCHAR(data));
TSharedPtr<FJsonObject> JsonObject;
TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(FString(UTF8_TO_TCHAR(data)));
FJsonSerializer::Deserialize(Reader, JsonObject);
...
else if(eventType == ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE)
  {
      int32 nResult = JsonObject->GetIntegerField(TEXT("result"));
      FString text = JsonObject->GetStringField(TEXT("text"));
      FString fileid = JsonObject->GetStringField(TEXT("file_id"));
      FString file_path = JsonObject->GetStringField(TEXT("file_path"));
      onPttStreamRecognitionCompleted(nResult,file_path, fileid, text);
  }
  else if(eventType == ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_IS_RUNNING)
  {
      int32 nResult = JsonObject->GetIntegerField(TEXT("result"));
      FString text = JsonObject->GetStringField(TEXT("text"));
      FString fileid = TEXT("STREAMINGRECOGNITION_IS_RUNNING");
      FString file_path = JsonObject->GetStringField(TEXT("file_path"));
      onPttStreamRecognitionisRunning(nResult,file_path, fileid, text);
  }
}
错误码
错误码
含义
处理方式
32775
流式语音转文本失败，但是录音成功
调用 UploadRecordedFile 接口上传录音，再调用 SpeechToText 接口进行语音转文字操作
32777
流式语音转文本失败，但是录音成功，上传成功
返回的信息中有上传成功的后台 url 地址，调用 SpeechToText 接口进行语音转文字操作
32786
流式语音转文本失败
在流式录制状态当中，请等待流式录制接口执行结果返回
3. 停止录音
此接口用于停止录音。此接口为异步接口，停止录音后会有录音完成回调，成功之后录音文件才可用。
函数原型
ITMGPTT virtual int StopRecording()
示例代码
ITMGContextGetInstance()->GetPTT()->StopRecording();
﻿

参数	类型	含义
sdkAppId	const char*	来自腾讯云控制台的 GME 服务提供的 AppId。
OpenId	const char*	OpenId 只支持 Int64 类型（转为 string 传入）。

错误码值	原因及建议方案
7006	鉴权失败，原因如下： AppID 不存在或者错误 authbuff 鉴权错误鉴权过期 openId 不符合规范
7007	已经在其它房间
1001	已经在进房过程中，然后又重复了此操作。建议在进房回调返回之前不要再调用进房接口
1003	已经进房了在房间中，又调用一次进房接口
1101	确保已经初始化 SDK，确保 openId 是否符合规则，或者确保在同一线程调用接口，以及确保 Poll 接口正常调用

消息名称	含义
result	用于判断流式语音识别是否成功的返回码
text	语音转文字识别的文本
file_path	录音存放的本地地址
file_id	录音在后台的 url 地址，录音在服务器存放90天

错误码	含义	处理方式
32775	流式语音转文本失败，但是录音成功	调用 UploadRecordedFile 接口上传录音，再调用 SpeechToText 接口进行语音转文字操作
32777	流式语音转文本失败，但是录音成功，上传成功	返回的信息中有上传成功的后台 url 地址，调用 SpeechToText 接口进行语音转文字操作
32786	流式语音转文本失败	在流式录制状态当中，请等待流式录制接口执行结果返回

Unreal SDK 快速接入

本页目录：

使用 GME 重要事项

接口调用流程图

接入步骤

集成SDK

核心接口

实时语音

语音消息

核心接口接入

1. 下载 SDK

2. 引入头文件

3. 设置单例

示例代码

4. 初始化 SDK

函数原型

示例代码

5. 触发事件回调

示例代码

6. 设置回调

示例代码

7. 鉴权信息

函数原型

示例代码

实时语音接入

1. 加入房间

函数原型

示例代码

加入房间事件回调

2. 开启或关闭麦克风

示例代码

3. 开启或关闭扬声器

示例代码

4. 退出房间

示例代码

退出房间回调

语音消息接入

1. 鉴权初始化

函数原型

示例代码

2. 启动流式语音识别

函数原型

示例代码

流式语音识别回调

3. 停止录音

函数原型

示例代码