接口文档

最近更新时间:2019-10-14 15:18:27

为方便 Unity 开发者调试和接入腾讯云游戏多媒体引擎产品 API,这里向您介绍适用于 Unity 开发的接入技术文档。

说明:

此文档对应 GME sdk version:2.5。

使用 GME 重要事项

重要接口 接口含义
Init 初始化 GME
Poll 触发事件回调
EnterRoom 进房
EnableMic 开麦克风
EnableSpeaker 开扬声器
说明:

  • GME 使用前请对工程进行配置,否则 SDK 不生效。
  • GME 的接口调用成功后返回值为 QAVError.OK,数值为 0。
  • GME 的接口调用要在同一个线程下。
  • GME 加入房间需要鉴权,请参考文档关于鉴权部分内容。
  • GME 需要周期性的调用 Poll 接口触发事件回调。
  • GME 回调信息参考回调消息列表。
  • 设备的操作要在进房成功之后。
  • 错误码详情可参考 错误码

实时语音流程图

初始化相关接口

未初始化前,SDK 处于未初始化阶段,需要通过接口 Init 初始化 SDK,才可以使用实时语音及离线语音。
使用问题可参考 一般性问题

接口 接口含义
Init 初始化 GME
Poll 触发事件回调
Pause 系统暂停
Resume 系统恢复
Uninit 反初始化 GME

获取实例

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

初始化 SDK

参数获取请查看 接入指引
此接口需要来自腾讯云控制台的 SDKAppID 号码作为参数,再加上 openId,这个 openId 是唯一标识一个用户,规则由 App 开发者自行制定,App 内不重复即可(目前只支持 INT64)。

注意:

初始化 SDK 之后才可以进房。

函数原型

ITMGContext Init(string sdkAppId, string openId)
参数 类型 含义
sdkAppId String 来自腾讯云控制台的 sdkAppId 号码
openId String openId 只支持 Int64 类型(转为 string 传入),必须大于10000,用于标识用户

示例代码

int ret = ITMGContext.GetInstance().Init(str_appId, str_openID);
    if (ret != QAVError.OK) {
        return;
    }

触发事件回调

通过在 update 里面周期的调用 Poll 可以触发事件回调。

函数原型

ITMGContext public abstract int Poll();

系统暂停

当系统发生 Pause 事件时,需要同时通知引擎进行 Pause。

函数原型

ITMGContext public abstract int Pause()

系统恢复

当系统发生 Resume 事件时,需要同时通知引擎进行 Resume。Resume 接口只恢复实时语音。

函数原型

ITMGContext  public abstract int Resume()

反初始化 SDK

反初始化 SDK,进入未初始化状态。切换账号需要反初始化。

函数原型

ITMGContext public abstract int Uninit()

实时语音房间相关接口

初始化之后,SDK 调用进房后进去了房间,才可以进行实时语音通话。
使用问题可参考实时语音相关问题

接口 接口含义
GenAuthBuffer 初始化鉴权
EnterRoom 加入房间
IsRoomEntered 是否已经进入房间
ExitRoom 退出房间
ChangeRoomType 修改用户房间音频类型
GetRoomType 获取用户房间音频类型

鉴权信息

生成 AuthBuffer,用于相关功能的加密和鉴权,相关后台部署请参考 鉴权密钥
离线语音获取鉴权时,房间号参数必须填 null。

函数原型

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

示例代码

byte[] GetAuthBuffer(string appId, string userId, string roomId)
    {
    return QAVAuthBuffer.GenAuthBuffer(int.Parse(appId), roomId,openID, "a495dca2482589e9");
}

加入房间

用生成的鉴权信息进房。加入房间默认不打开麦克风及扬声器。

范围语音接入流程请查看 范围语音

函数原型

ITMGContext EnterRoom(string roomId, int roomType, byte[] authBuffer)
参数 类型 含义
roomId string 房间号,最大支持127字符
roomType ITMGRoomType 房间音频类型
authBuffer Byte[] 鉴权码

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

示例代码

ITMGContext.GetInstance().EnterRoom(roomId, ITMG_ROOM_TYPE_FLUENCY, authBuffer);

加入房间事件的回调

加入房间后,需要通过委托函数进行回调。其中包含两个信息:result 及 error_info。

函数原型

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

示例代码

对事件进行监听:
ITMGContext.GetInstance().OnEnterRoomCompleteEvent += new QAVEnterRoomComplete(OnEnterRoomComplete);

监听处理:
void OnEnterRoomComplete(int err, string errInfo)
    {
    if (err != 0) {
        ShowWarnning (string.Format ("join room failed, err:{0}, errInfo:{1}", err, errInfo));
        return;
    }else{
        ShowWarnning (string.Format ("当前语音房间id:{0},请在别的终端加入这个房间进行通话",roomId ));
    }
}

判断是否已经进入房间

通过调用此接口可以判断是否已经进入房间,返回值为 bool 类型。

函数原型

ITMGContext abstract bool IsRoomEntered()

示例代码

ITMGContext.GetInstance().IsRoomEntered();

退出房间

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

注意:

如果应用中有退房后立即进房的场景,在接口调用流程上,开发者无需要等待 ExitRoom 的回调 RoomExitComplete 通知,只需直接调用接口。

函数原型

ITMGContext ExitRoom()

示例代码

ITMGContext.GetInstance().ExitRoom();

退出房间回调

退出房间完成回调,通过委托传递消息。

函数原型

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

示例代码

对事件进行监听:
ITMGContext.GetInstance().OnExitRoomCompleteEvent += new QAVExitRoomComplete(OnExitRoomComplete);
监听处理:
void OnExitRoomComplete(){
    //退出房间后的处理
}

获取用户房间音频类型

此接口用于获取用户房间音频类型,返回值为房间音频类型,返回值为0时代表获取用户房间音频类型发生错误,房间音频类型参考 EnterRoom 接口。

函数原型

ITMGContext ITMGRoom public  int GetRoomType()

示例代码

ITMGContext.GetInstance().GetRoom().GetRoomType();

修改用户房间音频类型

此接口用于修改用户房间音频类型。

函数原型

ITMGContext ITMGRoom public void ChangeRoomType(ITMGRoomType roomtype)
参数 类型 含义
roomtype ITMGRoomType 希望房间切换成的类型,房间音频类型参考 EnterRoom 接口

示例代码

ITMGContext.GetInstance().GetRoom().ChangeRoomType(ITMG_ROOM_TYPE_FLUENCY);

修改房间音频类型回调

主动设置房间类型,房间类型设置后,通过委托传递修改完成的相关消息。

返回的参数 含义
result 0 是代表成功
error_info 如果失败,会传递相关错误信息
委托函数:
public delegate void QAVOnChangeRoomtypeCallback(int result, string error_info);

事件函数:
public abstract event QAVCallback OnChangeRoomtypeCallback; 

示例代码

对事件进行监听:
ITMGContext.GetInstance().OnChangeRoomtypeCallback += new QAVOnChangeRoomtypeCallback(OnChangeRoomtypeCallback);
监听处理:
void OnChangeRoomtypeCallback(int result, string error_info){
    //房间类型设置完成后的处理
}

房间类型变化通知

用户主动修改房间类型,或者房间内其它用户修改房间类型,只要房间类型发生变化,该回调函数就会被调用,通过次回调函数通知业务层房间类型发生变化,返回的是房间类型,参考 EnterRoom 接口。

委托函数:
public delegate void QAVOnRoomTypeChangedEvent(int roomtype);

事件函数:
public abstract event QAVOnRoomTypeChangedEvent OnRoomTypeChangedEvent;    

示例代码

对事件进行监听:
ITMGContext.GetInstance().OnRoomTypeChangedEvent += new QAVOnRoomTypeChangedEvent(OnRoomTypeChangedEvent);
监听处理:
void OnRoomTypeChangedEvent(int roomtype){
    //房间类型改变后的处理
}

成员状态变化

该事件在状态变化才通知,状态不变化的情况下不通知。如需实时获取成员状态,请在上层收到通知时缓存,事件消息为 ITMG_MAIN_EVNET_TYPE_USER_UPDATE,包含 event_id、count 及 openIdList,在 OnEvent 函数中对事件消息进行判断。
音频事件的通知有一个阈值,超过这个阈值才会发送通知。超过两秒没有收到音频包才通知“有成员停止发送音频包”消息。

event_id 含义 应用侧维护内容
ITMG_EVENT_ID_USER_ENTER 有成员进入房间 应用侧维护成员列表
ITMG_EVENT_ID_USER_EXIT 有成员退出房间 应用侧维护成员列表
ITMG_EVENT_ID_USER_HAS_AUDIO 有成员发送音频包 应用侧维护通话成员列表
ITMG_EVENT_ID_USER_NO_AUDIO 有成员停止发送音频包 应用侧维护通话成员列表

示例代码

委托函数:
public delegate void QAVEndpointsUpdateInfo(int eventID, int count, [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)]string[] openIdList);
事件函数:
public abstract event QAVEndpointsUpdateInfo OnEndpointsUpdateInfoEvent;

对事件进行监听:
ITMGContext.GetInstance().OnEndpointsUpdateInfoEvent += new QAVEndpointsUpdateInfo(OnEndpointsUpdateInfo);
监听处理:
void OnEndpointsUpdateInfo(int eventID, int count, string[] openIdList)
{
    //进行处理

            switch (eventID)
             {
             case ITMG_EVENT_ID_USER_ENTER:
                  //有成员进入房间
                  break;
             case ITMG_EVENT_ID_USER_EXIT:
                  //有成员退出房间
                break;
            case ITMG_EVENT_ID_USER_HAS_AUDIO:
                //有成员发送音频包
                break;
            case ITMG_EVENT_ID_USER_NO_AUDIO:
                //有成员停止发送音频包
                break;

            default:
                break;
             }
        break;
}

质量监控事件

质量监控事件,事件消息为 ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_QUALITY,返回的参数为 weight、floss 及 delay,代表的信息如下,在 OnEvent 函数中对事件消息进行判断。

参数 含义
weight 范围是 1-5,数值为5是音质评分极好,数值为1是音质评分很差,几乎不能使用,数值为0代表初始值,无含义
floss 丢包率
delay 音频触达延迟时间(ms)

实时语音音频接口

初始化 SDK 之后进房,在房间中,才可以调用实时音频语音相关接口。
当用户界面单击打开/关闭麦克风/扬声器按钮时,建议如下方式:

  • 对于大部分的游戏类 App,推荐调用 EnableMic 及 EnableSpeaker 接口,相当于总是应该同时调用 EnableAudioCaptureDevice/EnableAudioSend 和 EnableAudioPlayDevice/EnableAudioRecv 接口;
  • 其他类型的移动端 App 例如社交类型 App,打开或者关闭采集设备,会伴随整个设备(采集及播放)重启,如果此时 App 正在播放背景音乐,那么背景音乐的播放也会被中断。利用控制上下行的方式来实现开关麦克风效果,不会中断播放设备。具体调用方式为:在进房的时候调用 EnableAudioCaptureDevice(true) && EnableAudioPlayDevice(true) 一次,单击开关麦克风时只调用 EnableAudioSend/Recv 来控制音频流是否发送/接收。
  • 如果想单独释放采集或者播放设备,请参考接口 EnableAudioCaptureDevice 及 EnableAudioPlayDevice。
  • 调用 pause 暂停音频引擎,调用 resume 恢复音频引擎。
接口 接口含义
EnableMic 开关麦克风
GetMicState 获取麦克风状态
EnableAudioCaptureDevice 开关采集设备
IsAudioCaptureDeviceEnabled 获取采集设备状态
EnableAudioSend 打开关闭音频上行
IsAudioSendEnabled 获取音频上行状态
GetMicLevel 获取实时麦克风音量
GetSendStreamLevel 获取音频上行实时音量
SetMicVolume 设置麦克风音量
GetMicVolume 获取麦克风音量
EnableSpeaker 开关扬声器
GetSpeakerState 获取扬声器状态
EnableAudioPlayDevice 开关播放设备
IsAudioPlayDeviceEnabled 获取播放设备状态
EnableAudioRecv 打开关闭音频下行
IsAudioRecvEnabled 获取音频下行状态
GetSpeakerLevel 获取实时扬声器音量
GetRecvStreamLevel 获取房间内其他成员下行实时音量
SetSpeakerVolume 设置扬声器音量
GetSpeakerVolume 获取扬声器音量
EnableLoopBack 开关耳返

开启关闭麦克风

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

函数原型

ITMGAudioCtrl EnableMic(bool isEnabled)
参数 类型 含义
isEnabled boolean 如果需要打开麦克风,则传入的参数为 true,如果关闭麦克风,则参数为 false

示例代码

打开麦克风
ITMGContext.GetInstance().GetAudioCtrl().EnableMic(true);

麦克风状态获取

此接口用于获取麦克风状态,返回值0为关闭麦克风状态,返回值1 为打开麦克风状态。

函数原型

ITMGAudioCtrl GetMicState()

示例代码

micToggle.isOn = ITMGContext.GetInstance().GetAudioCtrl().GetMicState();

开启关闭采集设备

此接口用来开启/关闭采集设备。加入房间默认不打开设备。

  • 只能在进房后调用此接口,退房会自动关闭设备。
  • 在移动端,打开采集设备通常会伴随权限申请,音量类型调整等操作。

函数原型

ITMGAudioCtrl int EnableAudioPlayDevice(bool isEnabled)
参数 类型 含义
isEnabled bool 如果需要打开采集设备,则传入的参数为 true,如果关闭采集设备,则参数为 false

示例代码

打开采集设备
ITMGContext.GetInstance().GetAudioCtrl().EnableAudioCaptureDevice(true);

采集设备状态获取

此接口用于采集设备状态获取。

函数原型

ITMGAudioCtrl bool IsAudioCaptureDeviceEnabled()

示例代码

bool IsAudioCaptureDevice = ITMGContext.GetInstance().GetAudioCtrl().IsAudioCaptureDeviceEnabled();

打开关闭音频上行

此接口用于打开/关闭音频上行。如果采集设备已经打开,那么会发送采集到的音频数据。如果采集设备没有打开,那么仍旧无声。采集设备的打开关闭参见接口 EnableAudioCaptureDevice。

函数原型

ITMGAudioCtrl int EnableAudioSend(bool isEnabled)
参数 类型 含义
isEnabled bool 如果需要打开音频上行,则传入的参数为 true,如果关闭音频上行,则参数为 false

示例代码

ITMGContext.GetInstance().GetAudioCtrl().EnableAudioSend(true);

音频上行状态获取

此接口用于音频上行状态获取。

函数原型

ITMGAudioCtrl bool IsAudioSendEnabled()

示例代码

bool IsAudioSend = ITMGContext.GetInstance().GetAudioCtrl().IsAudioSendEnabled();

获取麦克风实时音量

此接口用于获取麦克风实时音量,返回值为 int 类型。

函数原型

ITMGAudioCtrl int GetMicLevel

示例代码

ITMGContext.GetInstance().GetAudioCtrl().GetMicLevel();

获取音频上行实时音量

此接口用于获取音频上行实时音量,返回值为 int 类型,取值范围为0到100。

函数原型

ITMGAudioCtrl int GetSendStreamLevel()

示例代码

int Level = ITMGContext.GetInstance().GetAudioCtrl().GetSendStreamLevel();

设置麦克风的音量

此接口用于设置麦克风的音量。参数 volume 用于设置麦克风的音量,当数值为0的时候表示静音,当数值为100 的时候表示音量不增不减,默认数值为100。

函数原型

ITMGAudioCtrl SetMicVolume(int volume)
参数 类型 含义
volume int 设置音量,范围0到200

示例代码

int micVol = (int)(value * 100);
ITMGContext.GetInstance().GetAudioCtrl().SetMicVolume (micVol);

获取麦克风的音量

此接口用于获取麦克风的音量。返回值为一个int类型数值,返回值为101代表没调用过接口 SetMicVolume。

函数原型

ITMGAudioCtrl GetMicVolume()

示例代码

ITMGContext.GetInstance().GetAudioCtrl().GetMicVolume();

开启关闭扬声器

此接口用于开启关闭扬声器。
EnableSpeaker = EnableAudioPlayDevice + EnableAudioRecv.

函数原型

ITMGAudioCtrl EnableSpeaker(bool isEnabled)
参数 类型 含义
isEnabled bool 如果需要关闭扬声器,则传入的参数为 false,如果打开扬声器,则参数为 true

示例代码

打开扬声器
ITMGContext.GetInstance().GetAudioCtrl().EnableSpeaker(true);

扬声器状态获取

此接口用于扬声器状态获取。返回值 0 为关闭扬声器状态,返回值1 为打开扬声器状态,返回值2 为扬声器设备正在操作中。

函数原型

ITMGAudioCtrl GetSpeakerState()

示例代码

speakerToggle.isOn = ITMGContext.GetInstance().GetAudioCtrl().GetSpeakerState();

开启关闭播放设备

此接口用于开启关闭播放设备。

函数原型

ITMGAudioCtrl EnableAudioPlayDevice(bool isEnabled)
参数 类型 含义
isEnabled bool 如果需要关闭播放设备,则传入的参数为 false,如果打开播放设备,则参数为 true

示例代码

打开播放设备
ITMGContext.GetInstance().GetAudioCtrl().EnableAudioPlayDevice(true);

播放设备状态获取

此接口用于播放设备状态获取。

函数原型

ITMGAudioCtrl bool IsAudioPlayDeviceEnabled()

示例代码

bool IsAudioPlayDevice = ITMGContext.GetInstance().GetAudioCtrl().IsAudioPlayDeviceEnabled();

打开关闭音频下行

此接口用于打开/关闭音频下行。如果播放设备已经打开,那么会播放房间里其他人的音频数据。如果播放设备没有打开,那么仍旧无声。播放设备的打开关闭参见接口 参见 EnableAudioPlayDevice。

函数原型

ITMGAudioCtrl int EnableAudioRecv(bool isEnabled)
参数 类型 含义
isEnabled bool 如果需要打开音频下行,则传入的参数为 true,如果关闭音频下行,则参数为 false

示例代码

ITMGContext.GetInstance().GetAudioCtrl().EnableAudioRecv(true);

音频下行状态获取

此接口用于音频下行状态获取。

函数原型

ITMGAudioCtrl bool IsAudioRecvEnabled()

示例代码

bool IsAudioRecv = ITMGContext.GetInstance().GetAudioCtrl().IsAudioRecvEnabled();

获取扬声器实时音量

此接口用于获取扬声器实时音量。返回值为 int 类型数值,表示扬声器实时音量。

函数原型

ITMGAudioCtrl GetSpeakerLevel()

示例代码

ITMGContext.GetInstance().GetAudioCtrl().GetSpeakerLevel();

获取房间内其他成员下行实时音量

此接口用于获取房间内其他成员下行实时音量,返回值为 int 类型,取值范围为0到100。

函数原型

ITMGAudioCtrl int GetRecvStreamLevel(string openId)
参数 类型 含义
openId string 房间其他成员的openId

示例代码

int Level = ITMGContext.GetInstance().GetAudioCtrl().GetRecvStreamLevel(openId);

设置扬声器的音量

此接口用于设置扬声器的音量。
参数 volume 用于设置扬声器的音量,当数值为 0 的时候表示静音,当数值为 100 的时候表示音量不增不减,默认数值为 100。

函数原型

ITMGAudioCtrl SetSpeakerVolume(int volume)
参数 类型 含义
volume int 设置音量,范围0到200

示例代码

int speVol = (int)(value * 100);
ITMGContext.GetInstance().GetAudioCtrl().SetSpeakerVolume(speVol);

获取扬声器的音量

此接口用于获取扬声器的音量。返回值为 int 类型数值,代表扬声器的音量,返回值为101代表没调用过接口 SetSpeakerVolume。
Level 是实时音量,Volume 是扬声器的音量,最终声音音量相当于 Level*Volume%。举个例子:实时音量是数值是 100 的话,此时Volume的数值是 60,那么最终发出来的声音数值也是 60。

函数原型

ITMGAudioCtrl GetSpeakerVolume()

示例代码

ITMGContext.GetInstance().GetAudioCtrl().GetSpeakerVolume();

启动耳返

此接口用于启动耳返。

函数原型

ITMGContext GetAudioCtrl EnableLoopBack(bool enable)
参数 类型 含义
enable bool 设置是否启动

示例代码

ITMGContext.GetInstance().GetAudioCtrl().EnableLoopBack(true);

设备占用和释放事件回调

在房间内,占用设备和释放设备时会回调,通过委托传递事件的相关消息。

委托函数:
public delegate void QAVOnDeviceStateChangedEvent(int deviceType, string deviceId, bool openOrClose);
事件函数:
public abstract event QAVOnDeviceStateChangedEvent OnDeviceStateChangedEvent;
参数 类型 含义
deviceType int 1 代表采集设备,2 代表播放设备
deviceId string 设备 GUID,用于标记设备,仅在 Windows 端和 Mac 端有效
openOrClose bool 采集设备/播放设备占用或者释放
参数 数值 含义
AUDIODEVICE_CAPTURE 1 代表采集设备
AUDIODEVICE_PLAYER 2 代表播放设备

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetAudioCtrl().OnDeviceStateChangedEvent += new QAVAudioDeviceStateCallback(OnAudioDeviceStateChange);
监听处理:
void QAVAudioDeviceStateCallback(int deviceType, string deviceId, bool openOrClose){
    //设备占用和释放事件相关回调处理
}

离线语音语音转文字流程图

离线语音

未初始化前,SDK 处于未初始化阶段,需要通过接口 Init 初始化 SDK,才可以使用实时语音及离线语音。
使用问题可参考离线语音相关问题

初始化相关接口

接口 接口含义
Init 初始化 GME
Poll 触发事件回调
Pause 系统暂停
Resume 系统恢复
Uninit 反初始化 GME

离线语音相关接口

接口 接口含义
ApplyPTTAuthbuffer 鉴权初始化
SetMaxMessageLength 限制最大语音信息时长
StartRecording 启动录音
StartRecordingWithStreamingRecognition 启动流式录音
PauseRecording 暂停录音
ResumeRecording 恢复录音
StopRecording 停止录音
CancelRecording 取消录音
GetMicLevel 获取离线语音实时麦克风音量
SetMicVolume 设置离线语音录制音量
GetMicVolume 获取离线语音录制音量
GetSpeakerLevel 获取离线语音实时扬声器音量
SetSpeakerVolume 设置离线语音播放音量
GetSpeakerVolume 获取离线语音播放音量
UploadRecordedFile 上传语音文件
DownloadRecordedFile 下载语音文件
PlayRecordedFile 播放语音
StopPlayFile 停止播放语音
GetFileSize 语音文件的大小
GetVoiceFileDuration 语音文件的时长
SpeechToText 语音识别成文字

鉴权初始化

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

函数原型

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

示例代码

ITMGContext.GetInstance().GetPttCtrl().ApplyPTTAuthbuffer(authBuffer);

限制最大语音信息时长

限制最大语音消息的长度,最大支持60秒。

函数原型

ITMGPTT int SetMaxMessageLength(int msTime)
参数 类型 含义
msTime int 语音时长,单位 ms

示例代码

ITMGContext.GetInstance().GetPttCtrl().SetMaxMessageLength(60000); 

启动录音

此接口用于启动录音。需要将录音文件上传后才可以进行语音转文字等操作。

函数原型

ITMGPTT int StartRecording(string fileDir)
参数 类型 含义
fileDir string 存放的语音路径

示例代码

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

启动录音的回调

录音完成的回调,通过委托传递消息。

函数原型

委托函数:
public delegate void QAVRecordFileCompleteCallback(int code, string filepath); 
事件函数:
public abstract event QAVRecordFileCompleteCallback OnRecordFileComplete;
参数 类型 含义
code string 当 code 为 0 时,录制完成
filepath string 录制的存放地址

错误码

错误码值 原因 建议方案
4097 参数为空 检查代码中接口参数是否正确
4098 初始化错误 检查设备是否被占用,或者权限是否正常,是否初始化正常
4099 正在录制中 确保在正确的时机使用 SDK 录制功能
4100 没有采集到音频数据 检查麦克风设备是否正常
4101 录音时,录制文件访问错误 确保文件存在,文件路径的合法性
4102 麦克风未授权错误 使用 SDK 需要麦克风权限,添加权限请参考对应引擎或平台的 SDK 工程配置文档
4103 录音时间太短错误 首先,限制录音时长的单位为毫秒,检查参数是否正确;其次,录音时长要1000毫秒以上才能成功录制
4104 没有启动录音操作 检查是否已经调用启动录音接口

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetPttCtrl().OnRecordFileComplete +=  new QAVRecordFileCompleteCallback (OnRecordFileComplete);
监听处理:
void OnRecordFileComplete(int code, string filepath){
    //启动录音的回调
}

启动流式语音识别

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

函数原型

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

示例代码

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

启动流式语音识别的回调

启动流式语音识别完成后的回调通过委托传递消息。

委托函数:
public delegate void QAVStreamingRecognitionCallback(int code, string fileid, string filepath, string result);
事件函数:
public abstract event QAVStreamingRecognitionCallback OnStreamingSpeechComplete;
消息名称 含义
code 用于判断流式语音识别是否成功的返回码
result 语音转文字识别的文本
filepath 录音存放的本地地址
fileid 录音在后台的 url 地址
错误码 含义 处理方式
32775 流式语音转文本失败,但是录音成功 调用 UploadRecordedFile 接口上传录音,再调用 SpeechToText 接口进行语音转文字操作
32777 流式语音转文本失败,但是录音成功,上传成功 返回的信息中有上传成功的后台 url 地址,调用 SpeechToText 接口进行语音转文字操作

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetPttCtrl().OnStreamingSpeechComplete +=new QAVStreamingRecognitionCallback (OnStreamingSpeechComplete);
监听处理:
void OnStreamingSpeechComplete(int code, string fileid, string filepath, string result){
    //启动流式语音识别的回调
}

暂停录音

此接口用于暂停录音。如需恢复录音请调用接口 ResumeRecording。

函数原型

ITMGPTT int PauseRecording()

示例代码

ITMGContext.GetInstance().GetPttCtrl().PauseRecording();

恢复录音

此接口用于恢复录音。

函数原型

ITMGPTT int ResumeRecording()

示例代码

ITMGContext.GetInstance().GetPttCtrl().ResumeRecording();

停止录音

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

函数原型

ITMGPTT int StopRecording()

示例代码

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

取消录音

调用此接口取消录音。取消之后没有回调。

函数原型

ITMGPTT int CancelRecording()

示例代码

ITMGContext.GetInstance().GetPttCtrl().CancelRecording();

获取离线语音麦克风实时音量

此接口用于获取麦克风实时音量,返回值为 int 类型,值域为 0 到 100。

函数原型

ITMGPTT int GetMicLevel()

示例代码

ITMGContext.GetInstance().GetPttCtrl().GetMicLevel();

设置离线语音录制音量

此接口用于设置离线语音录制音量,值域为0到100。

函数原型

ITMGPTT int SetMicVolume(int vol)

示例代码

ITMGContext.GetInstance().GetPttCtrl().SetMicVolume(100);

获取离线语音录制音量

此接口用于获取离线语音录制音量。返回值为 int 类型,值域为0到100。

函数原型

ITMGPTT int GetMicVolume()

示例代码

ITMGContext.GetInstance().GetPttCtrl().GetMicVolume();

获取扬声器实时音量

此接口用于获取扬声器实时音量。返回值为 int 类型,值域为 0 到 100。

函数原型

ITMGPTT int GetSpeakerLevel()

示例代码

ITMGContext.GetInstance().GetPttCtrl().GetSpeakerLevel();

设置离线语音播放音量

此接口用于设置离线语音播放音量,值域为0到100。

函数原型

ITMGPTT int SetSpeakerVolume(int vol)

示例代码

ITMGContext.GetInstance().GetPttCtrl().SetSpeakerVolume(100);

获取离线语音播放音量

此接口用于获取离线语音播放音量。返回值为 int 类型,值域为0到100。

函数原型

ITMGPTT int GetSpeakerVolume()

示例代码

ITMGContext.GetInstance().GetPttCtrl().GetSpeakerVolume();

上传语音文件

此接口用于上传语音文件。

函数原型

ITMGPTT int UploadRecordedFile (string filePath)
参数 类型 含义
filePath string 上传的语音路径

示例代码

ITMGContext.GetInstance().GetPttCtrl().UploadRecordedFile(filePath);

上传语音完成的回调

上传语音完成的回调,通过委托传递消息。

函数原型

委托函数:
public delegate void QAVUploadFileCompleteCallback(int code, string filepath, string fileid);
事件函数:
public abstract event QAVUploadFileCompleteCallback OnUploadFileComplete; 
参数 类型 含义
code int 当 code 为0时,录制完成
filepath string 录制的存放地址
fileid string 文件的 url 路径

错误码

错误码值 原因 建议方案
8193 上传文件时,文件访问错误 确保文件存在,文件路径的合法性
8194 签名校验失败错误 检查鉴权密钥是否正确,检查是否有初始化离线语音
8195 网络错误 检查设备网络是否可以正常访问外网环境
8196 获取上传参数过程中网络失败 检查鉴权是否正确,检查设备网络是否可以正常访问外网环境
8197 获取上传参数过程中回包数据为空 检查鉴权是否正确,检查设备网络是否可以正常访问外网环境
8198 获取上传参数过程中回包解包失败 检查鉴权是否正确,检查设备网络是否可以正常访问外网环境
8200 没有设置 appinfo 检查 apply 接口是否有调用,或者入参是否为空

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetPttCtrl().OnUploadFileComplete +=new QAVUploadFileCompleteCallback (OnUploadFileComplete);
监听处理:
void OnUploadFileComplete(int code, string filepath, string fileid){
    //上传语音完成的回调
}

下载语音文件

此接口用于下载语音文件。

函数原型

ITMGPTT DownloadRecordedFile (string fileID, string downloadFilePath)
参数 类型 含义
fileID string 文件的 url 路径
downloadFilePath string 文件的本地保存路径

示例代码

ITMGContext.GetInstance().GetPttCtrl().DownloadRecordedFile(fileId, filePath);

下载语音文件完成回调

下载语音文件完成回调,通过委托传递消息。

函数原型

委托函数:
public delegate void QAVDownloadFileCompleteCallback(int code, string filepath, string fileid);
事件函数:
public abstract event QAVDownloadFileCompleteCallback OnDownloadFileComplete;
参数 类型 含义
code int 当 code 为0时,录制完成
filepath string 录制的存放地址
fileid string 文件的 url 路径

错误码

错误码值 原因 建议方案
12289 下载文件时,文件访问错误 检查文件路径是否合法
12290 签名校验失败 检查鉴权密钥是否正确,检查是否有初始化离线语音
12291 网络存储系统异常 服务器获取语音文件失败,检查接口参数 fileid 是否正确,检查网络是否正常,检查 cos 文件存不存在
12292 服务器文件系统错误 检查设备网络是否可以正常访问外网环境,检查服务器上是否有此文件
12293 获取下载参数过程中,HTTP 网络失败 检查设备网络是否可以正常访问外网环境
12294 获取下载参数过程中,回包数据为空 检查设备网络是否可以正常访问外网环境
12295 获取下载参数过程中,回包解包失败 检查设备网络是否可以正常访问外网环境
12297 没有设置 appinfo 检查鉴权密钥是否正确,检查是否有初始化离线语音

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetPttCtrl().OnDownloadFileComplete +=new QAVDownloadFileCompleteCallback(OnDownloadFileComplete);
监听处理:
void OnDownloadFileComplete(int code, string filepath, string fileid){
    //下载语音文件完成回调
}

播放语音

此接口用于播放语音。

函数原型

ITMGPTT PlayRecordedFile (string downloadFilePath)
参数 类型 含义
downloadFilePath string 文件的路径

示例代码

ITMGContext.GetInstance().GetPttCtrl().PlayRecordedFile(filePath); 

播放语音的回调

播放语音的回调,通过委托传递消息。

函数原型

委托函数:
public delegate void QAVPlayFileCompleteCallback(int code, string filepath);
事件函数:
public abstract event QAVPlayFileCompleteCallback OnPlayFileComplete;
参数 类型 含义
code int 当 code 为0时,录制完成
filepath string 录制的存放地址

错误码

错误码值 原因 建议方案
20481 初始化错误 检查设备是否被占用,或者权限是否正常,是否初始化正常
20482 正在播放中,试图打断并播放下一个失败了(正常是可以打断的) 检查代码逻辑是否正确
20483 参数为空 检查代码中接口参数是否正确
20484 内部错误 初始化播放器错误,解码失败等问题产生此错误码,需要结合日志定位问题

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetPttCtrl().OnPlayFileComplete +=new  QAVPlayFileCompleteCallback(OnPlayFileComplete);
监听处理:
void OnPlayFileComplete(int code, string filepath){
    //播放语音的回调
}

停止播放语音

此接口用于停止播放语音。停止播放语音也会有播放完成的回调。

函数原型

ITMGPTT int StopPlayFile()

示例代码

ITMGContext.GetInstance().GetPttCtrl().StopPlayFile();

获取语音文件的大小

通过此接口,获取语音文件的大小。

函数原型

ITMGPTT GetFileSize(string filePath) 
参数 类型 含义
filePath string 语音文件的路径

示例代码

int fileSize = ITMGContext.GetInstance().GetPttCtrl().GetFileSize(filepath);

获取语音文件的时长

此接口用于获取语音文件的时长,单位毫秒。

函数原型

ITMGPTT int GetVoiceFileDuration(string filePath)
参数 类型 含义
filePath string 语音文件的路径

示例代码

int fileDuration = ITMGContext.GetInstance().GetPttCtrl().GetVoiceFileDuration(filepath);

将指定的语音文件识别成文字

此接口用于将指定的语音文件识别成文字。

函数原型

ITMGPTT int SpeechToText(String fileID)
参数 类型 含义
fileID string 语音文件 url

示例代码

ITMGContext.GetInstance().GetPttCtrl().SpeechToText(fileID);

将指定的语音文件翻译成文字(指定语言)

此接口可以指定语言进行识别,也可以将语音中识别到的信息翻译成指定的语言返回。

函数原型

ITMGPTT int SpeechToText(String fileID,String language)
参数 类型 含义
fileID String 语音文件 url
speechLanguage String 识别出指定文字的语言参数,参数参考语音转文字的语言参数参考列表
translatelanguage String 翻译成指定文字的语言参数,参数参考语音转文字的语言参数参考列表(此参数暂时无效,填入参数应与 speechLanguage 一致)

示例代码

ITMGContext.GetInstance().GetPttCtrl().SpeechToText(fileID,"cmn-Hans-CN","cmn-Hans-CN");

识别回调

将指定的语音文件识别成文字,通过委托传递消息。

函数原型

委托函数:
public delegate void QAVSpeechToTextCallback(int code, string fileid, string result);
事件函数:
public abstract event QAVSpeechToTextCallback OnSpeechToTextComplete;
参数 类型 含义
code int 当 code 为0时,录制完成
fileid string 语音文件 url
result string 转换的文本结果

示例代码

对事件进行监听:
ITMGContext.GetInstance().GetPttCtrl().OnSpeechToTextComplete += new QAVSpeechToTextCallback(OnSpeechToTextComplete);
监听处理:
void OnSpeechToTextComplete(int code, string fileid, string result){
    //识别回调
}

高级 API

获取版本号

获取 SDK 版本号,用于分析。

函数原型

ITMGContext  abstract string GetSDKVersion()

示例代码

ITMGContext.GetInstance().GetSDKVersion();

设置打印日志等级

用于设置打印日志等级。建议保持默认等级。

函数原型

ITMGContext  SetLogLevel(ITMG_LOG_LEVEL levelWrite, ITMG_LOG_LEVEL levelPrint)

参数含义

参数 类型 含义
levelWrite ITMG_LOG_LEVEL 设置写入日志的等级,TMG_LOG_LEVEL_NONE 表示不写入,默认为 TMG_LOG_LEVEL_INFO
levelPrint ITMG_LOG_LEVEL 设置打印日志的等级,TMG_LOG_LEVEL_NONE 表示不打印,默认为 TMG_LOG_LEVEL_ERROR
ITMG_LOG_LEVEL 含义
TMG_LOG_LEVEL_NONE=0 不打印日志
TMG_LOG_LEVEL_ERROR=1 打印错误日志(默认)
TMG_LOG_LEVEL_INFO=2 打印提示日志
TMG_LOG_LEVEL_DEBUG=3 打印开发调试日志
TMG_LOG_LEVEL_VERBOSE=4 打印高频日志

示例代码

ITMGContext.GetInstance().SetLogLevel(TMG_LOG_LEVEL_INFO,TMG_LOG_LEVEL_INFO);

设置打印日志路径

用于设置打印日志路径。
默认路径为:

平台 路径
Windows %appdata%\Tencent\GME\ProcessName
iOS Application/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Documents
Android /sdcard/Android/data/xxx.xxx.xxx/files
Mac /Users/username/Library/Containers/xxx.xxx.xxx/Data/Documents

函数原型

ITMGContext  SetLogPath(string logDir)
参数 类型 含义
logDir NSString 路径

示例代码

ITMGContext.GetInstance().SetLogPath(path);

获取诊断信息

获取音视频通话的实时通话质量的相关信息。该接口主要用来查看实时通话质量、排查问题等,业务侧可以忽略。

函数原型

ITMGRoom GetQualityTips()

示例代码

string tips = ITMGContext.GetInstance().GetRoom().GetQualityTips();

加入音频数据黑名单

将某个 ID 加入音频数据黑名单。返回值为 0 表示调用成功。

函数原型

ITMGContext ITMGAudioCtrl AddAudioBlackList(String openId)
参数 类型 含义
openId NSString 需添加黑名单的 id

示例代码

ITMGContext.GetInstance().GetAudioCtrl ().AddAudioBlackList (id);

移除音频数据黑名单

将某个 ID 移除音频数据黑名单。返回值为 0 表示调用成功。

函数原型

ITMGContext ITMGAudioCtrl RemoveAudioBlackList(string openId)
参数 类型 含义
openId NSString 需移除黑名单的 id

示例代码

ITMGContext.GetInstance().GetAudioCtrl ().RemoveAudioBlackList (id);