tencent cloud

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

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

使用 GME 重要事项

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

关于 Init 接口

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

接口调用流程图

接入步骤

集成SDK

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

核心接口

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

实时语音

语音消息

反初始化 GME接口：UnInit

核心接口接入

1. 下载 SDK

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

2. 引入头文件

#include "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 服务，建议应用侧在应用初始化时候调用。
• 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 = TCHAR_TO_UTF8(CurrentWidget->editAppID->GetText().ToString().operator*());
std::string userId = TCHAR_TO_UTF8(CurrentWidget->editUserID->GetText().ToString().operator*());
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字符
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();