文档概览/
Live/
SDK/
iOS/
API Usage Guide/
Basic Features/
Audience Connection/

Audience Connection

本文档主要介绍如何使用 RTC Room Engine SDK 实现 观众连麦功能。
RTC Room Engine 支持如下麦位管理能力：
上麦响应配置
获取麦位列表
获取上麦请求列表
申请上麦
主动下麦
移动麦位
踢人下麦
邀请上麦
锁定麦位

前提条件

在使用 RTC RoomEngine SDK 前，您需要先调用 登录 SDK，以便后续功能正常使用。

使用指引

说明：
使用麦位管理时，您需要确保您已经开播或进入到了直播间。

上麦响应配置

iOS
Android
当您时房主时，您可以调用 updateRoomSeatModeByAdmin 接口实现，传入参数麦位模式 seatMode 即可。
seatMode 是一个 TUISeatMode 类型的枚举。
枚举值类型
含义
freeToTake
申请上麦无需等待房主同意，可直接上麦
applyToTake
申请上麦需要等待房主同意才可上麦
当您时房主时，您可以调用 updateRoomSeatModeByAdmin 接口实现，传入参数麦位模式 seatMode 即可。
seatMode 是一个 SeatMode 类型的枚举。
枚举值类型
含义
FREE_TO_TAKE
申请上麦无需等待房主同意，可直接上麦
APPLY_TO_TAKE
申请上麦需要等待房主同意才可上麦
以更新上麦相应配置为申请上麦模式为例：
iOS
Android
import RTCRoomEngine

let seatMode: TUISeatMode = .applyToTake    // 这里选择申请上麦模式，若您需要选择自由上麦模式，可更改为.freeToTake
TUIRoomEngine.sharedInstance().updateRoomSeatModeByAdmin(seatMode) {
    // 设置上麦响应配置成功
} onError: { code, message in
    // 设置上麦响应配置失败
}
TUIRoomDefine.SeatMode seatMode = TUIRoomDefine.SeatMode.APPLY_TO_TAKE;   // 这里选择申请上麦模式，若您需要选择自由上麦模式，可更改为.freeToTake
TUIRoomEngine.sharedInstance().updateRoomSeatModeByAdmin(seatMode, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 设置上麦响应配置成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 设置上麦响应配置失败
    }
});

获取麦位列表

您可以调用 getSeatList 接口获取当前的麦位列表信息。
iOS
Android
import RTCRoomEngine

TUIRoomEngine.sharedInstance().getSeatList { seatList in
    // 获取麦位列表成功
} onError: { code, messagea in
    // 获取麦位列表失败
}
TUIRoomEngine.sharedInstance().getSeatList(new TUIRoomDefine.GetSeatListCallback() {
    @Override
    public void onSuccess(List<TUIRoomDefine.SeatInfo> list) {
        // 获取麦位列表成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 获取麦位列表失败
    }
});

获取上麦请求列表

您可以调用 getSeatApplicationList 接口获取当前的上麦请求列表信息。
iOS
Android
import RTCRoomEngine

TUIRoomEngine.sharedInstance().getSeatApplicationList { applications in
    // 获取上麦请求列表成功
} onError: { code, message in
    // 获取上麦请求列表失败
}
TUIRoomEngine.sharedInstance().getSeatApplicationList(new TUIRoomDefine.RequestListCallback() {
    @Override
    public void onSuccess(List<TUIRoomDefine.Request> list) {
        // 获取上麦请求列表成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 获取上麦请求列表失败
    }
});

申请上麦

当您未上麦时，您可通过调用 takeSeat 接口实现申请上麦，传入两个参数：想要申请的麦位索引和超时时长。
以申请上1号麦为例：
iOS
Android
import RTCRoomEngine

let index = 1    // 请将这里替换成您想要申请的麦位号
let timeout = 30 // 请将这里替换成您申请上麦的超时时间,单位秒，如果设置为 0，SDK 不会做超时检测，也不会触发超时回调
TUIRoomEngine.sharedInstance().takeSeat(index, timeout: TimeInterval(timeout)) { requestId, userId in
    // 上麦申请被接受
} onRejected: { requestId, userId, message in
    // 上麦申请被拒绝
} onCancelled: { requestId, userId in
    // 上麦申请被取消
} onTimeout: { requestId, userId in
    // 上麦申请已超时
} onError: { requestId, userId, code, message in
    // 上麦异常
}
int index = 1;    // 请将这里替换成您想要申请的麦位号
int timeout = 30; // 请将这里替换成您申请上麦的超时时间,单位秒，如果设置为 0，SDK 不会做超时检测，也不会触发超时回调
TUIRoomEngine.sharedInstance().takeSeat(index, timeout, new TUIRoomDefine.RequestCallback() {
    @Override
    public void onAccepted(String requestId, String userId) {
        // 上麦申请被接受
    }
    @Override
    public void onRejected(String requestId, String userId, String message) {
        // 上麦申请被拒绝
    }
    @Override
    public void onCancelled(String requestId, String userId) {
        // 上麦申请被取消
    }
    @Override
    public void onTimeout(String requestId, String userId) {
        // 上麦申请已超时
    }

    @Override
    public void onError(String requestId, String userId, TUICommonDefine.Error error, String message) {
        // 上麦异常
    }
});
当您是房主时，若您通过 addObserver 接口成为了 RTC Room Engine SDK的观察者，则当有人申请上麦时，您会收到 onRequestReceived 回调，您可通过 responseRemoteRequest 接收或拒绝该请求。
iOS
Android
func onRequestReceived(request: TUIRequest) {
    if request.requestAction == .takeSeat {
        let agreeToTakeSeat = true   // 若您想拒绝该上麦请求，此处可置为false
        TUIRoomEngine.sharedInstance().responseRemoteRequest(request.requestId, agree: agreeToTakeSeat) {
            // 处理上麦请求成功
        } onError: { code, message in
            // 处理上麦请求失败
        }
    }
}
public void onRequestReceived(TUIRoomDefine.Request request) {
    if (TUIRoomDefine.RequestAction.REQUEST_TO_TAKE_SEAT == request.requestAction) {
        boolean agreeToTakeSeat = true;   // 若您想拒绝该上麦请求，此处可置为false
        TUIRoomEngine.sharedInstance().responseRemoteRequest(request.requestId, agreeToTakeSeat, new TUIRoomDefine.ActionCallback() {
            @Override
            public void onSuccess() {
                // 处理上麦请求成功
            }
            @Override
            public void onError(TUICommonDefine.Error error, String message) {
                // 处理上麦请求失败
            }
        });
    }
}

主动下麦

当您已经在麦上时，您可通过调用 leaveSeat 接口实现主动下麦。
iOS
Android
import RTCRoomEngine

TUIRoomEngine.sharedInstance().leaveSeat {
    // 主动下麦成功
} onError: { code, message in
    // 主动下麦失败
}
TUIRoomEngine.sharedInstance().leaveSeat(new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 主动下麦成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 主动下麦失败
    }
});

移动麦位

当您已经在麦上时，您可通过调用 moveToSeat 接口实现移动麦位功能，传入参数：想要移动到的麦位索引。
以移动到2号麦位为例：
iOS
Android
import RTCRoomEngine

let targetIndex = 2
TUIRoomEngine.sharedInstance().moveToSeat(targetSeatIndex: targetIndex) {
    // 移动麦位成功
} onError: { code, message in
    // 移动麦位失败
}
int targetIndex = 2;
TUIRoomEngine.sharedInstance().moveToSeat(targetIndex, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 移动麦位成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 移动麦位失败
    }
});

踢人下麦

当您是房主时，您可通过调用 kickUserOffSeatByAdmin 接口实现该功能，传入参数：想要踢下麦的用户的用户Id。
以将麦位用户 Id 为100001的用户踢下麦为例：
iOS
Android
import RTCRoomEngine

let targetIndex = -1     // 请将改值设为-1，其他值无任何意义
let userId = "100001"    // 请将其替换成您需要踢下麦的用户
TUIRoomEngine.sharedInstance().kickUserOffSeatByAdmin(targetIndex, userId: userId) {
    // 踢人下麦成功
} onError: { code, messagae in
    // 踢人下麦失败
}
int targetIndex = -1;     // 请将改值设为-1，其他值无任何意义
String userId = "100001";    // 请将其替换成您需要踢下麦的用户
TUIRoomEngine.sharedInstance().kickUserOffSeatByAdmin(targetIndex, userId, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 踢人下麦成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 踢人下麦失败
    }
});

邀请上麦

当您是房主时，您可通过调用 takeUserOnSeatByAdmin 接口，传入三个参数：想要操作的麦位索引、想要邀请的用户的用户Id和超时时长。
以邀请用户 Id 为 100002 的用户上4号麦为例：
iOS
Android
import RTCRoomEngine

let targetIndex = 4
let timeout = 30  // 请将这里替换成您申请上麦的超时时间,单位秒，如果设置为 0，SDK 不会做超时检测，也不会触发超时回调
let targetUserId = "100002"  // 请替换成您想要踢下麦的主播的用户Id
TUIRoomEngine.sharedInstance().takeUserOnSeatByAdmin(tartgetIndex,
                                                     userId: targetUserId,
                                                     timeout: TimeInterval(timeout)) { requestId, userId in
    // 上麦邀请被接受
} onRejected: { requestId, userId, message in
    // 上麦邀请被拒绝
} onCancelled: { requestId, userId in
    // 上麦邀请超时
} onTimeout: { requestId, userId in
    // 上麦邀请被取消
} onError: { requestId, userId, code, message in
    // 上麦邀请异常
}
int targetIndex = 4;
int timeout = 30;  // 请将这里替换成您申请上麦的超时时间,单位秒，如果设置为 0，SDK 不会做超时检测，也不会触发超时回调
String targetUserId = "100002";  // 请替换成您想要踢下麦的主播的用户Id
TUIRoomEngine.sharedInstance().takeUserOnSeatByAdmin(targetIndex, targetUserId, timeout, new TUIRoomDefine.RequestCallback() {
    @Override
    public void onAccepted(String requestId, String userId) {
        // 上麦邀请被接受
    }
    @Override
    public void onRejected(String requestId, String userId, String message) {
        // 上麦邀请被拒绝
    }
    @Override
    public void onCancelled(String requestId, String userId) {
        // 上麦邀请超时
    }
    @Override
    public void onTimeout(String requestId, String userId) {
        // 上麦邀请被取消
    }
    @Override
    public void onError(String requestId, String userId, TUICommonDefine.Error error, String message) {
        // 上麦邀请异常
    }
});
若您通过 addObserver 接口成为了 RTC Room Engine SDK的观察者，则当有人邀请您上麦时， 您会收到 onRequestReceived 回调， 您可通过调用 responseRemoteRequest 同意/拒绝对方的上麦邀请。
iOS
Android
func onRequestReceived(request: TUIRequest) {
    if request.requestAction == .remoteUserOnSeat {
        let agreeToTakeSeat = true   // 若您想拒绝该上麦邀请，此处可置为false
        TUIRoomEngine.sharedInstance().responseRemoteRequest(request.requestId, 
                                                             agree: agreeToTakeSeat) {
            // 处理上麦邀请成功
        } onError: { code, message in
            // 处理上麦邀请失败
        }
    }
}
public void onRequestReceived(TUIRoomDefine.Request request) {
    if (TUIRoomDefine.RequestAction.REQUEST_REMOTE_USER_ON_SEAT == request.requestAction) {
        boolean agreeToTakeSeat = true;   // 若您想拒绝该上麦邀请，此处可置为false
        TUIRoomEngine.sharedInstance().responseRemoteRequest(request.requestId, agreeToTakeSeat, new TUIRoomDefine.ActionCallback() {
            @Override
            public void onSuccess() {
                // 处理上麦邀请成功
            }
            @Override
            public void onError(TUICommonDefine.Error error, String message) {
                // 处理上麦邀请失败
            }
        });
    }
}

锁定麦位

iOS
Android
当您是房主，且想将5号空麦位锁定不让其他人上麦，或想将6号麦位上的主播静音且将7号麦位上的主播禁画时，可调用 lockSeat 接口，传入两个参数：将要锁定的麦位索引和锁定模式。
锁定模式(TUISeatLockParams)的结构如下：
属性名称
字段含义
补充说明
数据类型
填写示例
lockSeat
锁定麦位
锁定对应麦位则该麦位不允许申请上麦。
布尔值
当锁定麦位时为 true
lockVideo
锁定麦位摄像头
锁定对应麦位摄像头则该麦位不再发布视频流。
布尔值
false
lockAudio
锁定麦位麦克风
锁定对应麦位摄像头则该麦位不再发布音频流。
布尔值
当锁定麦位麦克风时为 true
当您是房主，且想将5号空麦位锁定不让其他人上麦，或想将6号麦位上的主播静音且将7号麦位上的主播禁画时，可调用 lockSeat 接口，传入两个参数：将要锁定的麦位索引和锁定模式。
锁定模式(SeatLockParams)的结构如下：
属性名称
字段含义
补充说明
数据类型
填写示例
lockSeat
锁定麦位
锁定对应麦位则该麦位不允许申请上麦。
布尔值
当锁定麦位时为 true
lockVideo
锁定麦位摄像头
锁定对应麦位摄像头则该麦位不再发布视频流。
布尔值
false
lockAudio
锁定麦位麦克风
锁定对应麦位摄像头则该麦位不再发布音频流。
布尔值
当锁定麦位麦克风时为 true
您可通过调用 lockSeatByAdmin 接口实现上述功能：
iOS
Android
import RTCRoomEngine

// 锁定麦位
let lockSeatIndex = 5
let lockSeatParam = TUISeatLockParams()
lockSeatParam.lockSeat = true
TUIRoomEngine.sharedInstance().lockSeatByAdmin(lockSeatIndex, 
                                               lockMode: lockSeatParam) {
    // 锁定麦位成功
} onError: { code, message in
    // 锁定麦位失败
}

// 锁定麦位麦克风
let lockSeatAudioIndex = 6
let lockSeatAudioParam = TUISeatLockParams()
lockSeatAudioParam.lockAudio = true
TUIRoomEngine.sharedInstance().lockSeatByAdmin(lockSeatAudioIndex,
                                               lockMode: lockSeatAudioParam) {
    // 锁定麦位麦克风成功
} onError: { code, message in
    // 锁定麦位麦克风失败
}

// 锁定麦位摄像头
let lockSeatVideoIndex = 7
let lockSeatVideoParam = TUISeatLockParams()
lockSeatAudioParam.lockVideo = true
TUIRoomEngine.sharedInstance().lockSeatByAdmin(lockSeatVideoIndex, 
                                               lockMode: lockSeatAudioParam) {
    // 锁定麦位摄像头成功
} onError: { code, message in
    // 锁定麦位摄像头失败
}
// 锁定麦位
int lockSeatIndex = 5;
TUIRoomDefine.SeatLockParams lockSeatParam = new TUIRoomDefine.SeatLockParams();
lockSeatParam.lockSeat = true;
TUIRoomEngine.sharedInstance().lockSeatByAdmin(lockSeatIndex, lockSeatParam, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 锁定麦位成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 锁定麦位失败
    }
});

// 锁定麦位麦克风
int lockSeatAudioIndex = 6;
TUIRoomDefine.SeatLockParams lockSeatAudioParam = new TUIRoomDefine.SeatLockParams();
lockSeatAudioParam.lockAudio = true;
TUIRoomEngine.sharedInstance().lockSeatByAdmin(lockSeatAudioIndex, lockSeatAudioParam, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 锁定麦位麦克风成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 锁定麦位麦克风失败
    }
});

// 锁定麦位摄像头
int lockSeatVideoIndex = 7;
TUIRoomDefine.SeatLockParams lockSeatVideoParam = new TUIRoomDefine.SeatLockParams();
lockSeatAudioParam.lockVideo = true;
TUIRoomEngine.sharedInstance().lockSeatByAdmin(lockSeatVideoIndex, lockSeatAudioParam, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 锁定麦位摄像头成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 锁定麦位摄像头失败
    }
});

监听回调

iOS
Android
您可通过调用 addObserver 成为 RTC Room Engine SDK的观察者，监听麦位相关的回调。
以 CoGuestController 成为观察者为例：
import RTCRoomEngine

class CoGuestController: NSObject, TUIRoomObserver {  // 请将其替换为您的业务类,这里只做示例
    override init() {
        super.init()
        TUIRoomEngine.sharedInstance().addObserver(self)
    }
    
    deinit {
        TUIRoomEngine.sharedInstance().removeObserver(self)
    }
    
    // 房间上麦模式发生变化时触发
    func onRoomSeatModeChanged(roomId: String, seatMode: TUISeatMode) {
        // 房间麦位模式改变了，当前模式：seatMode
    }
    // 当麦位列表改变时触发
    func onSeatListChanged(seatList: [TUISeatInfo], seated seatedList: [TUISeatInfo], left leftList: [TUISeatInfo]) {
        // 麦位列表改变了, 麦上最新的用户列表:seatList, 新上麦的用户列表:seatedList, 新下麦的用户列表:leftList
    }
    // 当收到其他用户的请求时触发
    func onRequestReceived(request: TUIRequest) {
        switch request.requestAction {
        case .takeSeat:
            // 收到来自request.userName的上麦请求
        case .remoteUserOnSeat:
            // 收到来自request.userName的上麦邀请
        default:
            break
        }
    }
    // 当其他用户取消请求时触发
    func onRequestCancelled(request: TUIRequest, operateUser: TUIUserInfo) {
        switch request.requestAction {
        case .takeSeat:
            // 来自request.userName的上麦请求被取消了
        case .remoteUserOnSeat:
           // 来自request.userName的上麦邀请被取消了
        default:
            break
        }
    }

    // 收到请求被其他 管理员/房主 处理时触发
    func onRequestProcessed(request: TUIRequest, operateUser: TUIUserInfo) {
        switch request.requestAction {
        case .takeSeat:
            // 来自request.userName的上麦请求被operateUser.userName处理了
        case .remoteUserOnSeat:
            // 来自request.userName的上麦邀请被operateUser.userName处理了
        default:
            break
        }
    }
}
您可通过调用 addObserver 成为 RTC Room Engine SDK的观察者，监听麦位相关的回调。
以 CoGuestObserver 成为观察者为例：
class CoGuestObserver extends TUIRoomObserver {  // 请将其替换为您的业务类,这里只做示例

    CoGuestObserver() {
        TUIRoomEngine.sharedInstance().addObserver(this);
    }

    // 房间上麦模式发生变化时触发
    @Override
    public void onRoomSeatModeChanged(String roomId, TUIRoomDefine.SeatMode seatMode) {
        // 房间麦位模式改变了，当前模式：seatMode
    }
    // 当麦位列表改变时触发
    @Override
    public void onSeatListChanged(List<TUIRoomDefine.SeatInfo> seatList, List<TUIRoomDefine.SeatInfo> seatedList,
                                  List<TUIRoomDefine.SeatInfo> leftList) {
        // 麦位列表改变了, 麦上最新的用户列表:seatList, 新上麦的用户列表:seatedList, 新下麦的用户列表:leftList
    }
    // 当收到其他用户的请求时触发
    @Override
    public void onRequestReceived(TUIRoomDefine.Request request) {
        switch (request.requestAction) {
            case REQUEST_TO_TAKE_SEAT:
            // 收到来自request.userName的上麦请求
            case REQUEST_REMOTE_USER_ON_SEAT:
            // 收到来自request.userName的上麦邀请
            default:
                break;
        }
    }
    // 当其他用户取消请求时触发
    @Override
    public void onRequestCancelled(TUIRoomDefine.Request request, TUIRoomDefine.UserInfo operateUser) {
        switch (request.requestAction) {
            case REQUEST_TO_TAKE_SEAT:
            // 来自request.userName的上麦请求被取消了
            case REQUEST_REMOTE_USER_ON_SEAT:
            // 来自request.userName的上麦邀请被取消了
            default:
                break;
        }
    }

    // 收到请求被其他 管理员/房主 处理时触发
    @Override
    public void onRequestProcessed(TUIRoomDefine.Request request, TUIRoomDefine.UserInfo operateUser) {
        switch (request.requestAction) {
            case REQUEST_TO_TAKE_SEAT:
                // 来自request.userName的上麦请求被operateUser.userName处理了
            case REQUEST_REMOTE_USER_ON_SEAT:
                // 来自request.userName的上麦邀请被operateUser.userName处理了
            default:
                break;
        }
    }
}