Agora Unity SDK API Reference

AgoraChannel 类

释放 AgoraChannel 对象。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • ERR_NOT_INITIALIZED(-7): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 AgoraChannel 对象并完成初始化。

通过 UID 加入频道。

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

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

注解

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

参数

token	在你服务器上生成的 Token。详见使用 Token 鉴权。
info	（非必选项）开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。
uid	用户 ID，32 位无符号整数。建议设置范围：1 到 232-1，并保证唯一性。如果不指定（即设为 0），SDK 会自动分配一个，并在 OnJoinChannelSuccessHandler 回调中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
channelMediaOptions	频道媒体设置选项: ChannelMediaOptions。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
  • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
    • 已经创建了一个同名的 AgoraChannel 频道。
    • 已经通过 AgoraChannel 加入了一个频道，并在该 AgoraChannel 频道中发布了音视频流。由于通过 IRtcEngine 加入频道会默认发布音视频流，而 SDK 不支持同时在两个频道发布音视频流，因此会报错。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 IRtcEngine 对象并完成初始化。

通过 User account 加入频道。

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

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

注解

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

参数

token	在你服务器上生成的 Token。详见使用 Token 鉴权。
userAccount	用户 User Account。该参数为必需，最大不超过 255 字节，不可为 null。请确保加入频道的 User Account 的唯一性。 以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
channelMediaOptions	频道媒体设置选项: ChannelMediaOptions。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • ERR_INVALID_ARGUMENT (2)
  • ERR_NOT_READY (3)
  • ERR_REFUSED (5)
  • ERR_NOT_INITIALIZED (7)

离开频道。

离开频道，即挂断或退出通话。

加入频道后，必须调用 LeaveChannel 结束通话，否则无法开始下一次通话。不管当前是否在通话中，都可以调用 LeaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。

该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 ChannelOnLeaveChannelHandler 回调。

成功调用该方法离开频道后，本地会触发 ChannelOnLeaveChannelHandler 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 ChannelOnUserOffLineHandler 回调。

注解

• 如果你调用了 LeaveChannel 后立即调用 ReleaseChannel，SDK 将无法触发 ChannelOnLeaveChannelHandler 回调。
• 如果你在旁路推流时调用 LeaveChannel 方法， SDK 将自动调用 RemovePublishStreamUrl 方法。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

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

弃用:

该方法自 v3.4.5 起废弃，请改用 MuteLocalAudioStream (false) 或 MuteLocalVideoStream (false)。

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

• 该方法仅支持将音视频流发布到当前 AgoraChannel 类所对应的频道。
• 直播场景下，该方法仅适用于角色为主播的用户。你可以调用该 AgoraChannel 类下的 SetClientRole 方法设置用户角色。
• SDK 只支持用户同一时间在一个频道发布一路音视频流。详情请参考进阶功能《加入多频道》。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • ERR_REFUSED (5): 调用被拒绝

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

弃用:

该方法自 v3.4.5 起废弃，请改用 MuteLocalAudioStream (true) 或 MuteLocalVideoStream (true)。

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

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • ERR_REFUSED (5): 调用被拒绝

获取当前频道的频道名。

返回

• 方法调用成功，返回 channelId，即当前频道的频道名。
• 方法调用失败，返回空字符串 ""。

获取当前通话 ID。

客户端在每次加入频道后会生成一个对应的 callId，标识该客户端的此次通话。有些方法如 Rate、Complain，需要在通话结束后调用，向 SDK 提交反馈，这些方法必须指定 callId 参数。使用这些反馈方法，需要在通话过程中调用 GetCallId 方法获取 callId，在通话结束后在反馈方法中作为参数传入。

注解

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

返回

• 方法调用成功则返回当前的通话 ID。
• 方法调用失败则返回空字符串。

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当：

• 发生 ChannelOnTokenPrivilegeWillExpireHandler 回调时，或发生
• ChannelOnConnectionStateChangedHandler 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。

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

参数

token

新的 Token。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

启用内置加密，并设置数据加密密钥。

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

注解

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

参数

secret

加密密码。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置内置的加密模式。

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

注解

在调用本方法前，请先调用 SetEncryptionSecret 启用内置加密功能。

参数

encryptionMode

加密模式： "aes-128-xts": 128 位 AES 加密，XTS 模式； "aes-128-ecb": 128 位 AES 加密，ECB 模式； "aes-256-xts": 256 位 AES 加密，XTS 模式； "": 设置为空字符串时，默认使用加密模式 "aes-128-xts"。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置直播场景下的用户角色。

在加入频道前，用户需要通过本方法设置观众（默认）或主播场景。在加入频道后，用户可以通过本方法切换用户场景。

直播场景下，如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 ChannelOnClientRoleChangedHandler 回调；远端会触发 ChannelOnUserJoinedHandler 回调或 ChannelOnUserOffLineHandler (BECOME_AUDIENCE) 回调。

注解

该方法仅适用于直播场景。

参数

role	直播场景里的用户角色: CLIENT_ROLE_TYPE。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置远端用户流的优先级。

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

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

注解

• 目前 Agora SDK 仅允许将一名远端用户设为高优先级。
• 该方法需要在加入频道前调用。

参数

uid	远端用户的 ID。
userPriority	远端用户的需求优先级。详见: PRIORITY_TYPE 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置远端用户的语音位置。

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

注解

• 如果想调用 SetRemoteVoicePosition 实现听声辨位的功能，请确保在加入频道前调用 EnableSoundPositionIndication 开启远端用户的语音立体声。
• 为获得最佳听觉体验，我们建议使用该方法时使用立体声外放。
• 该方法需要在加入频道后调用。

参数

uid	远端用户的 ID。
pan	设置远端用户声音的空间位置，取值范围为 [-1.0,1.0]: 0.0: (默认）声音出现在正前方。 -1.0: 声音出现在左边。 1.0: 声音出现在右边。
gain	设置远端用户声音的音量，取值范围为 [0.0,100.0]，默认值为 100.0，表示该用户的原始音量。取值越小，则音量越低。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

默认取消或恢复订阅远端用户的音频流。

弃用:

该方法自 v3.3.1 起废弃。

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

注解

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

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

参数

mute	是否默认取消订阅远端用户的音频流： true: 默认取消订阅。 false: （默认）默认订阅。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

默认取消或恢复订阅远端用户的视频流。

弃用:

该方法自 v3.3.1 起废弃。

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

注解

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

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

参数

mute	是否默认取消订阅远端用户的视频流： true: 默认取消订阅。 false: （默认）默认订阅。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

取消或恢复订阅所有远端用户的音频流。

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

注解

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

参数

mute	是否取消订阅所有远端用户的音频流。 true: 取消订阅。 false: （默认）订阅。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

调节本地播放的指定远端用户的信号音量。

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

注解

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

参数

userId	远端用户 ID。
volume	播放音量，取值范围为 [0,100]: 0: 静音 100: 原始音量

返回

• 0: 方法调用成功
• < 0: 方法调用失败

取消或恢复订阅指定远端用户的音频流。

注解

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

参数

userId	指定用户的用户 ID。
mute	是否取消订阅指定远端用户的音频流。 true: 取消订阅。 false:（默认）订阅。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

取消或恢复订阅所有远端用户的视频流。

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

注解

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

参数

mute	是否取消订阅所有远端用户的视频流。 true: 取消订阅。 false: （默认）订阅。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

取消或恢复订阅指定远端用户的视频流。

注解

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

参数

userId	指定用户的用户 ID。
mute	是否取消订阅指定远端用户的视频流。 true: 取消订阅。 false:（默认）订阅。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置订阅的视频流类型。

如果发送端选择发送视频双流 (大流，即高分辨率、高码率视频流，或小流，即低分辨率、低码率视频流)，接收端可以选择接收大流还是小流。该方法可以根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。

• 如果发送端用户已调用 EnableDualStreamMode 启用了双流模式，默认接收大流。如需使用小流，可调用本方法进行切换；
• 如果发送端用户未启用双流模式，默认接收大流。

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

注解

该方法需要在加入频道后调用。如果既调用了 SetRemoteVideoStreamType，也调用了 SetRemoteDefaultVideoStreamType EnableDualStreamMode，则 SDK 以 SetRemoteVideoStreamType 中的设置为准。

参数

userId	用户 ID。
streamType	视频流类型: REMOTE_VIDEO_STREAM_TYPE.

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置默认订阅的视频流类型。

如果发送端选择发送视频双流 (大流，即高分辨率、高码率视频流，或小流，即低分辨率、低码率视频流)，接收端可以选择接收大流还是小流。

• 如果用户已调用 EnableDualStreamMode 启用了双流模式，默认接收大流。如需使用小流，可调用本方法进行切换。
• 如果用户未启用双流模式，默认接收大流。

调用本方法的执行结果将 OnApiExecutedHandler 中返回。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

注解

该方法需要在加入频道后调用。如果既调用了 SetRemoteVideoStreamType，也调用了 SetRemoteDefaultVideoStreamType EnableDualStreamMode，则 SDK 以 SetRemoteVideoStreamType 中的设置为准。

参数

streamType

视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

创建数据流。

弃用:

该方法自 v3.3.1 起废弃，请改用 CreateDataStream2。

该方法用于创建数据流。AgoraChannel 生命周期内，每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 app 报错。

注解

• Agora 不支持你将 reliable 设为 true 且 ordered 设为 false。
• 该方法需要在加入频道后调用。

参数

reliable	true: 接收方 5 秒内会收到发送方所发送的数据，否则会收到 OnStreamMessageErrorHandler 回调获得相应报错信息。 false: 接收方不保证收到，就算数据丢失也不会报错。
ordered	true: 接收方 5 秒内会按照发送方发送的顺序收到数据包； false: 接收方不保证按照发送方发送的顺序收到数据包。

返回

• ≥ 0: 方法调用成功则返回数据流 ID。
• < 0: 方法调用失败。

创建数据流。

自从

v3.3.1

该方法用于创建数据流。每个用户在每个频道内最多只能创建 5 个数据流。

相比 CreateDataStream1， 本方法不支持数据可靠，接收方会丢弃超出发送时间 5 秒后的数据包。

参数

config

数据流设置：DataStreamConfig

返回

• ≥ 0: 方法调用成功则返回数据流 ID。
• < 0: 创建数据流失败。

发送数据流。

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

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

注解

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

参数

streamId	由 CreateDataStream 返回的数据流 ID。
data	自定义数据。
length	数据长度。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

增加旁路推流地址。

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

注解

• 请确保在成功加入频道后才能调用该接口。
• 请确保已开通旁路推流的功能。
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
• 在直播场景中，只有角色为主播的用户才能调用该方法。
• Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

参数

url	CDN 推流地址，格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
transcodingEnabled	true: 转码（ 转码 是指在旁路推流时对音视频流进行转码处理后再推送到其他 CDN 服务器。多适用于频道内有多个主播，需要进行混流、合图的场景）。如果设为 true，需先调用 SetLiveTranscoding 方法。 false: 不转码。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。
  • ERR_INVALID_ARGUMENT(-2): URL 为空或是长度为 0 的的字符串。
  • ERR_NOT_INITIALIZED(-7): 推流时未初始化引擎。

删除旁路推流地址。

调用该方法后，SDK 会在本地触发 ChannelOnRtmpStreamingStateChangedHandler 回调，报告删除旁路推流地址的状态。

注解

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

参数

url	待删除的旁路推流地址，格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

设置直播推流转码。

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

注解

• 在直播场景中，只有角色为主播的用户才能调用该方法。
• 请确保已开通旁路推流的功能。
• 首次调用该方法更新转码设置时，不会触发 ChannelOnTranscodingUpdatedHandler 回调。
• 该方法需要在加入频道后调用。
• Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

参数

liveTranscoding

详见 LiveTranscoding 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

输入在线媒体流。

该方法将正在播放的音视频作为音视频源输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后，SDK 会在本地触发 OnStreamInjectedStatusHandler 回调，报告输入在线媒体流的状态；成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 OnUserJoinedHandler 回调，其中 uid 为 666。该音视频流会出现在频道中。

警告

客户端输入在线媒体流功能即将停服。如果你尚未集成该功能，Agora 建议你不要使用。详见《部分服务下架计划》。

注解

• 请确保已开通旁路推流的功能。
• 该方法适用于 RTC SDK v2.9.1 及之后的版本。
• 该方法仅适用于直播场景中的主播用户。
• 频道内同一时间只允许输入一个在线媒体流。
• 该方法需要在加入频道后调用。

参数

url	添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。 支持的音频编码格式：AAC； 支持的视频编码格式：H.264(AVC)。
config	所添加的视频流属性定义，详见: InjectStreamConfig 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。 -ERR_INVALID_ARGUMENT(-2): 输入的 URL 为空。请重新调用该方法，并确认输入的媒体流的 URL 有效。 -ERR_NOT_READY(-3): 用户没有加入频道。 -ERR_NOT_SUPPORTED(-4): 频道非直播场景。请调用 SetChannelProfile 并将频道设置为直播场景再调用该方法。 -ERR_NOT_INITIALIZED(-7): 引擎没有初始化。请确认调用该方法前已创建 IRtcEngine 对象并完成初始化。

删除输入的外部媒体流。

警告

客户端输入在线媒体流功能即将停服。如果你尚未集成该功能，Agora 建议你不要使用。详见《部分服务下架计划》。

注解

成功删除外部视频源 URL 地址后会触发 ChannelOnUserOffLineHandler 回调，uid 为 666。

参数

url	已输入、待删除的外部视频源 URL 地址。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

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

• 如果 ChannelOnMediaRelayStateChangedHandler 回调报告 RELAY_STATE_RUNNING(2) 和 RELAY_OK(0)，且 ChannelOnMediaRelayEventHandler 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。
• 如果 ChannelOnMediaRelayStateChangedHandler 回调报告 RELAY_STATE_FAILURE(3)，则表示跨频道媒体流转发出现异常。

注解

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

参数

channelMediaRelayConfiguration

跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

更新媒体流转发的频道。成功开始跨频道转发媒体流后，如果你希望将流转发到多个目标频道，或退出当前的转发频道，可以调用该方法。

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

注解

请在 StartChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。

参数

channelMediaRelayConfiguration

跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

停止跨频道媒体流转发。一旦停止，主播会退出所有目标频道。

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

注解

如果该方法调用不成功，SDK 会触发 ChannelOnMediaRelayStateChangedHandler 回调，并报告状态码 RELAY_ERROR_SERVER_NO_RESPONSE(2) 或 RELAY_ERROR_SERVER_CONNECTION_LOST(8)。你可以调用 LeaveChannel 方法离开频道，跨频道媒体流转发会自动停止。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。

获取当前网络连接状态。

注解

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

返回

CONNECTION_STATE_TYPE

设置直播场景下的用户角色。

自从

v3.2.0

在加入频道前和加入频道后均可调用该方法设置用户角色。

如果你在加入频道后调用该方法成功切换用户角色，SDK 会触发以下回调：

• 本地触发 ChannelOnClientRoleChangedHandler 回调。
• 远端触发 ChannelOnUserJoinedHandler 或 ChannelOnUserOffLineHandler 回调。

注解

• 该方法仅在频道场景为直播时生效。
• 该方法与 SetClientRole1 的区别在于，该方法还支持设置用户级别。
  • 用户角（role）确定用户在 SDK 层的权限，包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
  • 用户级别（level）需要与角色结合使用，确定用户在其权限范围内，可以操作和享受到的服务级别。例如对于观众，选择接收低延时还是超低延时的视频流。不同的级别会影响计费。

参数

role	直播场景中的用户角色，详见 CLIENT_ROLE_TYPE
audienceLatencyLevel	用户具体设置，包含用户级别，详见 ClientRoleOptions

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

开启或关闭内置加密。

自从

v3.1.0

在安全要求较高的场景下，Agora 建议你在加入频道前，调用 EnableEncryption 方法开启内置加密。

用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

自 v3.4.5 起，Agora 推荐使用 AES_128_GCM2 或 AES_256_GCM2 加密模式。 这两种模式支持设置盐，安全性更高。设置方法详见《媒体流加密》。

警告

同一频道内所有用户必须使用相同的加密模式、密钥和盐，否则用户之间无法互通。

注解

• 如果开启了内置加密，则不能使用 RTMP/RTMPS 推流功能。
• 为加强安全性，Agora 建议每次启用媒体流加密时都更换新的密钥和盐。

参数

enabled	是否开启内置加密： true: 开启 false: 关闭
encryptionConfig	配置内置加密方案。详见 EncryptionConfig。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
  • -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。需在调用 API 之前已创建 IRtcEngine 对象并完成初始化。

取消或恢复发布本地视频流。

自从

v3.4.5

该方法仅设置用户在 AgoraChannel 频道中的视频发布状态。

成功调用该方法后，远端会触发 OnRemoteVideoStateChangedHandler 回调。

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中 调用 MuteLocalVideoStream (false)， 否则方法会调用失败并返回 -5 (ERR_REFUSED)。

注解

• 该方法不会改变视频采集设备的使用状态。
• 该方法的调用是否生效受 JoinChannel 和 SetClientRole 方法的影响。

参数

mute	是否取消发布本地视频流。 true: 取消发布。 false: 发布。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • -5 (ERR_REFUSED): 调用被拒绝。

取消或恢复发布本地音频流。

自从

v3.4.5

该方法仅设置用户在 AgoraChannel 频道中的音频发布状态。

成功调用该方法后，远端会触发 OnRemoteAudioStateChangedHandler 回调。

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中 调用 MuteLocalAudioStream (false)， 否则方法会调用失败并返回 -5 (ERR_REFUSED)。

注解

• 该方法不会改变音频采集设备的使用状态。
• 该方法的调用是否生效受 JoinChannel 和 SetClientRole 方法的影响。

参数

mute	是否取消发布本地音频流。 true: 取消发布。 false: 发布。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • -5 (ERR_REFUSED): 调用被拒绝。