tencent cloud

Feedback

Quick Integration of SDK for Unity

Last updated: 2024-12-18 14:51:59
    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 messaging 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 messaging services at the same time, you only need to call Init API once.

    API call flowchart

    
    image
    
    

    Directions

    Integrating SDK

    To integrate the SDK into the project, see Integrating SDK.

    Core APIs

    Voice Chat

    Voice Message

    Key API Access

    1. Download the SDK

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

    2. Importing the header file

    using GME;

    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

    You need to initialize the SDK through the Init API before you can use the real-time voice, voice message, and speech-to-text services. The Init API must be called in the same thread as other APIs. We recommend you call all APIs in the main thread.

    API prototype

    //class ITMGContext
    public abstract int Init(string sdkAppID, string openID);
    Parameter
    Type
    Description
    sdkAppId
    string
    AppID provided in the GME console, which can be obtained as instructed in Activating Services.
    openID
    string
    openID can only be in Int64 type, which is passed in after being converted to a string. You can customize its rules, and it must be unique in the application. To pass in openID as a string, submit a ticket for application.

    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 is GME's message pump and should be called periodically for GME to trigger event callbacks; otherwise, the entire SDK service will run abnormally. For more information, see the EnginePollHelper file in SDK Download Guide.

    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. Calculating the local authentication key

    Generate AuthBuffer for encryption and authentication of relevant features. For release in the production environment, please use the backend deployment key as detailed in Authentication Key.

    API 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 AV_OK indicates successful API call but not successful room entry.

    API prototype

    ITMGContext EnterRoom(string roomId, int roomType, byte[] authBuffer)
    Parameter
    Type
    Description
    roomId
    String
    Room ID, which can contain up to 127 characters
    roomType
    ITMGRoomType
    Just enter ITMGRoomType.ITMG_ROOM_TYPE_FLUENCY
    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, the room entry result will be called back, which can be listened on for processing. A successful callback means that the room entry is successful, and the billing starts.
    Sample codeSample 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. Turning on or off the microphone

    This API is used to turn on of off the mic. Mic and speaker are not turned on 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
    // Turn on mic
    ITMGContext.GetInstance().GetAudioCtrl().EnableMic(true);
    }
    }

    3. Turning on or off the speaker

    This API is used to turn on/off 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
    // Turn on 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).

    API 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. To stop recording, call StopRecording. The callback will be returned after the recording is stopped.

    API prototype

    ITMGPTT int StartRecordingWithStreamingRecognition(string filePath)
    Parameter
    Type
    Description
    filePath
    String
    Path of stored audio file

    Sample code

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

    Callback for streaming speech recognition

    After streaming speech recognition is started, you need to listen on callback messages in the OnStreamingSpeechComplete or OnStreamingSpeechisRunning notification, which is as detailed below:
    OnStreamingSpeechComplete 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.
    OnStreamingSpeechisRunning returns the recognized text in real time during the recording, which is equivalent to returning the recognized text while speaking.
    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.

    API prototype

    ITMGPTT int StopRecording()

    Sample code

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

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support