tencent cloud

文档反馈

实时语音

最后更新时间:2024-01-18 15:11:45
    为方便 iOS 开发者调试和接入腾讯云游戏多媒体引擎客户端 API,本文为您介绍适用于 iOS 实时语音功能的开发接入技术文档。

    使用 GME 重要事项

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

    重点提示

    已完成 GME 应用创建,并获取 SDK AppID 和 Key。请参考 服务开通指引
    已开通 GME 实时语音服务、语音消息服务以及转文本服务。请参考 服务开通指引
    GME 使用前请对工程进行配置,否则 SDK 不生效。
    GME 的接口调用成功后返回值为 QAVError.OK,数值为 0。
    GME 的接口调用要在同一个线程下。
    GME 需要周期性的调用 Poll 接口触发事件回调。
    错误码详情可参考 错误码

    接入 SDK

    重要步骤

    接入 SDK 重要流程如下:
    
    
    
    1. 初始化 GME

    接口类

    @class ITMGRoom;//房间相关
    @class ITMGAudioCtrl;//音频相关
    @class ITMGAudioEffectCtrl;//音效、伴奏相关

    核心接口

    接口
    接口含义
    InitEngine
    初始化 GME
    Poll
    触发事件回调
    Pause
    系统暂停
    Resume
    系统恢复
    Uninit
    反初始化 GME
    SetDefaultAudienceAudioCategory
    iOS 设备音频设置
    注意:
    如果切换账号,请调用 UnInit 反初始化 SDK。InitEngine 接口调用不会产生计费。

    引用头文件

    #import "GMESDK/TMGEngine.h"
    #import "GMESDK/QAVAuthBuffer.h"

    获取单例

    在使用语音功能时,需要首先获取 ITMGContext 对象。
    + (ITMGContext*) GetInstance;

    示例代码

    //TMGSampleViewController.m
    ITMGContext* _context = [ITMGContext GetInstance];

    设置回调

    接口类采用 Delegate 方法用于向应用程序发送回调通知。将回调函数注册给 SDK,用于接收回调的信息。

    示例代码

    声明采用 ITMGDelegate。
    @interface TMGDemoViewController ()<ITMGDelegate>{}
    ITMGDelegate < NSObject >
    
    //TMGSampleViewController.m
    ITMGContext* _context = [ITMGContext GetInstance];
    _context.TMGDelegate = [DispatchCenter getInstance];
    在 OnEvent 中处理接口的回调信息,消息类型参考 ITMG_MAIN_EVENT_TYPE,消息内容为一个字典,解析出接口回调的内容。

    接口原型

    - (void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary*)data;

    示例代码

    //TMGRealTimeViewController.m
    TMGRealTimeViewController ()< ITMGDelegate >
    
    
    - (void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary *)data {
    NSString *log = [NSString stringWithFormat:@"OnEvent:%d,data:%@", (int)eventType, data];
    [self showLog:log];
    NSLog(@"====%@====", log);
    switch (eventType) {
    // Step 6/11 : Perform the enter room event
    case ITMG_MAIN_EVENT_TYPE_ENTER_ROOM: {
    int result = ((NSNumber *)[data objectForKey:@"result"]).intValue;
    NSString *error_info = [data objectForKey:@"error_info"];
    
    [self showLog:[NSString stringWithFormat:@"OnEnterRoomComplete:%d msg:(%@)", result, error_info]];
    
    if (result == 0) {
    [self updateStatusEnterRoom:YES];
    }
    }
    break;
    }
    }
    
    //需要参考 DispatchCenter.h、DispatchCenter.m

    初始化 SDK

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

    接口原型

    -(int)InitEngine:(NSString*)sdkAppID openID:(NSString*)openID;
    参数
    类型
    含义
    sdkAppId
    String
    来自 腾讯云控制台 的 GME 服务提供的 AppID,获取请参考 语音服务开通指引
    OpenId
    String
    openID 只支持 Int64 类型(转为 const char* 传入)。 规则由 App 开发者自行制定,App 内不重复即可。如需使用字符串作为 Openid 传入,可通过工单联系开发者

    返回值

    返回值
    处理
    QAV_OK= 0
    初始化 SDK 成功
    QAV_ERR_SDK_NOT_FULL_UPDATE= 7015
    检查 SDK 文件是否完整,建议删除后重新导入 SDK
    关于7015错误提示:
    7015错误码是通过 md5 进行判断,在接入过程中若出现此错误,请根据提示检查 SDK 文件是否完整、SDK 文件版本是否一致。
    出现返回值 AV_ERR_SDK_NOT_FULL_UPDATE 时,此返回值只有提示作用,并不会造成初始化失败。
    由于第三方加固、Unity 打包机制等因素会影响库文件 md5,造成误判,所以正式发布请在逻辑中忽略此错误,并尽量不在 UI 中提示。

    示例代码

    _openId = _userIdText.text;
    _appId = _appIdText.text;
    int result = 0;
    //在用户同意APP隐私政策之后,按APP功能需要在合适时机再正式初始化SDK
    //result = 0,表示用户同意APP隐私合规政策
    //result = 1,表示用户不同意APP隐私合规政策
    //如果用户不授权隐私策略,则 ret 修改为非 0
    if (result == 0) {
    [[ITMGContext GetInstance] InitEngine:SDKAPPID openID:_openId];}
    else{
    log = [NSString stringWithFormat:@"用户不同意APP隐私合规政策"];
    }

    触发事件回调

    通过在 update 里面周期的调用 Poll 可以触发事件回调。Poll 是 GME 的消息泵,GME 需要周期性的调用 Poll 接口触发事件回调。如果没有调用 Poll ,将会导致整个 SDK 服务运行异常。可参考 Demo 中的 EnginePollHelper.m 文件。
    务必周期性调用 Poll 接口:
    务必周期性调用 Poll 接口且在主线程调用,以免接口回调异常。

    接口原型

    -(void)Poll;

    示例代码

    [[ITMGContext GetInstance] Poll];

    系统暂停

    当系统发生 Pause 事件时,需要同时通知引擎进行 Pause。如果不需要后台播放房间内声音,请调用 Pause 接口暂停整个 GME 服务。

    接口原型

    -(QAVResult)Pause;

    系统恢复

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

    接口原型

    -(QAVResult)Resume;

    反初始化 SDK

    反初始化 SDK,进入未初始化状态。如果游戏业务侧账号与 openid 是绑定的,那切换游戏账号需要反初始化 GME,再用新的 openid 初始化
    注意:
    终端用户撤销同意处理其个人信息的授权时,您可通过调用 Uninit 接口停止使用SDK功能并停止采集与关闭功能相应的用户数据。

    接口原型

    -(int)Uninit;

    示例代码

    [[ITMGContext GetInstance] Uninit];

    iOS 设备音频设置

    此接口用于设置后台播放声音,以及 GME 音频不受物理静音按键、锁屏的影响。例如拉起通知中心或者控制中心时候依然可以接收播放 GME 音频。此接口需要在进房前调用。
    同时,应用侧有如下两点需要注意:
    退后台时没有暂停音频引擎的采集和播放(即 PauseAudio)。
    App 的 Info.plist 中,需要至少增加 key:Required background modes,string:App plays audio or streams audio/video using AirPlay。
    
    
    
    注意:
    建议开发者调用此接口设置音频。

    函数原型

    -(QAVResult)SetDefaultAudienceAudioCategory:(ITMG_AUDIO_CATEGORY)audioCategory;
    类型
    参数代表
    含义
    ITMG_CATEGORY_AMBIENT
    0
    退后台没有声音(默认)
    ITMG_CATEGORY_PLAYBACK
    1
    退后台有声音
    具体实现为修改 kAudioSessionProperty_AudioCategory,相关资料请参见 Apple 官方文档。

    示例代码

    [[ITMGContext GetInstance]SetDefaultAudienceAudioCategory:ITMG_CATEGORY_AMBIENT];

    实时语音房间相关接口

    初始化之后,SDK 调用进房后进去了房间,才可以进行实时语音通话。使用问题可参考 实时语音相关问题
    
    
    
    接口
    接口含义
    GenAuthBuffer
    本地鉴权计算
    EnterRoom
    加入房间
    ExitRoom
    退出房间
    IsRoomEntered
    判断是否已经进入房间
    SwitchRoom
    快速切换房间
    StartRoomSharing
    跨房连麦

    本地鉴权计算

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

    接口原型

    @interface QAVAuthBuffer : NSObject
    + (NSData*) GenAuthBuffer:(unsigned int)appId roomId:(NSString*)roomId openID:(NSString*)openID key:(NSString*)key;
    + @end
    参数
    类型
    含义
    appId
    unsigned int
    来自腾讯云控制台的 AppId 号码。
    roomId
    NSString *
    房间号,最大支持127字符。
    openID
    NSString *
    用户标识。与 Init 时候的 openID相同。
    key
    NSString *
    来自腾讯云 控制台 的权限密钥。

    示例代码

    #import "GMESDK/QAVAuthBuffer.h"
    NSData* authBuffer = [QAVAuthBuffer GenAuthBuffer:SDKAPPID3RD.intValue roomId:_roomId openID:_openId key:AUTHKEY];

    加入房间

    用生成的鉴权信息进房,加入房间默认不打开麦克风及扬声器。
    注意:
    加入房间事件回调结果 result 为 0 代表进房成功,进房接口 EnterRoom 返回值为 0 不代表进房成功。
    房间的音频类型由第一个进房的人确定,此后房间里有成员修改房间类型,将对此房间所有成员生效。例如第一个进入房间的人使用的房间音频类型是流畅音质,第二个进房的是即使进房时候调用接口的音频类型参数是高清音质,进入房间之后也会变成流畅音质。需要有成员调用 ChangeRoomType 才会修改房间的音频类型。

    函数原型

    -(int)EnterRoom:(NSString*) roomId roomType:(int)roomType authBuffer:(NSData*)authBuffer;
    参数
    类型
    含义
    roomId
    NSString *
    房间号,最大支持127字符
    roomType
    int
    房间类型,建议填 ITMG_ROOM_TYPE_FLUENCY。房间音频类型请参考 音质选择
    authBuffer
    NSData *
    鉴权码

    示例代码

    [[ITMGContext GetInstance] EnterRoom:_roomId roomType:_roomType authBuffer:authBuffer];

    加入房间的事件回调

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

    示例代码

    回调处理相关参考代码,包括加入房间事件以及断网事件。
    -(void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary *)data{
    NSLog(@"OnEvent:%lu,data:%@",(unsigned long)eventType,data);
    switch (eventType) {
    case ITMG_MAIN_EVENT_TYPE_ENTER_ROOM:
    {
    int result = ((NSNumber*)[data objectForKey:@"result"]).intValue;
    NSString* error_info = [data objectForKey:@"error_info"];
    //收到进房成功事件
    }
    break;
    }
    }

    Data 详情

    消息
    Data
    例子
    ITMG_MAIN_EVENT_TYPE_ENTER_ROOM
    result; error_info
    {"error_info":"","result":0}
    ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT
    result; error_info
    {"error_info":"waiting timeout, please check your network","result":0}
    如果断网,将会有断网的回调提示 ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT,此时 SDK 会自动进行重连,回调是 ITMG_MAIN_EVENT_TYPE_RECONNECT_START,当重连成功时,会有 ITMG_MAIN_EVENT_TYPE_RECONNECT_SUCCESS 回调。

    错误码

    错误码值
    原因及建议方案
    7006
    鉴权失败原因。
    AppID 不存在或者错误
    authbuff 鉴权错误
    鉴权过期
    OpenId 不符合规范
    7007
    已经在其它房间
    1001
    已经在进房过程中,然后又重复了此操作。建议在进房回调返回之前不要再调用进房接口
    1003
    已经进房了在房间中,又调用一次进房接口
    1101
    确保已经初始化 SDK,确保 OpenId 是否符合规则,或者确保在同一线程调用接口,以及确保 Poll 接口正常调用

    退出房间

    通过调用此接口可以退出所在房间。这是一个异步接口,返回值为 AV_OK 的时候代表异步投递成功。如果应用中有退房后立即进房的场景,在接口调用流程上,开发者无需要等待 ExitRoom 的回调 RoomExitComplete 通知,只需直接调用接口。

    接口原型

    -(int)ExitRoom

    示例代码

    [[ITMGContext GetInstance] ExitRoom];

    退出房间事件回调

    退出房间完成后会有回调,消息为 ITMG_MAIN_EVENT_TYPE_EXIT_ROOM。

    示例代码

    -(void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary *)data{
    NSLog(@"OnEvent:%lu,data:%@",(unsigned long)eventType,data);
    switch (eventType) {
    case ITMG_MAIN_EVENT_TYPE_EXIT_ROOM:
    {
    //收到退房成功事件
    }
    break;
    }
    }

    Data详情

    消息
    Data
    例子
    ITMG_MAIN_EVENT_TYPE_EXIT_ROOM
    result; error_info
    {"error_info":"","result":0}

    判断是否已经进入房间

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

    接口原型

    -(BOOL)IsRoomEntered;

    示例代码

    [[ITMGContext GetInstance] IsRoomEntered];

    快速切换房间

    调用此接口快速切换实时语音房间。此接口在进房后调用。切换房间后,不重置设备,即如果在此房间已经是打开麦克风状态,在切换房间后也会是打开麦克风状态。
    快速切换房间的回调是 ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_SWITCH_ROOM,字段是 error_info 以及 result。

    接口原型

    -(int) SwitchRoom:(NSString *)roomID authBuffer:(NSData*)authBuffer;

    类型说明

    参数
    类型
    含义
    targetRoomID
    NSString *
    将要进入的房间号
    authBuffer
    NSData*
    用将要进入的房间号生成的新鉴权

    回调示例代码

    - (IBAction)swichRoom:(id)sender {
    NSData* authBuffer = [QAVAuthBuffer GenAuthBuffer:_appId.intValue roomID:_roomIdText.text openID:_openId key:_key];
    [[[ITMGContext GetInstance]GetRoom]SwitchRoom:_roomIdText.text authBuffer:authBuffer];
    }
    
    -(void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary *)data{
    NSString* log =[NSString stringWithFormat:@"OnEvent:%d,data:%@", (int)eventType, data];
    [self showLog:log];
    NSLog(@"====%@====",log);
    switch (eventType) {
    case ITMG_MAIN_EVENT_TYPE_SWITCH_ROOM:
    {
    int result = ((NSNumber*)[data objectForKey:@"result"]).intValue;
    NSString* log = nil;
    if (result == QAV_OK) {
    log = [NSString stringWithFormat:@"switch room success."];
    } else {
    log = [NSString stringWithFormat:@"switch room failed."];
    }
    [self showLog:log];
    break;
    }
    }
    }

    跨房连麦

    调用此接口进行跨房连麦,此接口在进房后调用。调用接口后,本端可以与目标房间的目标 OpenID 用户进行连麦交流。目标房间与本端房间类型相同才能成功。

    场景示例

    a 用户在 A 房间中,b 用户在 B 房间中,a 用户可以通过跨房接口与 b 进行通话,A 房间中的用户 c 说话,B 房间的 b 与 d 无法听到;A 房间中的用户 c 只能听到 A 房间的声音以及 B 房间中 b 的声音,B 房间其他人说话 c 无法听到。

    接口原型

    -(int) StartRoomSharing:(NSString *)targetRoomID targetOpenID:(NSString *)targetOpenID authBuffer:(NSData*)authBuffer;
    
    -(int) StopRoomSharing;

    类型说明

    参数
    类型
    含义
    targetRoomID
    NSString *
    将要连麦的房间号
    targetOpenID
    NSString *
    将要连麦的目标 OpenID
    authBuffer
    NSData*
    保留标志位,只需填 NULL

    示例代码

    - (IBAction)shareRoom:(id)sender {
    if(_shareRoomSwitch.isOn){
    [[[ITMGContext GetInstance]GetRoom]StartRoomSharing:_shareRoomID.text targetOpenID:_shareOpenID.text authBuffer:NULL];
    }else{
    [[[ITMGContext GetInstance]GetRoom]StopRoomSharing];
    }
    }

    房间内状态维护

    此部分接口用于业务层显示说话成员、进退房成员,以及将房间内某成员禁言等功能。
    
    
    
    接口/通知
    含义
    ITMG_MAIN_EVNET_TYPE_USER_UPDATE
    成员状态变化通知
    AddAudioBlackList
    房间中禁言某成员
    RemoveAudioBlackList
    移除禁言

    成员进房、说话状态通知

    此接口适用于获取房间中说话的人并在 UI 中展示,以及有人进入、退出语音房间的一个通知。
    该事件在状态变化才通知,状态不变化的情况下不通知。如需实时获取成员状态,请在上层收到通知时缓存,事件消息为 ITMG_MAIN_EVNET_TYPE_USER_UPDATE,其中 data 包含两个信息,event_id 及 user_list,在 OnEvent 函数中对事件消息进行判断。
    音频事件的通知有一个阈值,超过这个阈值才会发送通知。超过两秒没有收到音频包才通知“有成员停止发送音频包”消息。
    event_id
    含义
    应用侧维护内容
    ITMG_EVENT_ID_USER_ENTER
    有成员进入房间,返回此时进房的 openid
    应用侧维护成员列表
    ITMG_EVENT_ID_USER_EXIT
    有成员退出房间,返回此时退房的 openid
    应用侧维护成员列表
    ITMG_EVENT_ID_USER_HAS_AUDIO
    有成员发送音频包,返回此时房间内说话的 openid,通过此事件可以判断用户是否说话,并展示声纹效果
    应用侧维护通话成员列表
    ITMG_EVENT_ID_USER_NO_AUDIO
    有成员停止发送音频包,返回此时房间内停止说话的 openid
    应用侧维护通话成员列表

    示例代码

    -(void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary *)data{
    ITMG_EVENT_ID_USER_UPDATE event_id=((NSNumber*)[data objectForKey:@"event_id"]).intValue;
    NSMutableArray* uses = [NSMutableArray arrayWithArray: [data objectForKey:@"user_list"]];
    NSLog(@"OnEvent:%lu,data:%@",(unsigned long)eventType,data);
    switch (eventType) {
    case ITMG_MAIN_EVNET_TYPE_USER_UPDATE:
    {
    //进行处理
    //开发者对参数进行解析,得到信息 event_id及 user_list
    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;
    }
    break;
    }
    }
    }

    Data 详情

    消息
    Data
    例子
    ITMG_MAIN_EVNET_TYPE_USER_UPDATE
    event_id; user_list
    {"event_id":0,"user_list":""}

    房间中禁言某成员

    将某个 ID 加入音频数据黑名单,即不接受某人的语音, 只对本端生效,不会影响其他端。返回值为 0 表示调用成功。例如 :A、B、C 都在同一个房间开麦说话:
    如果 A 设置了 C 的黑名单, 则 A 只能听见 B 的声音。
    B 因为没有设置黑名单, 仍旧可以听见 A 和 C 的声音。
    C 同样因为没有设置黑名单, 可以听见 A 和 B 的声音。
    此接口适用于在语音房间中将某用户禁言的场景。

    接口原型

    ITMGContext GetAudioCtrl -(QAVResult)AddAudioBlackList:(NSString*)openID;
    参数
    类型
    含义
    openId
    NSString
    需添加黑名单的用户 openid

    示例代码

    [[[ITMGContext GetInstance]GetAudioCtrl ] AddAudioBlackList[id]];

    移除禁言

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

    接口原型

    -(QAVResult)RemoveAudioBlackList:(NSString*)openID;
    参数
    类型
    含义
    openId
    NSString
    需移除黑名单的用户 openid

    示例代码

    [[[ITMGContext GetInstance]GetAudioCtrl ] RemoveAudioBlackList[openId]];

    实时语音采集相关接口

    初始化 SDK 之后进房,在房间中,才可以调用实时音频语音相关接口。
    当用户界面单击打开/关闭麦克风/扬声器按钮时,建议采用 EnableMic 以及 EnableSpeaker 接口进行调用。
    当用户进入实时语音房间,打开或者关闭采集设备,会伴随整个设备(采集及播放)重启,如果此时 App 正在播放背景音乐,那么背景音乐的播放也会被中断。利用控制上下行的方式来实现开关麦克风效果,不会中断播放设备。具体调用方式为:在进房的时候调用 EnableAudioCaptureDevice(true) && EnableAudioPlayDevice(true) 一次,单击开关麦克风时只调用 EnableAudioSend/Recv 来控制音频流是否发送/接收
    接口
    接口含义
    EnableMic
    开关麦克风
    GetMicState
    获取麦克风状态
    EnableAudioCaptureDevice
    开关采集设备
    IsAudioCaptureDeviceEnabled
    获取采集设备状态
    EnableAudioSend
    打开关闭音频上行
    IsAudioSendEnabled
    获取音频上行状态
    GetMicLevel
    获取实时麦克风音量
    GetSendStreamLevel
    获取音频上行实时音量
    SetMicVolume
    设置麦克风音量
    GetMicVolume
    获取麦克风音量

    开启或关闭麦克风

    此接口用来开启关闭麦克风。加入房间默认不打开麦克风及扬声器。EnableMic = EnableAudioCaptureDevice + EnableAudioSend如果有使用伴奏的情况,请参考 实时语音伴奏流程图 进行调用。

    接口原型

    -(QAVResult)EnableMic:(BOOL)enable;
    参数
    类型
    含义
    enable
    boolean
    如果需要打开麦克风,则传入的参数为 YES
    如果关闭麦克风,则传入的参数为 NO

    示例代码

    //打开麦克风
    [[[ITMGContext GetInstance] GetAudioCtrl] EnableMic:YES];

    麦克风状态获取

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

    接口原型

    -(int)GetMicState;

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetMicState];

    开启或关闭采集设备

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

    接口原型

    -(QAVResult)EnableAudioCaptureDevice:(BOOL)enabled;
    参数
    类型
    含义
    enabled
    BOOL
    如果需要打开采集设备,则传入的参数为 YES
    如果关闭采集设备,则参数为 NO

    示例代码

    //打开采集设备
    [[[ITMGContext GetInstance]GetAudioCtrl ]EnableAudioCaptureDevice:enabled];

    采集设备状态获取

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

    接口原型

    -(BOOL)IsAudioCaptureDeviceEnabled;

    示例代码

    BOOL IsAudioCaptureDevice = [[[ITMGContext GetInstance] GetAudioCtrl] IsAudioCaptureDeviceEnabled];

    打开或关闭音频上行

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

    接口原型

    -(QAVResult)EnableAudioSend:(BOOL)enable;
    参数
    类型
    含义
    enable
    BOOL
    如果需要打开音频上行,则传入的参数为 YES
    如果关闭音频上行,则传入的参数为 NO

    示例代码

    [[[ITMGContext GetInstance]GetAudioCtrl ]EnableAudioSend:enabled];

    音频上行状态获取

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

    接口原型

    -(BOOL)IsAudioSendEnabled;

    示例代码

    BOOL IsAudioSend = [[[ITMGContext GetInstance] GetAudioCtrl] IsAudioSendEnabled];

    获取麦克风实时音量

    此接口用于获取麦克风实时音量,返回值为 int 类型。建议20ms获取一次。值域为0 - 100,通过此接口可以获取到麦克风采集到的实时音量情况。

    接口原型

    -(int)GetMicLevel;

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetMicLevel];

    获取音频上行实时音量

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

    接口原型

    -(int)GetSendStreamLevel();

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetSendStreamLevel];

    设置麦克风软件音量

    此接口用于设置麦克风的音量。参数 volume 用于设置麦克风的音量,相当于对采集的声音做衰减或增益。

    接口原型

    -(QAVResult)SetMicVolume:(int) volume;
    参数
    类型
    含义
    volume
    int
    取值范围为 0-200,数值为0的时候表示静音,当数值为100的时候表示音量不增不减,默认数值为100

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] SetMicVolume:100];

    获取麦克风软件音量

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

    接口原型

    -(int) GetMicVolume;

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetMicVolume];

    实时语音播放相关接口

    接口
    接口含义
    EnableSpeaker
    开关扬声器
    GetSpeakerState
    获取扬声器状态
    EnableAudioPlayDevice
    开关播放设备
    IsAudioPlayDeviceEnabled
    获取播放设备状态
    EnableAudioRecv
    打开关闭音频下行
    IsAudioRecvEnabled
    获取音频下行状态
    GetSpeakerLevel
    获取实时扬声器音量
    GetRecvStreamLevel
    获取房间内其他成员下行实时音量
    SetSpeakerVolume
    设置扬声器音量
    GetSpeakerVolume
    获取扬声器音量

    开启或关闭扬声器

    此接口用于开启关闭扬声器。EnableSpeaker = EnableAudioPlayDevice + EnableAudioRecv如果有使用伴奏的情况,请参考 实时语音伴奏流程图 进行调用。

    接口原型

    -(void)EnableSpeaker:(BOOL)enable;
    参数
    类型
    含义
    enable
    boolean
    如果需要关闭扬声器,则传入的参数为 NO
    如果打开扬声器,则传入的参数为 YES

    示例代码

    //打开扬声器
    [[[ITMGContext GetInstance] GetAudioCtrl] EnableSpeaker:YES];

    扬声器状态获取

    此接口用于扬声器状态获取。返回值0为关闭扬声器状态,返回值1为打开扬声器状态。

    函数原型

    -(int)GetSpeakerState;

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetSpeakerState];

    开启或关闭播放设备

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

    接口原型

    -(QAVResult)EnableAudioPlayDevice:(BOOL)enabled;
    参数
    类型
    含义
    enabled
    BOOL
    如果需要关闭播放设备,则传入的参数为 NO
    如果打开播放设备,则传入的参数为 YES

    示例代码

    //打开播放设备
    [[[ITMGContext GetInstance]GetAudioCtrl ]EnableAudioPlayDevice:enabled];

    播放设备状态获取

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

    接口原型

    -(BOOL)IsAudioPlayDeviceEnabled;

    示例代码

    BOOL IsAudioPlayDevice = [[[ITMGContext GetInstance] GetAudioCtrl] IsAudioPlayDeviceEnabled];

    打开或关闭音频下行

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

    接口原型

    -(QAVResult)EnableAudioRecv:(BOOL)enabled;
    参数
    类型
    含义
    enabled
    BOOL
    如果需要打开音频下行,则传入的参数为 YES
    如果关闭音频下行,则传入的参数为 NO

    示例代码

    [[[ITMGContext GetInstance]GetAudioCtrl ]EnableAudioRecv:enabled];

    音频下行状态获取

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

    接口原型

    -(BOOL)IsAudioRecvEnabled;

    示例代码

    BOOL IsAudioRecv = [[[ITMGContext GetInstance] GetAudioCtrl] IsAudioRecvEnabled];

    获取扬声器实时音量

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

    接口原型

    -(int)GetSpeakerLevel;

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetSpeakerLevel];

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

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

    接口原型

    -(int)GetRecvStreamLevel:(NSString*) openID;
    参数
    类型
    含义
    openID
    NSString
    房间其他成员的 openId

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetRecvStreamLevel:(NSString*) openId];

    动态设置房间内某成员音量

    此接口用于设置房间内某成员的说话音量大小,此设置只在本端生效。

    接口原型

    -(int) SetSpeakerVolumeByOpenID:(NSString *)openId volume:(int)volume;
    参数
    类型
    含义
    openId
    String *
    需要调节音量大小的OpenID
    volume
    int
    百分比,建议[0-200],其中100为默认值

    获取设置的声音百分比

    调用此接口获取 SetSpeakerVolumeByOpenID 设置的能量值。

    接口原型

    -(int) GetSpeakerVolumeByOpenID:(NSString *)openId;

    返回值

    接口返回 OpenID 设置的能量百分比, 默认返回100。

    设置扬声器的音量

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

    函数原型

    -(QAVResult)SetSpeakerVolume:(int)vol;
    参数
    类型
    含义
    vol
    int
    设置音量,范围0 - 200

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] SetSpeakerVolume:100];

    获取扬声器的音量

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

    函数原型

    -(int)GetSpeakerVolume;

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetSpeakerVolume];

    高级 API

    启动耳返

    此接口用于启动耳返,需要 EnableLoopBack + EnableSpeaker 才可以听到自己声音。

    函数原型

    -(QAVResult)EnableLoopBack:(BOOL)enable;
    参数
    类型
    含义
    enable
    boolean
    设置是否启动

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] EnableLoopBack:YES];

    修改用户房间音频类型

    此接口用于修改用户房间音频类型,结果参见回调事件,事件类型为 ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE。房间的音频类型由第一个进房的人确定,此后房间里有成员修改房间类型,将对此房间所有成员生效。

    函数原型

    -(int)ChangeRoomType:(int)nRoomType;
    参数
    类型
    含义
    nRoomType
    int
    房间切换成的目标类型,房间音频类型请参见 EnterRoom 接口

    示例代码

    [[[ITMGContext GetInstance]GetRoom ]ChangeRoomType:_roomType];

    获取用户房间音频类型

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

    函数原型

    -(int)GetRoomType;

    示例代码

    [[[ITMGContext GetInstance]GetRoom ]GetRoomType];

    房间类型修改回调

    房间类型设置完成后,回调的事件消息为 ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE,返回的参数为 result、error_info 及 new_room_type,new_room_type 代表的信息如下,在 OnEvent 函数中对事件消息进行判断。
    事件子类型
    代表参数
    含义
    ITMG_ROOM_CHANGE_EVENT_ENTERROOM
    1
    表示在进房的过程中,自带的音频类型与房间不符合,被修改为所进入房间的音频类型
    ITMG_ROOM_CHANGE_EVENT_START
    2
    表示已经在房间内,音频类型开始切换(例如调用 ChangeRoomType 接口后切换音频类型 )
    ITMG_ROOM_CHANGE_EVENT_COMPLETE
    3
    表示已经在房间,音频类型切换完成
    ITMG_ROOM_CHANGE_EVENT_REQUEST
    4
    表示房间成员调用 ChangeRoomType 接口,请求切换房间音频类型

    示例代码

    -(void)OnEvent:(ITMG_MAIN_EVENT_TYPE)eventType data:(NSDictionary *)data {
    NSLog(@"OnEvent:%lu,data:%@",(unsigned long)eventType,data);
    switch (eventType) {
    case ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE:
    NSLog(@"ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE:%@ ",data);
    int result = ((NSNumber*)[data objectForKey:@"result"]).intValue;
    int newRoomType = ((NSNumber*) [data objectForKey:@"new_room_type"]).intValue;
    int subEventType = ((NSNumber*) [data objectForKey:@"sub_event_type"]).intValue;
    }
    }

    Data 详情

    消息
    Data
    例子
    ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE
    result;error_info;new_room_type;subEventType
    {"error_info":"","new_room_type":0,"subEventType":0,"result":0}

    房间通话质量监控事件

    质量监控事件,在进房后触发,2秒回调一次,事件消息为 ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_QUALITY,返回的参数为 weight、loss 及 delay,代表的信息如下。
    此接口适用于监听网络质量,如果用户网络差的话,业务层将通过 UI 提醒用户切换网络。
    参数
    类型
    含义
    weight
    int
    范围是1 - 50,数值为50是音质评分极好,数值为1是音质评分很差,几乎不能使用,数值为0代表初始值,无含义。一般数值在 30 以下就可以提醒用户网络较差,建议切换网络
    loss
    double
    上行丢包率
    delay
    int
    音频触达延迟时间(ms)

    获取版本号

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

    函数原型

    -(NSString*)GetSDKVersion;

    示例代码

    [[ITMGContext GetInstance] GetSDKVersion];

    检查麦克风权限

    返回麦克风权限状态。

    函数原型

    -(ITMG_RECORD_PERMISSION)CheckMicPermission;

    参数含义

    参数
    数值
    含义
    ITMG_PERMISSION_GRANTED
    0
    麦克风已授权
    ITMG_PERMISSION_Denied
    1
    麦克风被禁用
    ITMG_PERMISSION_NotDetermined
    2
    尚未弹出权限框向用户申请权限
    ITMG_PERMISSION_ERROR
    3
    接口调用错误

    示例代码

    [[ITMGContext GetInstance] CheckMicPermission];

    设置打印日志等级

    用于设置打印日志等级。建议保持默认等级。需要在 Init 之前调用。

    函数原型

    -(void)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
    不打印日志
    TMG_LOG_LEVEL_ERROR
    打印错误日志(默认)
    TMG_LOG_LEVEL_INFO
    打印提示日志
    TMG_LOG_LEVEL_DEBUG
    打印开发调试日志
    TMG_LOG_LEVEL_VERBOSE
    打印高频日志

    示例代码

    [[ITMGContext GetInstance] SetLogLevel:TMG_LOG_LEVEL_INFO TMG_LOG_LEVEL_INFO];

    设置打印日志路径

    用于设置打印日志路径。默认路径为: Application/********-****-****-****-************/Documents。需要在 Init 之前调用。

    函数原型

    -(void)SetLogPath:(NSString*)logDir;
    参数
    类型
    含义
    logDir
    NSString
    路径

    示例代码

    [[ITMGContext GetInstance] SetLogPath:Path];

    获取诊断信息

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

    函数原型

    -(NSString*)GetQualityTips;

    示例代码

    [[[ITMGContext GetInstance]GetRoom ] GetQualityTips];

    回调消息

    消息列表

    消息
    消息代表的含义
    ITMG_MAIN_EVENT_TYPE_ENTER_ROOM
    进入音频房间消息
    ITMG_MAIN_EVENT_TYPE_EXIT_ROOM
    退出音频房间消息
    ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT
    房间因为网络等原因断开消息
    ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE
    房间类型变化事件
    ITMG_MAIN_EVNET_TYPE_USER_UPDATE
    房间成员更新消息
    ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_QUALITY
    房间质量信息

    Data 列表

    消息
    Data
    例子
    ITMG_MAIN_EVENT_TYPE_ENTER_ROOM
    result; error_info
    {"error_info":"","result":0}
    ITMG_MAIN_EVENT_TYPE_EXIT_ROOM
    result; error_info
    {"error_info":"","result":0}
    ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT
    result; error_info
    {"error_info":"waiting timeout, please check your network","result":0}
    ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_TYPE
    result; error_info; sub_event_type; new_room_type
    {"error_info":"","new_room_type":0,"result":0}
    ITMG_MAIN_EVENT_TYPE_SPEAKER_NEW_DEVICE
    result; error_info
    {"deviceID":"{0.0.0.00000000}.{a4f1e8be-49fa-43e2-b8cf-dd00542b47ae}","deviceName":"扬声器 (Realtek High Definition Audio)","error_info":"","isNewDevice":true,"isUsedDevice":false,"result":0}
    ITMG_MAIN_EVENT_TYPE_SPEAKER_LOST_DEVICE
    result; error_info
    {"deviceID":"{0.0.0.00000000}.{a4f1e8be-49fa-43e2-b8cf-dd00542b47ae}","deviceName":"扬声器 (Realtek High Definition Audio)","error_info":"","isNewDevice":false,"isUsedDevice":false,"result":0}
    ITMG_MAIN_EVENT_TYPE_MIC_NEW_DEVICE
    result; error_info
    {"deviceID":"{0.0.1.00000000}.{5fdf1a5b-f42d-4ab2-890a-7e454093f229}","deviceName":"麦克风 (Realtek High Definition Audio)","error_info":"","isNewDevice":true,"isUsedDevice":true,"result":0}
    ITMG_MAIN_EVENT_TYPE_MIC_LOST_DEVICE
    result; error_info
    {"deviceID":"{0.0.1.00000000}.{5fdf1a5b-f42d-4ab2-890a-7e454093f229}","deviceName":"麦克风 (Realtek High Definition Audio)","error_info":"","isNewDevice":false,"isUsedDevice":true,"result":0}
    ITMG_MAIN_EVNET_TYPE_USER_UPDATE
    user_list; event_id
    {"event_id":1,"user_list":["0"]}
    ITMG_MAIN_EVENT_TYPE_NUMBER_OF_USERS_UPDATE
    AllUser; AccUser; ProxyUser
    {"AllUser":3,"AccUser":2,"ProxyUser":1}
    ITMG_MAIN_EVENT_TYPE_NUMBER_OF_AUDIOSTREAMS_UPDATE
    AudioStreams
    {"AudioStreams":3}
    ITMG_MAIN_EVENT_TYPE_CHANGE_ROOM_QUALITY
    weight; loss; delay
    {"weight":5,"loss":0.1,"delay":1}
    
    联系我们

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

    技术支持

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

    7x24 电话支持