tencent cloud

피드백

Unreal SDK 빠른 통합

마지막 업데이트 시간:2024-01-18 15:57:14
    본문에서는 Unreal Engine 프로젝트 개발자가 GME(Game Multimedia Engine)용 API를 쉽게 디버깅하고 통합할 수 있도록 자세한 설명을 제공합니다.
    이 문서는 API 디버깅 및 통합을 위해 GME를 시작하는 데 도움이 되는 기본 API만 제공합니다.

    GME 사용 시 주의할 점

    GME는 실시간 음성 채팅 서비스와 음성 메시지 및 음성-텍스트 변환 서비스의 두 가지 서비스를 제공하며 둘 다 Init 및 Poll과 같은 주요 API에 의존합니다.
    Init API 정보
    실시간 음성 채팅과 음성 메시지 서비스를 동시에 사용해야 하는 경우 Init API를 한 번만 호출하면 됩니다.

    API 호출 순서도

    
    image
    
    

    액세스 단계

    SDK 통합

    SDK를 프로젝트에 통합하려면 SDK for Unreal Engine을 참고하십시오.

    주요 API

    실시간 음성 채팅

    음성 메시지

    주요 API 액세스

    1. SDK 다운로드

    SDK 다운로드 가이드 페이지에서 적절한 클라이언트 SDK를 다운로드합니다.

    2. 헤더 파일 가져오기

    #include "tmg_sdk.h"
    
    class UEDEMO1_API AUEDemoLevelScriptActor : public ALevelScriptActor, public ITMGDelegate
    {
    public:
    ...
    private:
    ...

    3. 싱글톤 설정

    모든 호출이 ITMGContext로 시작하고 콜백이 ITMGDelegate를 통해 애플리케이션에 전달되기 때문에 EnterRoom 함수를 호출하기 전에 먼저 ITMGContext를 가져와야 합니다.

    예시 코드

    ITMGContext* context = ITMGContextGetInstance();
    context->SetTMGDelegate(this);

    4. SDK 초기화

    이 API는 GME 서비스를 초기화하는 데 사용됩니다. 애플리케이션을 초기화할 때 호출하는 것이 좋습니다.
    OpenId는 App 개발자가 규정한 규칙으로 사용자를 고유하게 식별하며, App 내에서 중복될 수 없습니다(현재 INT64만 지원됨).
    사용자가 로그인 계정을 전환하면 Uninit를 호출한 다음 새 OpenId로 Init GME를 다시 호출해야 합니다.

    함수 프로토타입

    //class ITMGContext
    ITMGContext virtual int Init(const char* sdkAppId, const char* openId)
    매개변수
    유형
    의미
    sdkAppId
    const char*
    -
    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 API를 주기적으로 호출하여 이벤트 콜백을 트리거할 수 있습니다. GME가 이벤트 콜백을 트리거하려면 Poll API를 주기적으로 호출해야 합니다. 그렇지 않으면 전체 SDK 서비스가 예외적으로 실행됩니다. Demo에서 UEDemoLevelScriptActor.cpp 파일을 참고하십시오.

    예시 코드

    //헤더 파일의 선언
    virtual void Tick(float DeltaSeconds);
    
    void AUEDemoLevelScriptActor::Tick(float DeltaSeconds) {
    Super::Tick(DeltaSeconds);
    ITMGContextGetInstance()->Poll();
    }

    6. 콜백 설정

    API 유형은 Delegate 메소드를 사용하여 애플리케이션에 콜백 알림을 보냅니다. ITMG_MAIN_EVENT_TYPE은 메시지 유형을 나타냅니다. Windows의 data는 json 문자열 형식입니다. key-value pairs에 대해서는 관련 문서를 참고하십시오.

    예시 코드

    //함수 구현:
    //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를 생성합니다.음성 메시지 및 음성 텍스트 변환에 대한 인증을 얻으려면 방 ID 매개변수를 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
    Tencent Cloud 콘솔의 AppId
    strRoomID
    char*
    방 ID, 최대 127자 지원
    strOpenID
    char*
    사용자 ID. 초기화 중 openID와 동일.
    strKey
    char*
    Tencent Cloud 콘솔의 권한 키
    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. 방 입장

    생성된 인증 정보로 방에 입장할 때 사용하는 API입니다. 방 입장 후 마이크와 스피커는 기본적으로 활성화되어 있지 않습니다. 반환된 값 0은 API 호출이 성공했음을 의미하지만 방 입장이 성공했다는 의미는 아닙니다.
    방 오디오 유형을 선택하는 방법에 대한 자세한 내용은 Sound Quality를 참고하십시오.

    함수 프로토타입

    ITMGContext virtual int EnterRoom(const char* roomID, ITMG_ROOM_TYPE roomType, const char* authBuff, int buffLen)
    
    매개변수
    유형
    의미
    roomID
    char*
    방 ID, 최대 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
    사용자는 이미 방에 들어가는 과정에 있었지만 이 작업을 반복했습니다. 방 입장 콜백이 반환될 때까지 방 입장 API를 호출하지 않는 것이 좋습니다.
    1003
    사용자가 이미 방에 있었고 API를 입력하는 방을 다시 호출함
    1101
    SDK가 초기화되었는지, openId가 규칙을 준수하는지, API가 동일한 스레드에서 호출되는지, Poll API가 정상적으로 호출되는지 확인

    2. 마이크 활성화 또는 비활성화

    이 API는 마이크를 활성화/비활성화하는 데 사용됩니다. 방 입장 후 마이크와 스피커는 기본적으로 활성화되어 있지 않습니다.

    예시 코드

    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. 스피커 활성화 또는 비활성화

    이 API는 스피커를 활성화/비활성화하는 데 사용됩니다.

    예시 코드

    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. 방 퇴장

    이 API는 현재 방을 나가기 위해 호출됩니다. 종료를 위해 콜백을 기다리고 처리해야 합니다.

    예시 코드

    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(실시간 음성 채팅 인증 정보 API)를 참고하십시오.

    함수 프로토타입

    ITMGPTT virtual int ApplyPTTAuthbuffer(const char* authBuffer, int authBufferLen)
    
    매개변수
    유형
    의미
    authBuffer
    char*
    인증
    authBufferLen
    int
    인증 길이

    예시 코드

    ITMGContextGetInstance()->GetPTT()->ApplyPTTAuthbuffer(authBuffer,authBufferLen);
    

    2. 스트리밍 음성 인식 시작

    이 API는 스트리밍 음성 인식을 시작하는 데 사용됩니다. 음성을 텍스트로 변환하여 얻은 텍스트는 콜백에서 실시간으로 반환됩니다. 인식할 언어를 지정하거나 음성으로 인식된 정보를 지정된 언어로 번역하고 번역을 반환할 수 있습니다. 녹음을 중지하려면 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*
    오디오 파일이 텍스트로 변환될 언어이며, 매개변수는 Language Parameter Reference List 참고
    translateLanguage
    char*
    오디오 파일이 번역될 언어이며, 매개변수는 Language Parameter Reference List 참고(현재 이 매개변수는 사용할 수 없으며, speechLanguage와 동일한 값을 입력하십시오)

    예시 코드

    ITMGContextGetInstance()->GetPTT()->StartRecordingWithStreamingRecognition(filePath,"cmn-Hans-CN","cmn-Hans-CN");
    

    스트리밍 음성 인식 콜백

    스트리밍 음성 인식이 시작된 후 콜백 함수 OnEvent에서 콜백 메시지를 수신 대기해야 합니다. 이벤트 메시지는 ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE입니다. 즉, 녹화가 중지되고 인식이 완료된 후 텍스트를 반환합니다. 이는 한 단락을 말한 이후에 인식된 텍스트를 반환하는 것과 같습니다.
    이벤트 메시지는 실제 필요에 따라 OnEvent 함수에서 식별됩니다. 전달된 매개변수에는 다음 네 가지 메시지가 포함됩니다.
    메시지 이름
    의미
    result
    스트리밍 음성 인식 성공 여부를 판단하기 위한 반환 코드
    text
    음성에서 변환된 텍스트
    file_path
    저장된 녹음 파일의 로컬 경로
    file_id
    90일 동안 보관되는 녹음 파일의 백엔드 url 주소
    예시 코드
    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 API를 호출하여 녹음 파일을 업로드한 다음 SpeechToText API를 호출하여 음성을 텍스트로 변환
    32777
    스트리밍 음성을 텍스트로 변환하는 데 실패했지만 녹음 및 업로드는 성공함
    반환된 메시지에는 업로드 성공 후 백엔드 url이 포함되어 있으며, SpeechToText API를 호출하여 음성을 텍스트로 변환
    32786
    스트리밍 음성-텍스트 변환 실패
    스트리밍 녹화 중 스트리밍 녹화 API의 실행 결과가 반환될 때까지 기다리십시오

    3. 녹음 중지

    이 API는 녹음을 중지하는 데 사용됩니다. 비동기식이며 녹음이 중지된 후 녹음 완료에 대한 콜백이 반환됩니다. 녹음 파일은 녹음이 성공한 후에만 사용할 수 있습니다.

    함수 프로토타입

    ITMGPTT virtual int StopRecording()

    예시 코드

    ITMGContextGetInstance()->GetPTT()->StopRecording();
    
    문의하기

    고객의 업무에 전용 서비스를 제공해드립니다.

    기술 지원

    더 많은 도움이 필요하시면, 티켓을 통해 연락 바랍니다. 티켓 서비스는 연중무휴 24시간 제공됩니다.

    연중무휴 24시간 전화 지원