Java API Reference for Android

设置频道事件句柄。

设置后，你可以通过 IRtcChannelEventHandler 回调监听对应频道内的事件、获取频道数据。

参数

eventHandler

RtcChannel 对象的事件回调：IRtcChannelEventHandler.

获取频道事件句柄。

返回

• 方法调用成功，则返回 IRtcChannelEventHandler 对象。
• 方法调用失败，则返回 null。

销毁当前的 RtcChannel 对象。

返回

• 0：方法调用成功。
• < 0：方法调用失败；
  • ERR_NOT_INITIALIZED(-7)：调用该方法前尚未初始化 RtcChannel 对象。

获取当前 RtcChannel 对象的 channel ID。

返回

• 方法调用成功，则返回当前 RtcChannel 对象的 channel ID。
• 方法调用失败，则返回空字符串 ""。

获取当前的通话 ID. 该方法需要在加入频道后调用。

返回

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

获取网络连接状态。

返回

当前的网络连接状态

• CONNECTION_STATE_DISCONNECTED(1)：网络连接断开。
• CONNECTION_STATE_CONNECTING(2)：建立网络连接中。
• CONNECTION_STATE_CONNECTED(3)：网络已连接。
• CONNECTION_STATE_RECONNECTING(4)：重新建立网络连接中。
• CONNECTION_STATE_FAILED(5)：网络连接失败。

开启/关闭远端视频超分辨率。(beta 功能）

弃用:

该方法自 v3.7.1 废弃，请改用 enableRemoteSuperResolution[2/2] 方法。

自从

v3.5.1

该功能可以有效地提升本地用户看到的远端视频画面的分辨率。远端用户视频的原始分辨率为 a × b，开启该功能后，本地设备会以 2a × 2b 的分辨率显示该远端视频。

调用该方法后，SDK 会触发 onUserSuperResolutionEnabled 回调报告超分辨率是否成功开启。

警告

超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗，只可以对一个远端用户开启超分辨率，并且远端用户视频的原始分辨率不能超过 640 × 360。

注解

• 调用该方法前，请确保你已经将 libagora_super_resolution_extension.so 动态库集成到项目中。
• 该方法对用户设备具有一定要求，声网推荐你使用如下或更好的设备：
  • VIVO：V1821A，NEX S，1914A，1916A，1962A，1824BA，X60，X60 Pro
  • OPPO：PCCM00，Find X3
  • 一加：A6000
  • 小米：Mi 8，Mi 9，Mi 10，Mi 11，MIX3，Redmi K20 Pro
  • 三星：SM-G9600，SM-G9650，SM-N9600，SM-G9708，SM-G960U，SM-G9750，S20，S21
  • 华为：SEA-AL00，ELE-AL00，VOG-AL00，YAL-AL10，HMA-AL00，EVR-AN00，nova 4，nova 5 Pro，nova 6 5G，nova 7 5G，Mate 30，Mate 30 Pro，Mate 40， Mate 40 Pro，P40，P40 Pro，华为平板 M6，MatePad 10.8

参数

uid	远端用户 ID。
enable	是否对远端视频开启超分辨率： true: 开启。 false: 关闭。

返回

• 0：方法调用成功。
• < 0：方法调用失败。
  • -157 (ERR_MODULE_NOT_FOUND)：未集成超分辨率动态库。

开启/关闭远端视频超分辨率。（beta 功能）

自从

v3.7.1

该功能可以有效地提升用户看到的远端视频画面的分辨率，即对接收到的某个远端用户的视频宽和高均扩大为 2 倍像素。

调用该方法后，SDK 会触发 onUserSuperResolutionEnabled 回调报告超分辨率是否成功开启。

注解

调用该方法前，请确保你已经将 libagora_super_resolution_extension.so 动态库集成到项目中。

警告

超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗，该功能有如下使用限制：

• 只可以对一个远端用户开启超分辨率。
• 远端用户视频的原始分辨率不能超过 640 × 360。
• 该功能不支持在部分低端机型上开启。

参数

enable	是否对远端视频开启超级分辨率： true: 开启。 false: 关闭。
mode	超分辨率的模式: SR_MODE_MANUAL(0): 该模式表示对你指定的远端用户进行超分辨率处理。 SR_MODE_AUTO(1): 该模式表示对频道内最大的渲染窗口所对应的远端用户进行超分辨率处理。
uid	远端用户 ID。该参数仅在 mode 为 SR_MODE_MANUAL(0) 时生效。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -157 (ERR_MODULE_NOT_FOUND): 尚未集成超分辨率动态库。

使用 uid 加入频道。

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

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

注解

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

参数

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

返回

• 0：方法调用成功。
• < 0：方法调用失败。
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)
  • ERR_REFUSED(-5)
  • ERR_NOT_INITIALIZED(-7)
  • ERR_JOIN_CHANNEL_REJECTED(-17)：加入频道被拒绝。由于 SDK 不支持用户重复加入同一个 RtcChannel 频道， 当已经加入某个 RtcChannel 频道的用户再次调用该 RtcChannel 对象的加入频道方法时，会返回此错误码。

使用 user account 加入频道.

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

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

注解

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

参数

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

返回

• 0：方法调用成功。
• < 0：方法调用失败。
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)
  • ERR_REFUSED(-5)
  • ERR_JOIN_CHANNEL_REJECTED(-17)：加入频道被拒绝。由于 SDK 不支持用户重复加入同一个 RtcChannel 频道， 当已经加入某个 RtcChannel 频道的用户再次调用该 RtcChannel 对象的加入频道方法时，会返回此错误码。

离开当前频道。

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

• 本地：onLeaveChannel.
• 远端：通信场景下的用户和直播场景下的主播离开频道后，触发 onUserOffline。

返回

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

设置发流端音画同步。

自从

v3.6.0

同一用户可能使用两个设备分别发送音频流和视频流，为保证接收端听到和看到的音频和视频的时间同步性， 你可以在视频发送端调用该方法，并传入音频发送端的频道名、用户 ID。SDK 会以发送的音频流的时间戳为基准进行自动调节 发送的视频流，以保证即使在两个发送端的上行网络情况不一致（如分别使用 Wi-Fi 和 4G 网络）的情况下， 也能让接收到的音视频具有时间同步性。

注解

声网推荐你在加入频道前调用该方法。

参数

channelName	标识音频发送端所在频道的频道名。
uid	音频发送端的用户 ID。

返回

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

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

自从

v3.4.5

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

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

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

注解

• 该方法不会改变视频采集设备的使用状态。
• 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。

参数

muted

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

返回

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

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

自从

v3.4.5

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

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

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

注解

• 该方法不会改变视频采集设备的使用状态。
• 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。

参数

muted

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

返回

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

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

弃用:

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

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

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

返回

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

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

弃用:

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

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

返回

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

更新 Token。

在如下情况下，SDK 判定当前的 Token 已过期：

• SDK 触发 onTokenPrivilegeWillExpire 回调，或者
• SDK 在 onConnectionStateChanged 回调中报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 错误，

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

参数

token

新的 Token。

返回

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

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

弃用:

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

如果需要启用加密，请在加入频道前调用该方法启用内置加密功能，并设置加密密码。

同一频道内的所有用户应设置相同的密码。 当用户离开频道时，该频道的密码会自动清除。如果未指定密码或将密码设置为空，则无法激活加密功能。

注解

• 为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
• 请勿在转码推流场景中使用该方法。

参数

secret

加密密码。

返回

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

设置内置的加密方案。

弃用:

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

SDK 支持内置加密功能，默认使用 AES-128-XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。 同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别，请参考 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：方法调用失败。

开启或关闭内置加密。

自从

v3.1.0。

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

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

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

警告

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

注解

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

参数

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

返回

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

注册媒体 Metadata 观测器。

你需要在该方法中实现一个 IMetadataObserver 类，并指定 Metadata 的数据类型。成功调用该方法后，SDK 会触发 getMaxMetadataSize 回调。

该接口通过在直播的视频帧中同步添加 Metadata，实现发送商品链接、分发优惠券、发送答题等功能，构建更为丰富的直播互动方式。

注解

请在调用 joinChannel 加入频道前调用该方法。

参数

observer	IMetadataObserver 类。
type	Metadata 的数据类型。目前 SDK 仅支持视频类的 Metadata，即 VIDEO_METADATA(0)。 UNKNOWN_METADATA(-1)：Metadata 类型未知。 VIDEO_METADATA(0)：Metadata 类型为视频

返回

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

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

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

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

• 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
• 本地触发 onClientRoleChanged 或 onClientRoleChangeFailed。
• 远端触发 onUserJoined 或 onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)。

注解

该方法仅适用于直播场景（setChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING）。

参数

role	直播场景里的用户角色: CLIENT_ROLE_BROADCASTER(1)：主播可以发流也可以收流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(false) 和 muteLocalVideoStream(false)。 CLIENT_ROLE_AUDIENCE(2)：观众只能收流不能发流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(true) 和 muteLocalVideoStream(true)。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INVALID_ARGUMENT): 参数无效。
  • -5 (ERR_REFUSED): 调用被拒绝。在多频道场景中，如果你已在一个频道中进行如下设置，则用户在另一个频道内切换角色为主播时会返回该错误码：
    • 调用带 options 参数的 joinChannel，并使用默认设置 publishLocalAudio = true 或 publishLocalVideo = true。
    • 调用 setClientRole，并设置用户角色为主播。
    • 调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

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

自从

3.2.0

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

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

• 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
• 本地触发 onClientRoleChanged 或 onClientRoleChangeFailed。
• 远端触发 onUserJoined 或 onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)。

注解

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

示例代码

参数

role	直播场景里的用户角色: CLIENT_ROLE_BROADCASTER(1)：主播可以发流也可以收流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(false) 和 muteLocalVideoStream(false)。 CLIENT_ROLE_AUDIENCE(2)：观众只能收流不能发流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(true) 和 muteLocalVideoStream(true)。
options	用户具体设置，包含用户级别，详见 ClientRoleOptions。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INVALID_ARGUMENT): 参数无效。
  • -5 (ERR_REFUSED): 调用被拒绝。在多频道场景中，如果你已在一个频道中进行如下设置，则用户在另一个频道内切换角色为主播时会返回该错误码：
    • 调用带 options 参数的 joinChannel，并使用默认设置 publishLocalAudio = true 或 publishLocalVideo = true。
    • 调用 setClientRole，并设置用户角色为主播。
    • 调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

设置用户媒体流优先级。

如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。 弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注解

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

参数

uid	远端用户的 ID。
userPriority	远端用户的需求优先级： USER_PRIORITY_HIGH(50)：用户需求优先级为高。 USER_PRIORITY_NORMAL(100)：（默认）用户需求优先级为正常。

返回

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

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

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

注解

• 该方法需要在加入频道后调用。
• 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
• 为获得最佳听觉体验，我们建议用户佩戴耳机。

参数

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

返回

• 0：方法调用成功。
• -1：方法调用失败

更新远端视图显示模式。

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

注解

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

参数

uid	远端用户 ID。
renderMode	远端用户视图的渲染模式： RENDER_MODE_HIDDEN(1)：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。 RENDER_MODE_FIT(2)：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。 RENDER_MODE_ADAPTIVE(3)：已废弃，不再推荐使用。
mirrorMode	远端用户视图的镜像模式： VIDEO_MIRROR_MODE_AUTO(0)：(默认) 由 SDK 决定镜像模式。SDK 默认关闭远端用户的镜像模式。 VIDEO_MIRROR_MODE_ENABLED(1)：开启镜像模式。 VIDEO_MIRROR_MODE_DISABLED(2)：关闭镜像模式。

返回

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

设置是否默认接收音频流。

弃用:

该方法自 v3.3.0 起废弃。

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

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

注解

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

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

参数

muted

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

返回

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

设置是否默认接收视频流。

弃用:

该方法自 v3.3.0 起废弃。

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

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

注解

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

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

参数

muted

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

返回

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

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

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

注解

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

参数

muted

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

返回

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

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

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

注解

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

参数

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

返回

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

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

注解

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

参数

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

返回

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

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

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

注解

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

参数

muted

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

返回

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

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

注解

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

参数

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

返回

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

设置订阅的视频流类型。

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

正常情况下，用户默认接收大流。如需节约带宽和计算资源，则可以调用该方法动态调整对应远端视频流的大小。SDK 会根据该方法中的设置，切换大小流。

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

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

该方法在加入频道前后都能调用。如果既调用了 setRemoteVideoStreamType，也调用了 setRemoteDefaultVideoStreamType，则 SDK 以 setRemoteVideoStreamType 中的设置为准。

参数

uid	远端用户的 ID。
streamType	设置视频流大小类型： VIDEO_STREAM_HIGH(0)：视频大流，即高分辨率、高码率视频流。 VIDEO_STREAM_LOW(1)：视频小流，即低分辨率、低码率视频流。

返回

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

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

注解

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

参数

streamType

设置视频流大小类型： VIDEO_STREAM_HIGH(0)：视频大流，即高分辨率、高码率视频流 VIDEO_STREAM_LOW(1)：视频小流，即低分辨率、低码率视频流

返回

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

创建数据流。

弃用:

该方法从 v3.3.0 起废弃，请改用 createDataStream[2/2]。

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

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

注解

• 不可将 reliable 设为 true 且将 ordered 设为 false。
• 创建数据流后，如果你离开频道，SDK 会销毁数据流。

参数

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

返回

• 创建数据流成功则返回数据流 ID
• < 0：创建数据流失败。如果返回的错误码是负数，对应错误代码和警告代码里的正整数。

创建数据流。

自从

v3.3.0.

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

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

注解

创建数据流后，如果你离开频道，SDK 会销毁数据流。

参数

config

数据流设置：DataStreamConfig.

返回

• 创建数据流成功则返回数据流 ID。
• < 0: 创建数据流失败。

发送数据流。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：

• 频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。
• 每个客户端每秒最多能发送 6 KB 数据。
• 频道内每人最多能同时有 5 个数据通道。

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

参数

streamId	createDataStream 方法返回的数据流 ID。
message	待发送的数据，格式为 byte[]。

返回

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

增加旁路推流地址。

弃用:

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

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

参数

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

注解

• 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《旁路推流》中的前提条件。
• 请确保在成功加入频道后才能调用该接口。
• 该方法仅适用直播场景。
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。

返回

• 0：方法调用成功。
• < 0：方法调用失败。
  • ERR_INVALID_ARGUMENT(2)：参数无效，一般是 URL 为空或是长度为 0 的字符串。
  • ERR_NOT_INITIALIZED(7)：推流时未初始化 RtcChannel。

删除旁路推流地址。

弃用:

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

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

注解

• 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《旁路推流》中的前提条件。
• 该方法只适用于直播场景。
• 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

参数

url	待删除的推流地址，格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。

返回

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

设置直播转码。

弃用:

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

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码参数 LiveTranscoding 时，SDK 会触发 onTranscodingUpdated 回调。

首次调用该方法设置转码参数时，不会触发 onTranscodingUpdated 回调。

注解

• 请确保已开通旁路推流的功能，详见进阶功能《旁路推流》中的前提条件。
• 该方法仅适用于直播场景下的主播用户。
• 该方法需要在加入频道后调用。
• 请确保先调用过该方法，再调用 addPublishStreamUrl。

参数

transcoding

旁路推流布局相关设置：LiveTranscoding。

返回

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

开始跨频道媒体流转发。

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

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

注解

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

参数

channelMediaRelayConfiguration

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

返回

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

停止跨频道媒体流转发。

一旦停止，主播会退出所有目标频道。

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

注解

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

返回

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

更新媒体流转发的频道。

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

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

注解

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

参数

channelMediaRelayConfiguration

跨频道媒体流转发参数配置：ChannelMediaRelayConfiguration.

返回

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

暂停向所有目标频道转发媒体流。

自从

v3.5.1

开始跨频道转发媒体流后，如果你需要暂停向所有频道转发媒体流，可以调用该方法； 暂停后，如果要恢复跨频道媒体流转发，可以调用 resumeAllChannelMediaRelay 方法。

成功调用该方法后，SDK 会触发 onChannelMediaRelayStateChanged 回调，并在回调中报告是否成功暂停媒体流转发。

注解

该方法需要在 startChannelMediaRelay 后调用。

返回

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

恢复向所有目标频道转发媒体流。

自从

v3.5.1

调用 pauseAllChannelMediaRelay 方法后，如果你需要恢复向所有目标频道转发媒体流，可以调用该方法。

成功调用该方法后，SDK 会触发 onChannelMediaRelayEvent 回调，并在回调中报告是否成功恢复媒体流转发。

注解

该方法需要在 pauseAllChannelMediaRelay 后调用。

返回

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

自定义 RtcChannel 对象的远端视频渲染器。

自从

3.0.1

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

参数

uid	远端用户的 ID。
render	自定义的远端视频渲染器。详见 IVideoSink。

返回

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