tencent cloud

文档反馈

Native SDK 快速接入

最后更新时间:2022-06-08 16:55:28

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

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

    使用 GME 重要事项

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

    关于 Init 接口

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

    接口调用流程图

    image

    接入步骤

    核心接口

    初始化 GME接口:Init
    周期性调用 Poll 触发回调接口:Poll

    实时语音

    语音消息

    反初始化 GME接口:UnInit

    核心接口接入

    1. 下载 Demo

    进入下载指引页面,下载对应的客户端 Demo 工程代码DownLoad

    2. 引入头文件

    import com.tencent.TMG.ITMGContext;
    import com.tencent.av.sig.AuthBuffer;
    import com.tencent.bugly.crashreport.CrashReport;

    3. 获取单例

    在使用语音功能时,需要首先获取 ITMGContext 对象。

    函数原型

    public static ITMGContext GetInstance(Context context)

    示例代码

    //MainActivity.java
    import com.tencent.TMG.ITMGContext;
    ITMGContext tmgContext = ITMGContext.GetInstance(this);

    4. 设置回调

    接口类采用 Delegate 方法用于向应用程序发送回调通知。将回调函数注册给 SDK,用于接收回调的信息,需要在进房之前设置。

    函数原型及示例代码

    设置回调,用于接收回调的信息,需要在进房之前设置。

    //ITMGContext
    public abstract int SetTMGDelegate(ITMGDelegate delegate);

    //MainActivity.java
    tmgContext.SetTMGDelegate(TMGCallbackDispatcher.getInstance());

    回调示例

    在构造函数中重写此回调函数,对回调参数进行处理。

    //MainActivity.java
    tmgContext.SetTMGDelegate(TMGCallbackDispatcher.getInstance());

    //RealTimeVoiceActivity.java
    public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data) {
    if (type == ITMG_MAIN_EVENT_TYPE_ENTER_ROOM)
    {
    //回调处理
    }
    }

    //需要参考 TMGCallbackDispatcher.java、TMGCallbackHelper.java以及 TMGDispatcherBase.java
    参数 类型 含义
    type ITMGContext.ITMG_MAIN_EVENT_TYPE 回调的事件类型
    data Intent 消息类型 回调的相关信息,事件数据

    5. 初始化 SDK

    • 此接口用于初始化 GME 服务,建议应用侧在应用初始化时候调用。
    • **参数 sdkAppId 获取请参见 语音服务开通指引**。
    • OpenId 用于唯一标识一个用户,目前只支持 INT64,规则由 App 开发者自行制定,App 内不重复即可

    函数原型

    public abstract int Init(String sdkAppId, String openId);
    参数 类型 含义
    sdkAppId String 来自 腾讯云控制台 的 GME 服务提供的 AppId。
    OpenId String OpenId 只支持 Int64 类型(转为 string 传入)。

    示例代码

    //MainActivity.java
    int nRet = tmgContext.Init(appId, openId);
    if (nRet == AV_OK )
    {
    GMEAuthBufferHelper.getInstance().setGEMParams(appId, key, openId);
    // Step 4/11: Poll to trigger callback
    //https://www.tencentcloud.com/document/product/607/15210?from_cn_redirect=1#.E8.A7.A6.E5.8F.91.E4.BA.8B.E4.BB.B6.E5.9B.9E.E8.B0.83
    EnginePollHelper.createEnginePollHelper();
    showToast("Init success")
    ;
    }else if (nRet == AV_ERR_HAS_IN_THE_STATE) // 已经初始化过了,可以认为本次操作是成功的
    {
    showToast("Init success")
    ;
    }else
    {
    showToast("Init error errorCode:" + nRet)
    ;
    }

    6. 触发事件回调

    通过在 update 里面周期的调用 Poll 可以触发事件回调。GME 需要周期性的调用 Poll 接口触发事件回调。如果没有调用 Poll 的话,会导致整个 SDK 服务运行异常。

    可参考 Demo 中的 EnginePollHelper.java 文件。

    示例代码

    //MainActivity.java
    [EnginePollHelper createEnginePollHelper];

    //EnginePollHelper.java
    private Handler mhandler = new Handler();
    private Runnable mRunnable = new Runnable() {
    @Override
    public void run() {
    if (s_pollEnabled)
    {
    if (ITMGContext.GetInstance(null) !
    = null)
    ITMGContext.GetInstance(null).Poll();
    }
    mhandler.postDelayed(mRunnable, 33);
    }
    };
    //周期性调用 Poll 请参考 EnginePollHelper.java 写法

    7. 鉴权信息

    生成 AuthBuffer,用于相关功能的加密和鉴权。
    语音消息及转文本获取鉴权时,房间号参数必须填 null。

    函数原型

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

    示例代码

    //GMEAuthBufferHelper.java
    import com.tencent.av.sig.AuthBuffer;//头文件
    public byte[] createAuthBuffer(String roomId)
    {
    byte[] authBuffer;
    // Generate AuthBuffer for encryption and authentication of relevant features. For release in the production environment,
    // please use the backend deployment key as detailed in https://www.tencentcloud.com/document/product/607/12218
    if (TextUtils.isEmpty(roomId))
    {
    authBuffer = AuthBuffer.getInstance().genAuthBuffer(Integer.parseInt(mAppId), "0", mOpenId, mKey);
    }else
    {
    authBuffer = AuthBuffer.getInstance().genAuthBuffer(Integer.parseInt(mAppId), roomId, mOpenId, mKey);
    }
    return authBuffer;
    }

    实时语音接入

    1. 加入房间

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

    房间音频类型请参考 音质选择

    函数原型

    public abstract int EnterRoom(String roomID, int roomType, byte[] authBuffer);
    参数 类型 含义
    roomId String 房间号,最大支持127字符
    roomType int 房间音频类型
    authBuffer byte[] 鉴权码

    示例代码

    //RealTimeVoiceActivity.java
    byte[] authBuffer = GMEAuthBufferHelper.getInstance().createAuthBuffer(roomId);
    ITMGContext.GetInstance(this).EnterRoom(roomId, roomType, authBuffer);

    加入房间事件回调

    加入房间完成后会发送信息 ITMG_MAIN_EVENT_TYPE_ENTER_ROOM,在 OnEvent 函数中进行判断回调后处理。如果回调为成功,即此时进房成功,开始进行计费

    • 示例代码
      回调处理相关参考代码,包括加入房间事件以及断网事件。
      //RealTimeVoiceActivity.java
      public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data) {
      if (type == ITMG_MAIN_EVENT_TYPE_ENTER_ROOM)
      {
      // Step 6/11 : Perform the enter room event
      int nErrCode = TMGCallbackHelper.ParseIntentParams2(data).nErrCode;
      String strMsg = TMGCallbackHelper.ParseIntentParams2(data).strErrMsg;
      if (nErrCode == AV_OK)
      {
      appendLog2MonitorView("EnterRomm success")
      ;
      }else
      {
      appendLog2MonitorView(String.format(Locale.getDefault(), "EnterRomm errCode:%d errMsg:%s", nErrCode, strMsg))
      ;
      }
      }
      }
    • 错误码
      错误码值 原因及建议方案
      7006 鉴权失败,原因如下:
      • AppID 不存在或者错误
      • authbuff 鉴权错误
      • 鉴权过期
      • openId 不符合规范
      7007 已经在其它房间
      1001 已经在进房过程中,然后又重复了此操作。建议在进房回调返回之前不要再调用进房接口
      1003 已经进房了在房间中,又调用一次进房接口
      1101 确保已经初始化 SDK,确保 openId 是否符合规则,或者确保在同一线程调用接口,以及确保 Poll 接口正常调用

    2. 开启或关闭麦克风

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

    示例代码

    //RealTimeVoiceActivity.java
    ITMGContext.GetInstance(this).GetAudioCtrl().EnableMic(true);

    3. 开启或关闭扬声器

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

    示例代码

    //RealTimeVoiceActivity.java
    ITMGContext.GetInstance(this).GetAudioCtrl().EnableSpeaker(true);

    4. 退出房间

    通过调用此接口可以退出所在房间。这是一个异步接口,返回值为 AV_OK 的时候代表异步投递成功。

    示例代码

    //RealTimeVoiceActivity.java
    ITMGContext.GetInstance(this).ExitRoom();

    退出房间回调

    退出房间完成后会有回调,消息为 ITMG_MAIN_EVENT_TYPE_EXIT_ROOM。示例代码如下:

    //RealTimeVoiceActivity.java
    public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data) {
    if (ITMGContext.ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_EXIT_ROOM == type)
    {
    //收到退房成功事件
    }
    }

    语音消息接入

    1. 鉴权初始化

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

    函数原型

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

    示例代码

    //VoiceMessageRecognitionActivity.java
    byte[] authBuffer = GMEAuthBufferHelper.getInstance().createAuthBuffer("");
    ITMGContext.GetInstance(this).GetPTT().ApplyPTTAuthbuffer(authBuffer);

    2. 启动流式语音识别

    此接口用于启动流式语音识别,同时在回调中会有实时的语音转文字返回,可以指定语言进行识别,也可以将语音中识别到的信息翻译成指定的语言返回。停止录音调用 StopRecording,停止之后才有回调。

    接口原型

    public abstract int StartRecordingWithStreamingRecognition (String filePath);
    public abstract int StartRecordingWithStreamingRecognition (String filePath,String language,String translatelanguage)
    ;
    public abstract int StopRecording()
    ;
    参数 类型 含义
    filePath String 存放的语音路径
    speechLanguage String 识别成指定文字的语言参数,参数请参考 语音转文字的语言参数参考列表
    translateLanguage String 翻译成指定文字的语言参数,参数请参考 语音转文字的语言参数参考列表(此参数暂不可用,请填写与 speechLanguage 相同的参数)

    示例代码

    //VoiceMessageRecognitionActivity.java
    ITMGContext.GetInstance(this).GetPTT().StartRecordingWithStreamingRecognition(recordfilePath,"cmn-Hans-CN");

    流式语音识别回调

    启动流式语音识别后,需要在回调函数 OnEvent 中监听回调消息,事件消息分为 ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE ,在停止录制并完成识别后才返回文字,相当于一段话说完才会返回识别的文字。

    根据需求在 OnEvent 函数中对相应事件消息进行判断。传递的参数包含以下4个信息。

    消息名称 含义
    result 用于判断流式语音识别是否成功的返回码
    text 语音转文字识别的文本
    file_path 录音存放的本地地址
    file_id 录音在后台的 url 地址,录音在服务器存放90天
    • 示例代码
      //VoiceMessageRecognitionActivity.java
      import static com.tencent.TMG.ITMGContext.ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE;
      public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data)
      {
      if (type == ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE)
      {
      // Step 1.3/3 handle ITMG_MAIN_EVNET_TYPE_PTT_STREAMINGRECOGNITION_COMPLETE event
      mIsRecording = false;
      if (nErrCode ==0)
      {
      String recordfilePath = data.getStringExtra("file_path");
      mRecFilePathView.setText(recordfilePath);

      String recordFileUrl = data.getStringExtra("file_id");
      mRecFileUrlView.setText(recordFileUrl);
      }
      else
      {
      appendLog2MonitorView("Record and recognition fail errCode:" + nErrCode)
      ;
      }
      }

      }
    • 错误码
      错误码 含义 处理方式
      32775 流式语音转文本失败,但是录音成功 调用 UploadRecordedFile 接口上传录音,再调用 SpeechToText 接口进行语音转文字操作
      32777 流式语音转文本失败,但是录音成功,上传成功 返回的信息中有上传成功的后台 url 地址,调用 SpeechToText 接口进行语音转文字操作
      32786 流式语音转文本失败 在流式录制状态当中,请等待流式录制接口执行结果返回

    3. 停止录音

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

    接口原型

    public abstract int StopRecording();

    示例代码

    //VoiceMessageRecognitionActivity.java
    ITMGContext.GetInstance(this).GetPTT().StopRecording();
    联系我们

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

    技术支持

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

    7x24 电话支持