文档中心
互动直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

加入多频道

更新时间 2023/01/12 09:06:30

功能描述

声网 SDK 自 v2.9.0.100 起，支持用户同时加入多个频道。频道数量无限制。

加入多频道后，用户只能将本地的音视频流发布至其中一个频道，但可同时订阅多个频道内的音视频流，并分别控制各频道内的远端音视频流状态。

适用场景

该功能适用于类似在线教育行业超级小班课场景：

  • 大频道中，老师为主播，学生为观众，学生接收老师的音视频流。大频道的学生人数可达百万。
  • 与此同时，学生可分组加入多个小频道。小频道中，学⽣既发流也收流，进行实时互动。小频道中最多 17 人同时音视频互动。

实现方法

以下说明以 C++ 接口为例。OC 和 Java 接口类似，只是进行了封装和部分重命名。

声网 SDK 支持通过以下方式同时加入多个频道：

  1. 将 IRtcEngine类强转为 IRtcEngine2 类，调用 IRtcEngine2 类中的 createChannel 方法，指定频道名 channelId，创建一个 IChannel 对象。
  2. 调用该 IChannel 对象中的 joinChannel 方法加入该频道。可通过 options 参数设置是否订阅该频道内所有其他远端用户的音视频流（默认为订阅）。
  3. 多次调用 IRtcEngine2 类中的 createChannel 方法，创建多个 IChannel 对象。再调用各个 IChannel 对象中的 joinChannel 方法，即可实现加入多个频道。

通过 IChannel 对象中的 joinChannel 方法加入频道与原先的调用 IRtcEngine类中的 joinChannel 方法加入频道相比，有以下区别：

  • 调用 IRtcEngine 类中的 joinChannel 方法一次只能加入一个频道。并且加入某频道后，如果是通信场景下的用户或直播场景下的主播，会自动将本地音视频流发布到该频道。
  • IChannel 对象可同时创建多个，从而实现同时加入多个频道。通过此方法加入某频道后，需要调用 IChannel 对象中的 publish 接口才能将本地音视频流发布到本频道，同时用户的角色自动变成主播。
用户加入多个频道后，可同时订阅多个频道内的音视频流，但只能将本地的音视频流发布至一个频道。

以下结合具体场景介绍加入多频道的一种实现方式：

假设在某个超级小班课场景中，有老师 A，学生 B、C、D。

  • 老师 A 可通过 IRtcEngine 类的 joinChannel 以主播角色加入频道 1。
  • 学生 B、C、D 可通过 IRtcEngine2 类中的 createChannel 方法获取频道 1 的 IChannel 对象，调用该 IChannel 对象中的 joinChannel 方法以观众角色加入频道 1。
  • 学生 B、C、D 再通过 IRtcEngine 类的 joinChannel 以主播角色加入频道 2。
一个用户不能重复加入同一个频道。有以下三种情况：
  • 如果该用户通过 IRtcEngine 类中的 joinChannel 方法加入了频道 1，再通过 createChannel 接口创建频道 1 的对象，此时返回的对象，实际上就是 IRtcEngine 对象，我们不建议这么做。
  • 如果该用户通过 IRtcEngine2 类中的 createChannel 方法创建了频道 1 的对象，再通过 createChannel 依旧创建频道 1 的对象，两个对象实际上是一样的。
  • 如果该用户通过 IRtcEngine2 类中的 createChannel 方法创建了频道 1 的对象，再通过 IRtcEngine 类中的 joinChannel 方法加入频道 1，会被拒绝。

    • API 说明

    VideoCanvas 结构体新增 channelId 参数

    v2.9.0.100 在 IRtcEngine 类 VideoCanvas 结构体中新增 channelId 参数。具体说明如下：

    • 如果没有设置该参数，则表示为该 UID 在通过 IRtcEngine 类 joinChannel 方法所加入频道内的渲染视图。
    • 如果设置该参数，则代表该 UID 在所指定频道内的渲染视图。

    新增 IRtcEngine2 类

    v2.9.0.100 新增 IRtcEngine2 类，包含以下方法：

    创建频道

    virtual IChannel* createChannel(const char *channelId) = 0;

    该方法通过一个 channelId 创建一个 IChannel 对象。

    可多次调用该方法，创建多个 IChannel 对象。再调用各个 IChannel 对象中的 joinChannel 方法，即可实现加入多个频道。

    如果指定的 channelId 所对应的 IChannel 对象已经存在，则直接返回该对象。

    参数 描述
    channelId 频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）：
  • 26 个小写英文字母 az
  • 26 个大写英文字母 AZ
  • 10个数字 09
  • 空格
  • "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、""、","
    		•

    新增 IChannel 类

    v2.9.0.100 新增 IChannel 类，包含以下方法：

    OC 中为 AgoraRtcChannel 类；Java 中为 RtcChannel 类

    释放对象

    virtual int release() = 0;

    释放本 IChannel 对象。

    OC 和 Java 中为 destroy。

    设置回调

    virtual int setChannelEventHandler(IChannelEventHandler *channelEh) = 0;

    设置一个 IChannel 对象的回调。

    通过该回调，可以获取到本 IChannel 对象关联频道的事件，如加入频道成功、频道中用户视频流信息等。

    参数 描述
    channelEh 详见 IChannelEventHandler 类

    通过 UID 加入频道

    virtual int joinChannel(const char* token,
                        const char* info,
                        uid_t uid,
                        const ChannelMediaOptions& options) = 0;

    通过 UID 加入频道。

    该方法的 token、info 和 uid 参数类似于 IRtcEngine类 joinChannel 方法的对应参数。

    该方法与 IRtcEngine类中的 joinChannel 方法有以下区别：

    1. 无 channelId参数，因为创建 IChannel 对象时已指定了 channelId。
    2. 增加了 options 参数，可在加入频道前通过该参数设置是否订阅该频道内所有其他远端用户的音视频流（默认为订阅），详见下文 ChannelMediaOptions 结构体。
    3. 用户通过 IRtcEngine类中的 joinChannel 方法加入频道后，默认会将本地音视频流发布到该频道；而用户通过 IChannel 对象加入频道后，需要调用 publish 方法才能将本地音视频流发布到本频道。

    ChannelMediaOptions 结构体

    struct ChannelMediaOptions {
    bool autoSubscribeAudio;
    bool autoSubscribeVideo;
    ChannelMediaOptions()
    : autoSubscribeAudio(true)
    , autoSubscribeVideo(true)
    {}
};
    参数 描述
    autoSubscribeAudio 设置是否订阅该频道的所有远端音频流：
  • true:（默认）订阅
  • false: 不订阅
    		•
    autoSubscribeVideo 设置是否订阅该频道的所有远端视频流：
  • true:（默认）订阅
  • false: 不订阅
    		•

    autoSubscribeAudio 和 autoSubscribeVideo 参数的功能等同于 muteAllRemoteAudioStreams 和 muteAllRemoteVideoStreams 方法。我们建议：

    • 在加入频道前通过 autoSubscribeAudio 和 autoSubscribeVideo 参数设置是否订阅该频道内所有其他远端用户的音视频流。
    • 在加入频道后调用 muteAllRemoteAudioStreams 和 muteAllRemoteVideoStreams 方法更改该频道内远端音视频流的接收状态。

    通过 User Account 加入频道

    virtual int joinChannelWithUserAccount(const char* token,
                                       const char* userAccount,
                                       const ChannelMediaOptions& options) = 0;

    通过 User Account 加入频道。参考 IRtcEngine类 joinChannelWithUserAccount 方法。

    离开频道

    virtual int leaveChannel() = 0;

    离开本频道。

    发布本地音视频流

    virtual int publish() = 0;

    将本地音视频流发布到本频道。

    直播场景下，该方法会同时将用户的角色变成主播。

    注意：

    1. 调用该方法前，请确保当前本地音视频流没有发布到其他频道。
    2. 如果用户加入某个 IChannel 频道并 publish 后，再调用 IRtcEngine 类的 joinChannel 方法加入另一个频道，会被拒绝，这是因为主播通过 IRtcEngine类中的 joinChannel 方法加入某频道后，会自动将本地音视频流发布到该频道。

    停止发布本地音视频流

    virtual int unpublish() = 0;

    停止发布本地音视频流。

    直播场景下，该方法会同时将用户的角色变成观众。

    获取频道名

    virtual const char *channelId() = 0;

    获取本频道的频道名 channelId。

    我们不建议获取 IRtcEngine 的 IChannel对象的 channelId，因为该 channelId可能会因为 IRtcEngine 的 leaveChannel 再 joinChannel 而有所变化。

    其他方法

    以下方法的注释可直接参考 IRtcEngine 中对应方法的注释，均只对本频道起作用，不影响其他频道。

    方法 说明
    virtual int getCallId(agora::util::AString& callId) = 0; 获取本次通话 ID。参考 IRtcEngine 中的 getCallId
    virtual int renewToken(const char* token) = 0; 更新 Token。参考 IRtcEngine 中的 renewToken
    virtual int setEncryptionSecret(const char* secret) = 0; 启用内置加密。参考 IRtcEngine 中的 setEncryptionSecret
    virtual int setEncryptionMode(const char* encryptionMode) = 0; 设置内置的加密方案。参考 IRtcEngine 中的 setEncryptionMode
    virtual int registerPacketObserver(IPacketObserver* observer) = 0; 注册数据包观测器。参考 IRtcEngine 中的 registerPacketObserver
    virtual int registerMediaMetadataObserver(IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type) = 0; 注册媒体 Metadata 观测器。参考 IRtcEngine 中的 registerMediaMetadataObserver
    virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; 设置直播场景下的用户角色。参考 IRtcEngine 中的 setClientRole
    virtual int setRemoteUserPriority(uid_t uid, PRIORITY_TYPE userPriority) = 0; 设置远端用户流的优先级。参考 IRtcEngine 中的 setRemoteUserPriority
    virtual int setRemoteVoicePosition(int uid, double pan, double gain) = 0; 设置远端用户的语音位置。参考 IRtcEngine 中的 setRemoteVoicePosition
    virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) = 0; 设置远端视图显示模式。参考 IRtcEngine 中的 setRemoteRenderMode
    virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; 设置是否默认接收所有音频流。参考 IRtcEngine 中的 setDefaultMuteAllRemoteAudioStreams
    virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; 设置是否默认停止接收视频流。参考 IRtcEngine 中的 setDefaultMuteAllRemoteVideoStreams
    virtual int muteAllRemoteAudioStreams(bool mute) = 0; 接收／停止接收所有音频流。参考 IRtcEngine 中的 muteAllRemoteAudioStreams
    virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; 接收／停止接收指定音频流。参考 IRtcEngine 中的 muteRemoteAudioStream
    virtual int muteAllRemoteVideoStreams(bool mute) = 0; 接收／停止接收所有远端视频流。参考 IRtcEngine 中的 muteAllRemoteVideoStreams
    virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0; 接收／停止接收指定远端用户的视频流。参考 IRtcEngine 中的 muteRemoteVideoStream
    virtual int setRemoteVideoStreamType(uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType) = 0; 设置订阅的视频流类型。参考 IRtcEngine 中的 setRemoteVideoStreamType需要通过 IRtcEngine 类的 enableDualStreamMode 启动双流，设置小流才能生效。
    virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; 设置默认订阅的视频流类型。 参考 IRtcEngine 中的 setRemoteDefaultVideoStreamType
    virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; 创建数据流。 参考 IRtcEngine 中的 createDataStream
    virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; 发送数据流。 参考 IRtcEngine 中的 sendStreamMessage
    virtual int addPublishStreamUrl(const char *url, bool transcodingEnabled) = 0; 增加旁路推流地址。参考 IRtcEngine 中的 addPublishStreamUrl仅在调用 publish 方法将本地音视频流发布到本频道时才生效。
    virtual int removePublishStreamUrl(const char *url) = 0; 删除旁路推流地址。参考 IRtcEngine 中的 removePublishStreamUrl
    virtual int setLiveTranscoding(const LiveTranscoding &transcoding) = 0; 设置直播转码。参考 IRtcEngine 中的 setLiveTranscoding
    virtual int addInjectStreamUrl(const char* url, const InjectStreamConfig& config) = 0; 导入在线媒体流。参考 IRtcEngine 中的 addInjectStreamUrl
    virtual int removeInjectStreamUrl(const char* url) = 0; 删除导入的在线媒体流。参考 IRtcEngine 中的 removeInjectStreamUrl
    virtual int startChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0; 开始跨频道媒体流转发。参考 IRtcEngine 中的 startChannelMediaRelay
    virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0; 更新媒体流转发的频道。 参考 IRtcEngine 中的 updateChannelMediaRelay
    virtual int stopChannelMediaRelay() = 0; 停止跨频道媒体流转发。参考 IRtcEngine 中的 stopChannelMediaRelay
    virtual CONNECTION_STATE_TYPE getConnectionState() = 0; 获取当前网络连接状态。参考 IRtcEngine 中的 getConnectionState

    新增 IChannelEventHandler 类

    IChannelEventHandler 类为 IChannel 对象的回调句柄，其中的回调方法摘选自 IRtcEngineEventHandler 类中的频道相关回调，功能类似。

    区别在于，IChannelEventHandler 类中的回调都增加了该回调对应的 IChannel 对象，以便开发者直接在回调中通过该对象进行相关设置。

    回调 说明
    virtual void onChannelWarning(IChannel *rtcChannel, int warn, const char* msg) 发生警告回调。
    参考 IRtcEngineEventHandler 中的 onWarning
    virtual void onChannelError(IChannel *rtcChannel, int err, const char* msg) 发生错误回调。
    参考 IRtcEngineEventHandler 中的 onError
    virtual void onJoinChannelSuccess(IChannel *rtcChannel, uid_t uid, int elapsed) 加入频道回调。
    参考 IRtcEngineEventHandler 中的 onJoinChannelSuccess
    virtual void onRejoinChannelSuccess(IChannel *rtcChannel, uid_t uid, int elapsed) 重新加入频道回调。
    参考 IRtcEngineEventHandler 中的 onRejoinChannelSuccess
    virtual void onLeaveChannel(IChannel *rtcChannel, const RtcStats& stats) 离开频道回调。
    参考 IRtcEngineEventHandler 中的 onLeaveChannel
    virtual void onClientRoleChanged(IChannel *rtcChannel, CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole) 直播场景下用户角色已切换回调。
    参考 IRtcEngineEventHandler 中的 onClientRoleChanged
    virtual void onUserJoined(IChannel *rtcChannel, uid_t uid, int elapsed) 远端用户（通信场景）/主播（直播场景）加入当前频道回调。
    参考 IRtcEngineEventHandler 中的 onUserJoined
    virtual void onUserOffline(IChannel *rtcChannel, uid_t uid, USER_OFFLINE_REASON_TYPE reason) 远端用户（通信场景）/主播（直播场景）离开当前频道回调。
    参考 IRtcEngineEventHandler 中的 onUserOffline
    virtual void onConnectionLost(IChannel *rtcChannel) 网络连接丢失回调。
    参考 IRtcEngineEventHandler 中的 onConnectionLost
    virtual void onRequestToken(IChannel *rtcChannel) Token 已过期回调。
    参考 IRtcEngineEventHandler 中的 onRequestToken
    virtual void onTokenPrivilegeWillExpire(IChannel *rtcChannel, const char* token) Token 服务即将过期回调。
    参考 IRtcEngineEventHandler 中的 onTokenPrivilegeWillExpire
    virtual void onRtcStats(IChannel *rtcChannel, const RtcStats& stats) 当前通话统计回调。
    参考 IRtcEngineEventHandler 中的 onRtcStats
    virtual void onNetworkQuality(IChannel *rtcChannel, uid_t uid, int txQuality, int rxQuality) 网络上下行质量报告回调。
    参考 IRtcEngineEventHandler 中的 onNetworkQuality
    virtual void onRemoteVideoStats(IChannel *rtcChannel, const RemoteVideoStats& stats) 远端视频流统计信息回调。
    参考 IRtcEngineEventHandler 中的 onRemoteVideoStats
    virtual void onRemoteAudioStats(IChannel *rtcChannel, const RemoteAudioStats& stats) 远端音频流的统计信息回调。
    参考 IRtcEngineEventHandler 中的 onRemoteAudioStats
    virtual void onRemoteAudioStateChanged(IChannel *rtcChannel, uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) 远端用户音频流状态已变化回调。
    参考 IRtcEngineEventHandler 中的 onRemoteAudioStateChanged
    virtual void onActiveSpeaker(IChannel *rtcChannel, uid_t uid) 监测到活跃用户回调。
    参考 IRtcEngineEventHandler 中的 onActiveSpeaker
    virtual void onFirstRemoteVideoFrame(IChannel *rtcChannel, uid_t uid, int width, int height, int elapsed) 已显示远端视频首帧回调。
    参考 IRtcEngineEventHandler 中的 onFirstRemoteVideoFrame
    virtual void onUserMuteAudio(IChannel *rtcChannel, uid_t uid, bool muted) 远端用户暂停/恢复发送音频流回调。
    参考 IRtcEngineEventHandler 中的 onUserMuteAudio
    virtual void onFirstRemoteAudioDecoded(IChannel *rtcChannel, uid_t uid, int elapsed) 已解码远端音频首帧回调。
    参考 IRtcEngineEventHandler 中的 onFirstRemoteAudioDecoded
    virtual void onVideoSizeChanged(IChannel *rtcChannel, uid_t uid, int width, int height, int rotation) 本地或远端视频大小和旋转信息发生改变回调。
    参考 IRtcEngineEventHandler 中的 onVideoSizeChanged
    virtual void onRemoteVideoStateChanged(IChannel *rtcChannel, uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) 远端用户视频流状态已变化回调。
    参考 IRtcEngineEventHandler 中的 onRemoteVideoStateChanged
    virtual void onStreamMessage(IChannel *rtcChannel, uid_t uid, int streamId, const char* data, size_t length) 接收到对方数据流消息回调。
    参考 IRtcEngineEventHandler 中的 onStreamMessage
    virtual void onStreamMessageError(IChannel *rtcChannel, uid_t uid, int streamId, int code, int missed, int cached) 接收对方数据流消息发生错误回调。
    参考 IRtcEngineEventHandler 中的 onStreamMessageError
    virtual void onChannelMediaRelayStateChanged(IChannel *rtcChannel, CHANNEL_MEDIA_RELAY_STATE state,CHANNEL_MEDIA_RELAY_ERROR code) 跨频道媒体流转发状态发生改变回调。
    参考 IRtcEngineEventHandler 中的 onChannelMediaRelayStateChanged
    virtual void onChannelMediaRelayEvent(IChannel *rtcChannel, CHANNEL_MEDIA_RELAY_EVENT code) 跨频道媒体流转发事件回调。
    参考 IRtcEngineEventHandler 中的 onChannelMediaRelayEvent
    virtual void onFirstRemoteAudioFrame(IChannel *rtcChannel, uid_t uid, int elapsed) 已接收远端音频首帧回调。
    参考 IRtcEngineEventHandler 中的 onFirstRemoteAudioFrame
    virtual void onRtmpStreamingStateChanged(IChannel *rtcChannel, const char *url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) RTMP 推流状态发生改变回调。
    参考 IRtcEngineEventHandler 中的 onRtmpStreamingStateChanged
    virtual void onStreamPublished(IChannel *rtcChannel, const char *url, int error) 旁路推流已开启回调。
    参考 IRtcEngineEventHandler 中的 onStreamPublished
    virtual void onStreamUnpublished(IChannel *rtcChannel, const char *url) 旁路推流已停止回调。
    参考 IRtcEngineEventHandler 中的 onStreamUnpublished
    virtual void onTranscodingUpdated(IChannel *rtcChannel) 旁路推流设置已被更新回调。
    参考 IRtcEngineEventHandler 中的 onTranscodingUpdated
    virtual void onStreamInjectedStatus(IChannel *rtcChannel, const char* url, uid_t uid, int status) 导入在线媒体流状态回调。
    参考 IRtcEngineEventHandler 中的 onStreamInjectedStatus
    virtual void onRemoteSubscribeFallbackToAudioOnly(IChannel *rtcChannel, uid_t uid, bool isFallbackOrRecover) 远端订阅流已回退为音频流或恢复为音视频流回调。
    参考 IRtcEngineEventHandler 中的 onRemoteSubscribeFallbackToAudioOnly
    virtual void onConnectionStateChanged(IChannel *rtcChannel, CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason) 网络连接状态已改变回调。
    参考 IRtcEngineEventHandler 中的 onConnectionStateChanged