tencent cloud

文档反馈

Unity SDK 快速接入

最后更新时间:2024-12-18 14:57:33
    为方便开发者调试和接入腾讯云游戏多媒体引擎产品 API,这里向您介绍 Unity 工程快速接入文档。
    GME 快速入门文档只提供最主要的接入接口,协助用户进行接入。

    使用 GME 重要事项

    GME 分为两个部分,提供实时语音服务、语音消息及转文本服务,使用这两个服务都依赖 Init 和 Poll 等核心接口。
    关于 Init 接口
    例如使用了实时语音服务,同时也需要使用语音消息服务,只需要调用一次 Init 初始化接口

    接口调用流程图

    
    image
    
    

    接入步骤

    集成SDK

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

    核心接口

    实时语音

    语音消息

    核心接口接入

    1. 下载 SDK

    进入下载指引页面,下载对应的 客户端 SDK DownLoad

    2. 引入头文件

    using GME;

    3. 获取 Context 实例

    请使用 ITMGContext 的方法获取 Context 实例,不要直接使用 QAVContext.GetInstance() 去获取实例。

    示例代码

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

    4. 初始化 SDK

    未初始化前,SDK 处于未初始化阶段,需要通过接口 Init 初始化 SDK,才可以使用实时语音服务、语音消息服务及转文本服务。调用 Init 接口的线程必须于其他接口在同一线程,建议都在主线程调用接口。

    接口原型

    //class ITMGContext
    public abstract int Init(string sdkAppID, string openID);
    参数
    类型
    含义
    sdkAppId
    string
    来自 腾讯云控制台 的 GME 服务提供的 AppID,获取请参考 服务开通指引
    openID
    string
    openID 只支持 Int64 类型(转为 string 传入),规则由 App 开发者自行制定,App 内不重复即可。如需使用字符串作为 Openid 传入,可 提交工单 联系开发者。

    示例代码

    int ret = ITMGContext.GetInstance().Init(sdkAppId, openID);
    //通过返回值判断是否初始化成功
    if (ret != QAVError.OK)
    {
    Debug.Log("SDK初始化失败:"+ret);
    return;
    }

    5. 触发事件回调

    通过在 update 里面周期的调用 Poll 可以触发事件回调。Poll 是 GME 的消息泵,GME 需要周期性的调用 Poll 接口触发事件回调。如果没有调用 Poll ,将会导致整个 SDK 服务运行异常。详情请参见 Sample Project 中的 EnginePollHelper 文件。

    示例代码

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

    6. 监听进房、退房通知

    进房通知

    //委托函数:
    public delegate void QAVEnterRoomComplete(int result, string error_info);
    //事件函数:
    public abstract event QAVEnterRoomComplete OnEnterRoomCompleteEvent;

    退房通知

    委托函数:
    public delegate void QAVExitRoomComplete();
    事件函数:
    public abstract event QAVExitRoomComplete OnExitRoomCompleteEvent;

    7. 本地鉴权计算

    生成 AuthBuffer,用于相关功能的加密和鉴权,如正式发布请使用后台部署密钥,后台部署请参考 鉴权密钥

    接口原型

    QAVAuthBuffer GenAuthBuffer(int appId, string roomId, string openId, string key)
    参数
    类型
    含义
    appId
    int
    来自腾讯云控制台的 AppId 号码。
    roomId
    string
    房间号,最大支持127字符(离线语音房间号参数必须填 null)。
    openId
    string
    用户标识。与 Init 时候的 openId 相同。
    key
    string
    来自腾讯云 控制台 的权限密钥。

    示例代码

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

    实时语音接入

    1. 加入房间

    用生成的鉴权信息进房,加入房间默认不打开麦克风及扬声器。返回值为 AV_OK 的时候代表调用成功,不代表进房成功。

    接口原型

    ITMGContext EnterRoom(string roomId, int roomType, byte[] authBuffer)
    参数
    类型
    含义
    roomId
    String
    房间号,最大支持127字符
    roomType
    ITMGRoomType
    只需填 ITMGRoomType.ITMG_ROOM_TYPE_FLUENCY
    authBuffer
    byte[]
    鉴权码

    示例代码

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

    加入房间事件回调

    加入房间完成后会通过回调返回进房结果,监听进房结果事件后进行处理。如果回调为成功,即此时进房成功,开始进行计费
    示例代码
    回调处理相关参考代码。
    //对事件进行监听:
    ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);
    //监听处理:
    void OnEnterRoomComplete(int err, string errInfo)
    {
    if (err != 0) {
    ShowLoginPanel("错误码:" + err + " 错误信息:" + errInfo);
    return;
    }
    else{
    //进房成功
    }
    }
    错误码
    错误码值
    原因及建议方案
    7006
    鉴权失败,原因如下:
    AppID 不存在或者错误
    authbuff 鉴权错误
    鉴权过期
    openId 不符合规范
    7007
    已经在其它房间
    1001
    已经在进房过程中,然后又重复了此操作。建议在进房回调返回之前不要再调用进房接口
    1003
    已经进房了在房间中,又调用一次进房接口
    1101
    确保已经初始化 SDK,确保 openId 是否符合规则,或者确保在同一线程调用接口,以及确保 Poll 接口正常调用

    2. 开启或关闭麦克风

    此接口用来开启关闭麦克风。加入房间默认不打开麦克风及扬声器。

    示例代码

    //对事件进行监听:
    ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);
    //监听处理:
    void OnEnterRoomComplete(int err, string errInfo)
    {
    if (err != 0) {
    ShowLoginPanel("错误码:" + err + " 错误信息:" + errInfo);
    return;
    }
    else{
    //进房成功
    //打开麦克风
    ITMGContext.GetInstance().GetAudioCtrl().EnableMic(true);
    }
    }

    3. 开启或关闭扬声器

    此接口用于开启关闭扬声器。

    示例代码

    //对事件进行监听:
    ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);
    //监听处理:
    void OnEnterRoomComplete(int err, string errInfo)
    {
    if (err != 0) {
    ShowLoginPanel("错误码:" + err + " 错误信息:" + errInfo);
    return;
    }
    else{
    //进房成功
    //打开扬声器
    ITMGContext.GetInstance().GetAudioCtrl().EnableSpeaker(true);
    }
    }

    4. 退出房间

    通过调用此接口可以退出所在房间。需等待退房回调并进行处理。

    示例代码

    ITMGContext.GetInstance().ExitRoom();

    退出房间回调

    退出房间完成后会有回调,示例代码如下:
    对事件进行监听:
    ITMGContext.GetInstance().OnExitRoomCompleteEvent += new QAVExitRoomComplete(OnExitRoomComplete);
    监听处理:
    void OnExitRoomComplete(){
    //退出房间后的处理
    }

    语音消息接入

    1. 鉴权初始化

    在初始化 SDK 之后调用鉴权初始化,authBuffer 的获取参见上文实时语音鉴权信息接口 genAuthBuffer。

    接口原型

    ITMGPTT int ApplyPTTAuthbuffer (byte[] authBuffer)
    参数
    类型
    含义
    authBuffer
    String
    鉴权

    示例代码

    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. 启动流式语音识别

    此接口用于启动流式语音识别,同时在回调中会有实时的语音转文字返回。停止录音调用 StopRecording,停止之后才有回调。

    接口原型

    ITMGPTT int StartRecordingWithStreamingRecognition(string filePath)
    参数
    类型
    含义
    filePath
    String
    存放的语音路径

    示例代码

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

    流式语音识别回调

    启动流式语音识别后,需要通过在 OnStreamingSpeechComplete 或者 OnStreamingRecisRunning 通知中监听回调消息,事件消息分为以下两个:
    OnStreamingSpeechComplete 是在停止录制并完成识别后才返回文字,相当于一段话说完才会返回识别的文字。
    OnStreamingSpeechisRunning 是在录音过程中就会实时返回识别到的文字,相当于边说话边返回识别到的文字。
    根据需求在 OnEvent 函数中对相应事件消息进行判断。传递的参数包含以下4个信息。
    消息名称
    含义
    result
    用于判断流式语音识别是否成功的返回码
    text
    语音转文字识别的文本
    file_path
    录音存放的本地地址
    file_id
    录音在后台的 url 地址,录音在服务器存放90天
    示例代码
    //对事件进行监听:
    ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechComplete +=new QAVStreamingRecognitionCallback (OnStreamingSpeechComplete);
    ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechisRunning += new QAVStreamingRecognitionCallback (OnStreamingRecisRunning);
    //监听处理:
    void OnStreamingSpeechComplete(int code, string fileid, string filepath, string result){
    //启动流式语音识别的回调
    }
    void OnStreamingRecisRunning(int code, string fileid, string filePath, string result){
    if (code == 0)
    {
    setBtnText(mStreamBtn, "流式");
    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("录制中");
    }
    }
    错误码
    错误码
    含义
    处理方式
    32775
    流式语音转文本失败,但是录音成功
    调用 UploadRecordedFile 接口上传录音,再调用 SpeechToText 接口进行语音转文字操作
    32777
    流式语音转文本失败,但是录音成功,上传成功
    返回的信息中有上传成功的后台 url 地址,调用 SpeechToText 接口进行语音转文字操作
    32786
    流式语音转文本失败
    在流式录制状态当中,请等待流式录制接口执行结果返回

    3. 停止录音

    此接口用于停止录音。此接口为异步接口,停止录音后会有录音完成回调,成功之后录音文件才可用。

    接口原型

    ITMGPTT int StopRecording()

    示例代码

    ITMGContext.GetInstance().GetPttCtrl().StopRecording();
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持