tencent cloud

This document provides a detailed description that makes it easy for Unity project developers to debug and integrate the APIs for Game Multimedia Engine (GME).

This document only provides the main APIs to help you get started with GME to debug and integrate the APIs.

Key Considerations for Using GME

GME provides two services: voice chat service and voice message and speech-to-text service, both of which rely on key APIs such as Init and Poll.

Note on Init API

If you need to use voice chat and voice message services at the same time, you only need to call Init API once.

API call flowchart

Directions

Integrating SDK

Refer to Integrating SDK to integrate the SDK into the project.

Key APIs

• Initializing GMEAPI: Init
• Calling Poll periodically to trigger event callbacksAPI: Poll
• Listening on room entry/exit notificationListener: QAVEnterRoomComplete

Voice Chat

Voice Message

Uninitializing GMEAPI: UnInit

Key API Access

1. Downloading the SDK

On the SDK download guide page, download the appropriate client SDKDownLoad.

2. Importing the header file

using TencentMobileGaming;

3. Getting the Context instance

Get the Context instance by using the ITMGContext method instead of QAVContext.GetInstance().

Sample code

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

4. Initializing SDK

• This API is used to initialize the GME service. It is recommended to call it when initializing the application.
• The openID uniquely identifies a user with the rules stipulated by the application developer and unique in the application (currently, only INT64 is supported).
• If the user switches the login account, they need to call Uninit and then call Init again with the new OpenId.

Function prototype

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

Parameter	Type	Description
sdkAppId	String	AppId provided by the GME service from the Tencent Cloud console
OpenId	String	OpenId can only be in Int64 type, which is passed after being converted to a string.

Sample code

int ret = ITMGContext.GetInstance().Init(sdkAppId, openID);
// Determine whether the initialization is successful by the returned value
if (ret != QAVError.OK)
{
  Debug.Log("SDK initialization failed:"+ret);
  return;
}

5. Triggering event callback

Event callbacks can be triggered by periodically calling the Poll API in update. The Poll API should be called periodically for GME to trigger event callbacks; otherwise, the entire SDK service will run exceptionally.
Refer to the EnginePollHelper file in the demo.

Sample code

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

6. Listening on room entry/exit notification

Room entry notification

// Delegate function:
public delegate void QAVEnterRoomComplete(int result, string error_info);
// Event-triggered function:
public abstract event QAVEnterRoomComplete OnEnterRoomCompleteEvent;

Room exit notification

Delegate function:
public delegate void QAVExitRoomComplete();
Event-triggered function:
public abstract event QAVExitRoomComplete OnExitRoomCompleteEvent;

7. Authentication

Generate AuthBuffer for encryption and authentication of relevant features.
To get authentication for voice message and speech-to-text, the room ID parameter must be set to null.

Function prototype

QAVAuthBuffer GenAuthBuffer(int appId, string roomId, string openId, string key)

Parameter	Type	Description
appId	int	AppId from the Tencent Cloud console.
roomId	string	Room ID, which can contain up to 127 characters (For voice message, enter "null".)
openId	string	User ID, which is the same as openId during initialization.
key	string	Permission key from the Tencent Cloud console.

Sample code

public static byte[] GetAuthBuffer(string AppID, string RoomID,string OpenId, string AuthKey){
return QAVAuthBuffer.GenAuthBuffer(int.Parse(AppID), RoomID, OpenId, AuthKey);
}

Voice Chat Access

1. Entering a room

This API is used to enter a room with the generated authentication information. The mic and speaker are not enabled by default after room entry. The returned value of 0 indicates successful API call but not successful room entry.

For more information on how to choose a room audio type, please see Sound Quality Selection.

Function prototype

ITMGContext EnterRoom(string roomId, int roomType, byte[] authBuffer)

Parameter	Type	Description
roomId	String	Room ID, which can contain up to 127 characters
roomType	int	Room audio type
authBuffer	byte[]	Authentication code

Sample code

ITMGContext.GetInstance().EnterRoom(strRoomId, ITMGRoomType.ITMG_ROOM_TYPE_FLUENCY, byteAuthbuffer);

Callback for room entry

After the user enters the room, a room entry notification will be received and identified in the listener function for processing. A successful callback (err = 0) means that the room entry is successful, and the billing starts. If the total call duration on the day is below 700 minutes, no fees will be incurred.

• Sample code
  Sample code for processing the callback:

  // Listen on an event:
  ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);
  // Process the event listened on:
  void OnEnterRoomComplete(int err, string errInfo)
  {
  if (err != 0) {
   ShowLoginPanel("error code:" + err + " error message:" + errInfo);
   return;
  }
  else{
  // Entered room successfully
  }
  }
  

• Error code

  Error Code Value	Cause and Suggested Solution
  7006	Authentication failed. Possible causes: The `AppID` does not exist or is incorrect. An error occurred while authenticating the `authbuff`. Authentication expired. The `openId` does not meet the specification.
  7007	Already in another room.
  1001	The user was already in the process of entering a room but repeated this operation. It is recommended not to call the room entering API until the room entry callback is returned.
  1003	The user was already in the room and called the room entering API again.
  1101	Make sure that the SDK is initialized, `openId` complies with the rules, the APIs are called in the same thread, and the `Poll` API is called normally.

2. Enabling or disabling the microphone

This API is used to enable/disable the mic. Mic and speaker are not enabled by default after room entry.

Sample code

// Listen on an event:
ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);
// Process the event listened on:
void OnEnterRoomComplete(int err, string errInfo)
{
if (err != 0) {
ShowLoginPanel("error code:" + err + " error message:" + errInfo);
return;
}
else{
// Entered room successfully
// Enable mic
ITMGContext.GetInstance().GetAudioCtrl().EnableMic(true);
}
}

3. Enabling or disabling the speaker

This API is used to enable/disable the speaker.

Sample code

// Listen on an event:
ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);
// Process the event listened on:
void OnEnterRoomComplete(int err, string errInfo)
{
if (err != 0) {
ShowLoginPanel("error code:" + err + " error message:" + errInfo);
return;
}
else{
// Entered room successfully
// Enable the speaker
ITMGContext.GetInstance().GetAudioCtrl().EnableSpeaker(true);
}
}

4. Exiting the room

This API is called to exit the current room. It needs to wait for and process the callback for exit.

Sample code

ITMGContext.GetInstance().ExitRoom();

Callback for room exit

After the user exits a room, a callback will be returned. The sample code is as shown below:

Listen on an event:
ITMGContext.GetInstance().OnExitRoomCompleteEvent += new QAVExitRoomComplete(OnExitRoomComplete);
Process the event listened on:
void OnExitRoomComplete(){
// Send a callback after room exit
}

Voice Message Access

1. Initializing authentication

Call authentication initialization after initializing the SDK. For more information on how to get the authBuffer, please see genAuthBuffer (the voice chat authentication information API).

Function prototype

ITMGPTT int ApplyPTTAuthbuffer (byte[] authBuffer)

Parameter	Type	Description
authBuffer	String	Authentication

Sample code

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. Starting streaming speech recognition

This API is used to start streaming speech recognition. Text obtained from speech-to-text conversion will be returned in real time in its callback. It can specify a language for recognition or translate the information recognized in speech into a specified language and return the translation. To stop recording, call StopRecording. The callback will be returned after the recording is stopped.

Function prototype

ITMGPTT int StartRecordingWithStreamingRecognition(string filePath)
ITMGPTT int StartRecordingWithStreamingRecognition(string filePath, string speechLanguage,string translateLanguage)

Parameter	Type	Description
filePath	String	Path of stored audio file
speechLanguage	String	The language in which the audio file is to be converted to text. For parameters, please see Language Parameter Reference List
translateLanguage	String	The language into which the audio file will be translated. For parameters, please see Language Parameter Reference List (This parameter is currently unavailable. Enter the same value as that of speechLanguage)

Sample code

string recordPath = Application.persistentDataPath + string.Format("/{0}.silk", sUid++);
int ret = ITMGContext.GetInstance().GetPttCtrl().StartRecordingWithStreamingRecognition(recordPath, "cmn-Hans-CN","cmn-Hans-CN");

Callback for streaming speech recognition

After streaming speech recognition is started, you need to listen for callback messages in the callback function onEvent. The event message is ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE, namely returns text after the recording is stopped and the recognition is completed, which is equivalent to returning the recognized text after a paragraph of speech.

The event message will be identified in the OnEvent function based on the actual needs. The passed parameters include the following four messages.

Message Name	Description
result	A return code for judging whether the streaming speech recognition is successful.
text	Text converted from speech
file_path	Local path of stored recording file
file_id	Backend URL address of recording file, which will be retained for 90 days

• Sample code

  // Listen on an event:
  ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechComplete +=new QAVStreamingRecognitionCallback (OnStreamingSpeechComplete);
  ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechisRunning += new QAVStreamingRecognitionCallback (OnStreamingRecisRunning);
  // Process the event listened on:
  void OnStreamingSpeechComplete(int code, string fileid, string filepath, string result){
  // Callback for streaming speech recognition
  }
  void OnStreamingRecisRunning(int code, string fileid, string filePath, string result){
  if (code == 0)
  {
     setBtnText(mStreamBtn, "Streaming");
     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("Recording");
  }    
  }
  

• Error code

  Error Code	Description	Suggested Solution
  32775	Streaming speech-to-text conversion failed, but recording succeeded.	Call the `UploadRecordedFile` API to upload the recording file and then call the `SpeechToText` API to perform speech-to-text conversion.
  32777	Streaming speech-to-text converting failed, but recording and upload succeeded	The message returned contains a backend URL after successful upload. Call the `SpeechToText` API to perform speech-to-text conversion.
  32786	Streaming speech-to-text conversion failed.	During streaming recording, wait for the execution result of the streaming recording API to return.

3. Stopping recording

This API is used to stop recording. It is async, and a callback for recording completion will be returned after recording stops. A recording file will be available only after recording succeeds.

Function prototype

ITMGPTT int StopRecording()

Sample code

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