实时语音接口

最近更新时间:2022-01-14 18:00:49

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

说明

此文档对应 GME sdk version:2.9。

使用 GME 重要事项

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

关于 Init 接口

例如使用了实时语音服务,同时也需要使用语音消息服务,只需要调用一次 Init 初始化接口
Init 之后不会开始计费,调用 进入实时语音房间接口:EnterRoom 接口成功进入实时语音房间后才会开始计费。

image

重要步骤

重点提示

  • GME 使用前请对工程进行配置,否则 SDK 不生效。
  • GME 的接口调用成功后返回值为 QAVError.OK,数值为 0。
  • GME 的接口调用要在同一个线程下。
  • GME 需要周期性的调用 Poll 接口触发事件回调。
  • 错误码详情请参见 错误码ErrorCode

接口类

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

核心接口

未初始化前,SDK 处于未初始化阶段,需要通过接口 Init 初始化 SDK,才可以使用实时语音服务、语音消息及转文字服务。

在使用 GME 的任何接口之前,都需要先调用 Init 接口。

使用问题请参见 一般性问题

接口 接口含义
InitEngine 初始化 GME
Poll 触发事件回调
Pause 系统暂停
Resume 系统恢复
Uninit 反初始化 GME
SetDefaultAudienceAudioCategory 设置设备后台播放声音

引用头文件

#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

  • 此接口用于初始化 GME 服务,建议应用侧在应用初始化时候调用,调用此接口不会产生计费。
  • 参数 sdkAppID 获取请参考 语音服务开通指引
  • openID 用于唯一标识一个用户,目前只支持 INT64,规则由 App 开发者自行制定,App 内不重复即可
注意
  • 初始化 SDK 后才可以进入实时语音房间。
  • 调用 Init 接口的线程必须于其他接口在同一线程。建议都在主线程调用接口。

函数原型

-(int)InitEngine:(NSString*)sdkAppID openID:(NSString*)openID;

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

返回值

返回值 处理
QAV_OK= 0 初始化 SDK 成功
QAV_ERR_SDK_NOT_FULL_UPDATE= 7015 检查 SDK 文件是否完整,建议删除后重新导入 SDK

出现返回值 AV_ERR_SDK_NOT_FULL_UPDATE 时,此返回值只有提示作用,并不会造成初始化失败。

  • 如果在接入过程中提示此错误,请根据提示检查 SDK 文件是否完整、SDK 文件版本是否一致。
  • 如果是在导出可执行文件之后出现此返回值,请忽略此错误,并尽量不在 UI 中提示。

示例代码

_openId = _userIdText.text;
_appId = _appIdText.text;
[[ITMGContext GetInstance] InitEngine:SDKAPPID openID:_openId];

触发事件回调

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

务必周期性调用 Poll 接口

务必周期性调用 Poll 接口且在主线程调用,以免接口回调异常。

函数原型

-(void)Poll;

示例代码

[[ITMGContext GetInstance] Poll];

系统暂停

当系统发生 Pause 事件时,需要同时通知引擎进行 Pause。
如果需要在退后台的时候暂停语音,可以在退后台的监听代码中调用 Pause 接口,恢复前台的监听事件中调用 Resume 接口。

函数原型

-(QAVResult)Pause;

系统恢复

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

函数原型

-(QAVResult)Resume;

反初始化 SDK

反初始化 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 加入房间
IsRoomEntered 是否已经进入房间
ExitRoom 退出房间
ChangeRoomType 修改用户房间音频类型
GetRoomType 获取用户房间音频类型

实时语音房间调用流程图

进房成功

进房回调结果 result 为0代表进房成功,进房接口 EnterRoom 返回值为0不代表进房成功。

鉴权信息

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

函数原型

@interface QAVAuthBuffer : NSObject
+ (NSData*) GenAuthBuffer:(unsigned int)appId roomId:(NSString*)roomId openID:(NSString*)openID key:(NSString*)key;
+ @end

参数 类型 含义
appId 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];

加入房间

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

房间的音频类型由第一个进房的人确定,此后房间里有成员修改房间类型,将对此房间所有成员生效。例如第一个进入房间的人使用的房间音频类型是流畅音质,第二个进房的是即使进房时候调用接口的音频类型参数是高清音质,进入房间之后也会变成流畅音质。需要有成员调用 ChangeRoomType 才会修改房间的音频类型。

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

函数原型

-(int)EnterRoom:(NSString*) roomId roomType:(int)roomType authBuffer:(NSData*)authBuffer;

参数 类型 含义
roomId NSString 房间号,最大支持127字符
roomType int 房间音频类型
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];
        }
    }

    成员进房、说话状态通知

    此接口适用于获取房间中说话的人并在 UI 中展示,以及有人进入、退出语音房间的一个通知。

    该事件在状态变化时才通知,状态不变化的情况下不通知。如需实时获取成员状态,请在上层收到通知时缓存,事件消息为 ITMG_MAIN_EVNET_TYPE_USER_UPDATE,其中 data 包含两个信息,event_id 及 user_list,在 OnEvent 函数中对事件消息进行判断。
    音频事件的通知有一个阈值,超过这个阈值才会发送通知。超过两秒没有收到音频包才通知“有成员停止发送音频包”消息。此事件只会返回成员说话事件,没有返回具体的音量。如需房间内成员具体音量可定期轮询接口 GetRecvStreamLevel 进行获取。

    event_id 含义 应用侧维护内容
    ITMG_EVENT_ID_USER_ENTER 有成员进入房间 应用侧维护成员列表
    ITMG_EVENT_ID_USER_EXIT 有成员退出房间 应用侧维护成员列表
    ITMG_EVENT_ID_USER_HAS_AUDIO 有成员发送音频包,通过此事件可以判断用户是否说话,并展示声纹效果,可配合 GetRecvStreamLevel 一起调用 应用侧维护通话成员列表
    ITMG_EVENT_ID_USER_NO_AUDIO 有成员停止发送音频包 应用侧维护通话成员列表

    维护房间成员流程图

    示例代码

    -(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]];
    

    实时语音音频接口

    Image

    实时语音音频接入须知

    初始化 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

    函数原型

    -(QAVResult)EnableMic:(BOOL)enable;
    

    参数 类型 含义
    isEnabled 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 用于设置麦克风的音量,相当于对采集的声音做衰减或增益,当数值为0的时候表示静音,当数值为100的时候表示音量不增不减,默认数值为100。

    此接口不适用于语音消息服务。

    函数原型

    -(QAVResult)SetMicVolume:(int) volume;
    

    参数 类型 含义
    volume int 设置音量,范围0 - 200

    示例代码

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

    获取麦克风软件音量

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

    此接口不适用于语音消息服务。

    函数原型

    -(int) GetMicVolume;
    

    示例代码

    [[[ITMGContext GetInstance] GetAudioCtrl] GetMicVolume];
    

    实时语音播放相关接口

    开启或关闭扬声器

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

    EnableSpeaker = EnableAudioPlayDevice + EnableAudioRecv

    函数原型

    -(void)EnableSpeaker:(BOOL)enable;
    

    参数 类型 含义
    isEnabled 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}
    目录