Discussion

你可以通过该方法监听本 AgoraRtcChannel 对象对应频道的 Delegate，并接收频道中用户视频信息等。

Discussion

Discussion

该方法在加入频道前后都能调用。

Discussion

相比于 AgoraRtcEngineKit 类下的 joinChannelByToken 方法，该方法支持通过创建多个 AgoraRtcChannel 对象，并调用相应对象的 joinChannelByToken 方法，实现同时加入多个频道。

用户成功加入频道后，默认发布本地音视频流并自动订阅频道内所有其他用户的音视频流。 订阅音视频流会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

Note

• 该方法不支持相同的用户重复加入同一个频道。
• 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 uid 是不同的。
• 请确保用于生成 Token 的 App ID 和创建 AgoraRtcEngineKit 对象时用的 App ID 一致。

Discussion

该方法与 AgoraRtcEngineKit 类下的 joinChannelByUserAccount1 方法有以下区别：

Note

• 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID，了解使用限制及实现方法。
• 该方法不支持相同的用户重复加入同一个频道。
• 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 uid 是不同的。
• 请确保用于生成 Token 的 App ID 和创建 AgoraRtcEngineKit 对象时用的 App ID 一致。

Discussion

成功调用该方法离开频道后，会触发以下回调：

• 本地：rtcChannelDidLeaveChannel 回调。
• 远端：通信场景下的用户和直播场景下的主播离开频道后，会触发 didOfflineOfUid 回调。

Discussion

Discussion

Deprecated 该方法自 v3.4.5 起废弃，请改用 muteLocalAudioStream(NO) 或 muteLocalVideoStream(NO)。

该方法的调用需满足以下要求，否则 SDK 会返回 AgoraErrorCodeRefused(-5)：

• 该方法仅支持将音视频流发布到当前 AgoraRtcChannel 类所对应的频道。
• 直播场景下，该方法仅适用于角色为主播的用户。你可以调用该 AgoraRtcChannel 类下的 setClientRole 方法设置用户角色。
• SDK 只支持用户同一时间在一个频道发布一路音视频流。详情请参考高阶指南多频道管理。

Discussion

Deprecated 该方法自 v3.4.5 起废弃，请改用 muteLocalAudioStream(YES) 或 muteLocalVideoStream(YES)。

请确保你想要 unpublish 音视频流的频道 channelId，与当前正在 publish 音视频流的频道 channelId 一致，否则 SDK 会返回 AgoraErrorCodeRefused(-5)。

Discussion

调用 setChannelProfile(AgoraChannelProfileLiveBroadcasting) 后，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：

• 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
• 本地触发 didClientRoleChanged 或 didClientRoleChangeFailed 。
• 远端触发 didJoinedOfUid 或 didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)。

Discussion

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当以下任意一种情况发生时：

• SDK 触发 tokenPrivilegeWillExpire 回调。
• connectionChangedToState 回调 reason 参数报告 AgoraConnectionChangedTokenExpired(9)。

App 应重新获取 Token，然后调用该 API 更新 Token，否则 SDK 无法和服务器建立连接。

Note

声网推荐使用 rtcChannelRequestToken 回调报告 AgoraErrorCodeTokenExpired(-109)，而不是 didOccurError 回调.

Discussion

DEPRECATED自 v3.1.0 起废弃，请改用 enableEncryption。

在加入频道之前， App 需调用 setEncryptionSecret 指定 secret 来启用内置的加密功能，同一频道内的所有用户应设置相同的 secret。 当用户离开频道时，该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空，则无法激活加密功能。

Note

• 请不要在旁路推流时调用此方法。
• 为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

Discussion

DEPRECATED自 v3.1.0 起废弃，请改用 enableEncryption。

声网 Native SDK 支持内置加密功能，默认使用 AES-128-XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

Note

• 在调用本方法前，请先调用 setEncryptionSecret 启用内置加密功能。
• 请不要在旁路推流时调用此方法。

Discussion

Discussion

如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。

弱网下 SDK 会优先保证高优先级用户收到的流的质量。

该方法需要在加入频道前调用。

Note

目前仅支持将一名远端用户设为高优先级。

Discussion

设置远端用户声音的空间位置和音量，方便本地用户听声辨位。

通过调用该接口设置远端用户声音出现的位置，左右声道的声音差异会产生声音的方位感，从而判断出远端用户的实时位置。在多人在线游戏场景，如吃鸡游戏中，该方法能有效增加游戏角色的方位感，模拟真实场景。

Note

• 该方法需要在加入频道后调用。使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声

• 为获得最佳听觉体验，我们建议：

  • 在 iOS 使用该方法时佩戴有线耳机
  • 在 macOS 使用该方法时使用立体声外放

Discussion

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

Note

• 请在调用 setupRemoteVideo 方法初始化远端视图后，调用该方法。
• 你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

Discussion

Deprecated 该方法自 v3.3.0 起废弃。

该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

Note

取消订阅音频流后，如果需要恢复订阅频道内的远端用户，可以进行如下操作：

• 如果需要恢复订阅单个用户的音频流，调用 muteRemoteAudioStream(NO)， 并指定你想要订阅的远端用户 ID。
• 如果想恢复订阅多个用户的音频流，则需要多次调用 muteRemoteAudioStream(NO) 。

Discussion

Deprecated 该方法自 v3.3.0 起废弃。

该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

Note

取消订阅视频流后，如果需要恢复订阅频道内的远端用户，可以进行如下操作：

• 如果需要恢复订阅单个用户的视频流，调用 muteRemoteVideoStream(NO)， 并指定你想要订阅的远端用户 ID。
• 如果想恢复订阅多个用户的音频流，则需要多次调用 muteRemoteVideoStream(NO) 。

Discussion

Note

• 该方法需要在加入频道后调用。
• 该方法的推荐设置详见《设置订阅状态》。

Discussion

加入频道后，你可以多次调用该方法调节不同远端用户在本地播放的音量，或对某个远端用户在本地播放的音量调节多次。

Note

• 该方法要在加入频道后调用。
• 该方法调节的是本地播放的指定远端用户混音后的音量。
• 该方法每次只能调整一位远端用户在本地播放的音量。若需调整多位远端用户在本地播放的音量，则需多次调用该方法。

Discussion

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流， 包括在调用该方法后加入频道的用户的音频流。

Note

• 该方法需要在加入频道后调用。
• 自 v3.3.0 起，该方法包含了 setDefaultMuteAllRemoteAudioStreams 的功能。声网建议不要一起调用 muteAllRemoteAudioStreams 和 setDefaultMuteAllRemoteAudioStreams，否则设置可能会不生效。详见《设置订阅状态》。

Discussion

Note

• 该方法需要在加入频道后调用。
• 该方法的推荐设置详见《设置订阅状态》。

Discussion

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的视频流， 包括在调用该方法后加入频道的用户的视频流。

Note

• 该方法需要在加入频道后调用。
• 自 v3.3.0 起，该方法包含了 setDefaultMuteAllRemoteVideoStreams 的功能。声网建议不要一起调用 muteAllRemoteVideoStreams 和 setDefaultMuteAllRemoteVideoStreams，否则设置可能会不生效。详见《设置订阅状态》。

Discussion

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode(NO) 关闭双流模式，接收端可以选择接收大流还是小流。其中，大流可以接收高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。

正常情况下，用户默认接收大流。如需接收小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 didApiCallExecute 中返回。

Discussion

该方法设置远端视频默认为大流或小流。

Note

• 该方法只能在加入频道前调用。声网不支持你在加入频道后修改默认订阅的视频流类型。
• 如果你既调用了该方法，也调用了 setRemoteVideoStream，则 SDK 以 setRemoteVideoStream 中的设置为准。

Discussion

Deprecated 该方法自 3.6.0 版废弃，替代方案请参考发版说明。

该方法用于添加旁路推流地址，调用该方法后，你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 rtmpStreamingChangedToState 回调，报告增加旁路推流地址的状态。

Note:

• 该方法仅适用于直播场景。
• 请确保在成功加入频道后再调用该接口。
• 请确保已开通旁路推流的功能，详见前提条件。
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
• 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

Discussion

Deprecated 该方法自 3.6.0 版废弃，替代方案请参考发版说明。

该方法用于删除旁路推流过程中已经设置的 RTMP/RTMPS 推流地址。调用该方法后，SDK 会在本地触发 rtmpStreamingChangedToState 回调，报告删除旁路推流地址的状态。

Note:

• 该方法仅适用于直播场景。
• 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。
• URL 不支持中文等特殊字符。

Discussion

Deprecated 该方法自 3.6.0 版废弃，替代方案请参考发版说明。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 rtcEngineTranscodingUpdated 回调。

Note:

• 该方法需要在加入频道后调用。
• 该方法仅适用于直播场景。
• 请确保已开通 CDN 旁路推流的功能，详见前提条件。
• 首次调用该方法更新转码设置时，不会触发 rtcEngineTranscodingUpdated 回调。

Discussion

Deprecated 该方法自 v3.3.0 废弃，请改用 createDataStream2。

该方法用于创建数据流。AgoraRtcChannel 生命周期内，每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 App 报错。 目前声网 Native SDK 支持 99% 可靠和 100% 有序的数据传输。

Note:

• 该方法需要在加入频道后调用。
• 不可将 reliable 设为 YES 且将 ordered 设为 NO。
• 创建数据流后，如果你离开频道，SDK 会销毁数据流。

Discussion

Discussion

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

成功调用该方法后，远端会触发 receiveStreamMessageFromUid 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 didOccurStreamMessageErrorFromUid 回调。

Note:

• 该方法仅适用于通信场景以及直播场景下的主播用户，如果直播场景下的观众调用此方法可能会造成观众变主播。
• 请确保在调用该方法前，已调用 createDataStream 创建了数据通道。

Discussion

成功调用该方法后，SDK 会触发 channelMediaRelayStateDidChange 和 didReceiveChannelMediaRelayEvent 回调，并在回调中报告当前的跨频道媒体流转发状态和事件。

• 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateRunning(2) 和 AgoraChannelMediaRelayStateIdle(0)，且 didReceiveChannelMediaRelayEvent 回调报告 AgoraChannelMediaRelayEventSentToDestinationChannel(4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。
• 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateFailure(3)，则表示跨频道媒体流转发出现异常。

Note

• 请在成功加入频道后调用该方法。
• 该方法仅对直播场景下的主播有效。
• 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
• 跨频道媒体流转发功能需要联系提交工单联系技术支持开通。
• 该功能不支持 String 型 UID。

Discussion

成功调用该方法后，SDK 会触发 didReceiveChannelMediaRelayEvent 回调，并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel(7)。

Note

• 请在成功调用 startChannelMediaRelay 方法并收到 channelMediaRelayStateDidChange (AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone) 后调用该方法；否则，方法调用会失败。
• 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了，你可以在调用该方法之前，调用 AgoraChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的频道。

Discussion

Discussion

Discussion

成功调用该方法后，SDK 会触发 channelMediaRelayStateDidChange 回调。如果报告 AgoraChannelMediaRelayStateIdle(0) 和 AgoraChannelMediaRelayErrorNone(0)，则表示已停止转发媒体流。

Discussion

Deprecated: 该方法自 v3.7.1 废弃，请改用 enableRemoteSuperResolution 方法。

Discussion

Discussion

自定义远端视频渲染器，表示自定义渲染远端用户看到的本地视频画面。实时音视频互动过程中，SDK 通常会启动默认的视频渲染器进行视频渲染。多频道场景下，当需要自定义视频渲染器时，你可以先通过 AgoraVideoSinkProtocol 自定义渲染器，然后调用该方法将自定义的渲染器添加到 AgoraRtcChannel 中。

该方法在加入频道前后都能调用。如果在加入频道前调用，需要自行维护远端用户的 uid。

Discussion

设置媒体附属信息的 Data source。你需要在该方法中实现一个 AgoraMediaMetadataDataSource 协议，并指定附属信息的数据类型。

该接口可以与 setMediaMetadataDelegate 接口搭配使用，在直播场景中实现发送商品链接、分发优惠券、发送答题等功能，构建更为丰富的直播互动方式。

Discussion

设置媒体附属信息的 Delegate。你需要在该方法中实现一个 AgoraMediaMetadataDelegate 协议，并指定附属信息的数据类型。