文档中心
互动直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon
文档中心  >  互动直播 (Legacy)  >  API 参考  >  Windows API Reference (C#)  >  IAgoraRtcChannel
IAgoraRtcChannel
Updated Time 2023/06/15 07:16

IAgoraRtcChannel

提供在频道中实现实时音视频功能的方法。

调用 CreateChannel 创建一个 IAgoraRtcChannel 对象。

AddPublishStreamUrl

增加旁路推流地址。 

public abstract int AddPublishStreamUrl(string url, bool transcodingEnabled);
弃用：
该方法已废弃。

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

注意：
  • 该方法需要在加入频道后调用。
  • 请确保已开通旁路推流的功能。详见进阶功能旁路推流 中的前提条件。
  • 只有直播场景中角色为主播的用户才能调用该方法。
  • 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
  • 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

参数

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

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • -2: 参数无效，一般是 URL 为空或是长度为 0 的字符串。
    • -7: 推流时未初始化引擎。

AdjustUserPlaybackSignalVolume

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

public abstract int AdjustUserPlaybackSignalVolume(uint uid, int volume);

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

注意：
  • 该方法需要在加入频道后调用。
  • 该方法调节的是本地播放的指定远端用户混音后的音量。

参数

uid
远端用户 ID。
volume
音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

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

ChannelId

获取当前频道的频道名。

public abstract string ChannelId();

返回值

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

CreateDataStream [1/2]

创建数据流。

public abstract int CreateDataStream(bool reliable, bool ordered);
弃用：
请改用 CreateDataStream [2/2]。

在 IAgoraRtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。

注意：
  • 该方法需要在加入频道后调用。
  • 不可将 reliable 设为 true 且将 ordered 设为 true。

参数

reliable
该数据流是否可靠：
  • true: 接收方 5 秒内会收到发送方所发送的数据，否则会收到 OnStreamMessageError 回调并获得相应报错信息。
  • false: 接收方不保证收到，就算数据丢失也不会报错。
ordered
该数据流是否有序：
  • true: 接收方会按照发送方发送的顺序收到数据包。
  • false: 接收方不保证按照发送方发送的顺序收到数据包。

返回值

  • 创建的数据流的 ID：方法调用成功。
  • < 0：方法调用失败。你可以参考错误码和警告码进行问题排查。

CreateDataStream [2/2]

创建数据流。

public abstract int CreateDataStream(DataStreamConfig config);

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

相比 CreateDataStream [1/2]，该方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。

参数

config
数据流设置。详见 DataStreamConfig。

返回值

  • 创建的数据流的 ID：方法调用成功。
  • < 0：方法调用失败。你可以参考错误码和警告码进行问题排查。

EnableEncryption

开启或关闭内置加密。 

public abstract int EnableEncryption(bool enabled, EncryptionConfig config);

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

同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

注意： 如果开启了内置加密，则不能使用旁路推流功能。

参数

enabled
是否开启内置加密：
  • true: 开启内置加密。
  • false: 关闭内置加密。
config
配置内置加密模式和密钥。详见 EncryptionConfig。

返回值

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

GetCallId

获取通话 ID。

public abstract string GetCallId();

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

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

返回值

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

GetConnectionState

获取当前网络连接状态。 

public abstract CONNECTION_STATE_TYPE GetConnectionState();

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

返回值

当前网络连接状态。详见 CONNECTION_STATE_TYPE。

JoinChannel

通过 UID 加入频道。

public abstract int JoinChannel(string token, string info, uint uid, ChannelMediaOptions options);

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

注意：
  • 该方法不支持相同的用户重复加入同一个频道。
  • 我们建议不同频道中使用不同的 UID。
  • 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。

参数

token

在服务端生成的用于鉴权的动态密钥。详见 使用 Token 鉴权 。

警告： 请确保用于生成 token 的 App ID、频道名和用户名和 Initialize 方法初始化引擎时用的 App ID，以及该方法中设置的频道名和用户名是一致的。
info

预留参数。

uid
用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数，建议设置范围：1 到 21 到 232-1如果不指定（即设为 0），SDK 会自动分配一个，并在 OnJoinChannelSuccess 回调中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
options

频道媒体设置选项。详见 ChannelMediaOptions 。

返回值

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

JoinChannelWithUserAccount

通过 User Account 加入频道。

public abstract int JoinChannelWithUserAccount(string token, string userAccount, ChannelMediaOptions options);

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

注意：
  • 该方法不支持相同的用户重复加入同一个频道。
  • 我们建议不同频道中使用不同的 user account。
  • 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 user account 是不同的。

参数

token

在服务端生成的用于鉴权的动态密钥。详见 使用 Token 鉴权 。

警告： 请确保用于生成 token 的 App ID、频道名和用户名和 Initialize 方法初始化引擎时用的 App ID，以及该方法中设置的频道名和用户名是一致的。
userAccount
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
options

频道媒体设置选项。详见 ChannelMediaOptions 。

返回值

  • 0(ERR_OK) 方法调用成功。
  • < 0 方法调用失败。
    • -2(ERR_INVALID_ARGUMENT): 参数无效。
    • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
    • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
      • 已经创建了一个同名的 IAgoraRtcChannel 频道。
      • 已经通过 IAgoraRtcChannel 加入了一个频道，并在该 IAgoraRtcChannel 频道中发布了音视频流。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用该方法。请确认在调用 API 之前已经创建 IAgoraRtcEngine 对象并完成初始化。
    • -17(ERR_JOIN_CHANNEL_REJECTED): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IAgoraRtcEngine 频道， 当已经加入 IAgoraRtcEngine 频道的用户使用有效的频道名再次调用 IAgoraRtcEngine 类中的加入频道方法时，会返回此错误码。

LeaveChannel

离开频道。

public abstract int LeaveChannel();

离开频道，即挂断或退出通话。该方法会把会话相关的所有资源释放掉。该方法是异步操作，调用返回时并没有真正退出频道。

调用 JoinChannel 后，必须调用 LeaveChannel 结束通话，否则无法开始下一次通话。

不管当前是否在通话中，都可以调用 LeaveChannel，没有副作用。

成功调用该方法离开频道会触发以下回调：
  • 本地会触发 OnLeaveChannel 回调。
  • 通信场景下的用户和直播场景下的主播离开频道后，远端会触发 OnUserOffline 回调。
注意：
  • 如果你调用了 LeaveChannel 后立即调用 Dispose 方法，SDK 将无法触发 OnLeaveChannel 回调。
  • 如果你在旁路推流过程中调用了 LeaveChannel 方法，SDK 将自动调用 RemovePublishStreamUrl 方法。

返回值

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

MuteAllRemoteAudioStreams

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

public abstract int MuteAllRemoteAudioStreams(bool mute);

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

注意：
  • 该方法需要在加入频道后调用。

参数

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

返回值

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

MuteAllRemoteVideoStreams

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

public abstract int MuteAllRemoteVideoStreams(bool mute);

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

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

参数

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

返回值

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

MuteRemoteAudioStream

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

public abstract int MuteRemoteAudioStream(uint userId, bool mute);
注意：
  • 该方法需要在加入频道后调用。
  • 该方法的推荐设置详见《设置订阅状态》。

参数

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

返回值

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

MuteRemoteVideoStream

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

public abstract int MuteRemoteVideoStream(uint userId, bool mute);
注意：
  • 该方法需要在加入频道后调用。
  • 该方法的推荐设置详见《设置订阅状态》。

参数

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

返回值

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

Publish

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

public abstract int Publish();
该方法的调用需满足以下要求，否则 SDK 会返回 -5(ERR_REFUSED) :
  • 该方法仅支持将音视频流发布到当前 IAgoraRtcChannel 类所对应的频道。
  • 直播场景下，该方法仅适用于角色为主播的用户。你可以调用该 IAgoraRtcChannel 类下的 SetClientRole [2/2] 方法设置用户角色。
  • SDK 只支持用户同一时间在一个频道发布一路音视频流。详情请参考进阶功能《多频道管理》。

返回值

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

RegisterMediaMetadataObserver

注册媒体 metadata 观测器用于接收或发送 metadata。

public abstract int RegisterMediaMetadataObserver(METADATA_TYPE type);
注意：
  • 请在 JoinChannel 前调用该方法。
  • 该方法仅适用于直播场景。

参数

type
用户希望在观测器中使用的 METADATA 类型 。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。

返回值

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

RegisterPacketObserver

注册数据包观测器。

public abstract int RegisterPacketObserver(IPacketObserver observer);

该方法注册数据包观测器 (Packet Observer)。在声网 SDK 发送/接收（语音、视频）网络包时，会回调 IPacketObserver 定义的接口，App 可用此接口对数据做处理，例如加解密。

注意：
  • 处理后发送到网络的包大小不应超过 1200 字节，否则有可能发送失败。
  • 若需调用此方法，需确保接收端和发送端都调用此方法，否则会出现未定义行为（例如音频无声或视频黑屏）。
  • 若在直播场景下使用旁路推流、录制或储存，声网不建议调用此方法。
  • 你需要在加入频道前调用该方法。

参数

observer
IPacketObserver 。

返回值

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

Dispose

销毁 IAgoraRtcChannel 对象。

public abstract void Dispose();

返回值

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

RemovePublishStreamUrl

删除旁路推流地址。

public abstract int RemovePublishStreamUrl(string url);
弃用：
该方法已废弃。。

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

注意：
  • 调用该方法前，请确保已开通旁路推流的功能。
  • 只有直播场景中角色为主播的用户才能调用该方法。
  • 该方法需要在加入频道后调用。
  • 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

参数

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

返回值

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

RenewToken

更新 Token。

public abstract int RenewToken(string token);
该方法用于更新 Token。Token 会在一定时间后失效。以下两种情况下，app 应重新获取 Token，然后调用 renewToken 将新的 Token 传给 SDK，否则 SDK 无法和服务器建立连接：

参数

token
新的 Token。

SendMetadata

发送媒体附属信息。

public abstract int SendMetadata(Metadata metadata);

成功调用 RegisterMediaMetadataObserver 方法后，SDK 会触发 OnReadyToSendMetadata 回调，你可以调用该方法发送媒体附属信息。

如果成功发送了媒体附属信息，接收端会收到 OnMetadataReceived 回调。

参数

metadata
媒体附属信息。详见 Metadata。

返回值

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

SendStreamMessage

发送数据流。

public abstract int SendStreamMessage(int streamId, byte[] data);
该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：
  • 频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。
  • 每个客户端每秒最多能发送 6 KB 数据。
  • 频道内每人最多能同时有 5 个数据通道。

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

注意：
  • 请确保在调用该方法前，已调用 CreateDataStream [2/2] 创建了数据通道。
  • 直播场景下，该方法仅适用于主播用户。

参数

streamId
数据流 ID。可以通过 CreateDataStream [2/2] 获取。
data
待发送的数据。

返回值

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

InitEventHandler

设置 IAgoraRtcChannel 对象的事件句柄。

public abstract void InitEventHandler(IAgoraRtcChannelEventHandler channelEventHandler);

你可以通过设置的事件句柄监听本 IAgoraRtcChannel 对象对应频道的事件，并接收频道中用户视频信息等。

参数

channelEventHandler
IAgoraRtcChannel 对象的事件句柄。详见 IAgoraRtcChannelEventHandler。

返回值

  • 0(ERR_OK) 方法调用成功。
  • < 0 方法调用失败。

SetClientRole [1/2]

设置用户角色。

public abstract int SetClientRole(CLIENT_ROLE_TYPE role);

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

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：
注意： 该方法仅适用于直播场景。

参数

role

用户角色。详见 CLIENT_ROLE_TYPE。

返回值

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

SetClientRole [2/2]

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

public abstract int SetClientRole(CLIENT_ROLE_TYPE role, ClientRoleOptions options);

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

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：
注意：
  • 该方法仅在频道场景为直播（SetChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING）时生效。

参数

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

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • -1: 一般性的错误（未明确归类）。
    • -2: 参数无效。
    • -5: 调用被拒绝。
    • -7: SDK 尚未初始化。

SetDefaultMuteAllRemoteAudioStreams

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

public abstract int SetDefaultMuteAllRemoteAudioStreams(bool mute);

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

注意：

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

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

参数

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

返回值

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

SetDefaultMuteAllRemoteVideoStreams

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

public abstract int SetDefaultMuteAllRemoteVideoStreams(bool mute);

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

注意：

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

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

参数

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

返回值

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

SetAVSyncSource

设置发流端音画同步。 

public abstract int SetAVSyncSource(string channelId, uint uid);

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

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

参数

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

SetEncryptionMode

启用内置的加密方案。

public abstract int SetEncryptionMode(string encryptionMode);
弃用：
该方法自 v3.1.0 起废弃。请改用 EnableEncryption 方法。

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

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

参数

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

返回值

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

SetEncryptionSecret

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

public abstract int SetEncryptionSecret(string secret);
弃用：
请改用 EnableEncryption 方法。

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

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

参数

secret
加密密码。

返回值

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

SetMaxMetadataSize

设置媒体附属信息的最大大小。

public abstract int SetMaxMetadataSize(int size);

调用 RegisterMediaMetadataObserver 后，你可以调用本方法来设置媒体附属信息的最大大小。

参数

size
媒体附属信息的最大大小。

返回值

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

SetLiveTranscoding

设置直播推流转码。

public abstract int SetLiveTranscoding(LiveTranscoding transcoding);
弃用：
该方法已废弃。

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

注意：
  • 只有直播场景中角色为主播的用户才能调用该方法。
  • 请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
  • 首次调用该方法更新转码设置时，不会触发 OnTranscodingUpdated 回调。
  • 该方法需要在加入频道后调用。
  • 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

参数

transcoding

推流转码设置。详见 LiveTranscoding。

返回

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

SetRemoteDefaultVideoStreamType

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

public abstract int SetRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType);

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

正常情况下，用户默认接收大流。如需默认接收所有用户的视频小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

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

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

参数

streamType

默认订阅的视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回值

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

SetRemoteRenderMode

更新远端视图显示模式。

public abstract int SetRemoteRenderMode(uint userId, RENDER_MODE_TYPE renderMode,
            VIDEO_MIRROR_MODE_TYPE mirrorMode);
自从
v3.0.0

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

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

参数

userId

远端用户 ID。

renderMode

远端用户视图的渲染模式，详见 RENDER_MODE_TYPE。

mirrorMode

远端用户视图的镜像模式，详见 VIDEO_MIRROR_MODE_TYPE。

返回值

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

SetRemoteUserPriority

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

public abstract int SetRemoteUserPriority(uint uid, PRIORITY_TYPE userPriority);

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

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

参数

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

返回值

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

SetRemoteVideoStreamType

设置订阅的视频流类型。 

public abstract int SetRemoteVideoStreamType(uint userId, REMOTE_VIDEO_STREAM_TYPE streamType);

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

正常情况下，用户默认接收大流。如需接收小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

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

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

参数

userId
用户 ID。
streamType

视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回值

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

SetRemoteVoicePosition

设置远端用户声音的 2D 位置，即水平面位置。

public abstract int SetRemoteVoicePosition(uint uid, double pan, double gain);

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

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

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

参数

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

返回值

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

StartChannelMediaRelay

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

public abstract int StartChannelMediaRelay(ChannelMediaRelayConfiguration configuration);
成功调用该方法后，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)， 则表示跨频道媒体流转发出现异常。
注意：
  • 请在成功加入频道后调用该方法。
  • 在直播场景中，只有角色为主播的用户才能调用该方法。
  • 功调用该方法后，若你想再次调用该方法，必须先调用 StopChannelMediaRelay 方法退出当前的转发状态。
  • 跨频道媒体流转发功能需要联系技术支持开通。
  • 该功能不支持 String 型 UID。

参数

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

返回值

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

StartRtmpStreamWithTranscoding

开始旁路推流并设置转码属性。 

public abstract int StartRtmpStreamWithTranscoding(string url, LiveTranscoding transcoding);

调用该方法，你可以向指定的 CDN 推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流，如果你需要向多个地址转码推流，则需多次调用该方法。

调用该方法后，SDK 会在本地触发 OnRtmpStreamingStateChanged 回调，报告推流的状态。

注意：
  • 请确保已开通旁路推流服务，详见进阶功能旁路推流中的前提条件。
  • 请在加入频道后调用该方法。
  • 只有直播场景下的主播才能调用该方法。
  • 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 StopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。

参数

url
旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
transcoding

旁路推流的转码属性，详见 LiveTranscoding 类。

StartRtmpStreamWithoutTranscoding

开始非转码推流。 

public abstract int StartRtmpStreamWithoutTranscoding(string url);

调用该方法，你可以向指定的 CDN 推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流，如果你需要向多个地址推流，则需多次调用该方法。

调用该方法后，SDK 会在本地触发 OnRtmpStreamingStateChanged 回调，报告推流的状态。

注意：
  • 请确保已开通旁路推流服务，详见进阶功能旁路推流中的前提条件。
  • 请在加入频道后调用该方法。
  • 只有直播场景下的主播才能调用该方法。
  • 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 StopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。

参数

url
旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

StopRtmpStream

结束旁路推流。 

public abstract int StopRtmpStream(string url);

调用该方法，你可以结束指定的 CDN 推流地址上的直播。该方法每次只能结束一个推流地址上的直播，如果你需要结束多个推流地址的直播，则需多次调用该方法。

调用该方法后，SDK 会在本地触发 OnRtmpStreamingStateChanged 回调，报告推流的状态。

参数

url
旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

StopChannelMediaRelay

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

public abstract int StopChannelMediaRelay();

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

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

返回值

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

UpdateRtmpTranscoding

更新旁路推流转码属性。 

public abstract int UpdateRtmpTranscoding(LiveTranscoding transcoding);

开启转码推流后，你可以根据场景需求，动态更新转码属性。转码属性更新后，SDK 会触发 OnTranscodingUpdated 回调。

参数

transcoding

旁路推流的转码属性，详见 LiveTranscoding 类。

Unpublish

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

public abstract int Unpublish();

如果当前 IChannel 频道没有发布音视频流，调用该方法后 SDK 会返回 -5(ERR_REFUSED)。

返回值

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

UnRegisterMediaMetadataObserver

取消注册媒体附属信息观测器。

public abstract int UnRegisterMediaMetadataObserver(METADATA_TYPE type);

参数

type
观测器使用的 metadata 类型。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。

返回值

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

UpdateChannelMediaRelay

更新媒体流转发的频道。

public abstract int UpdateChannelMediaRelay(ChannelMediaRelayConfiguration configuration);

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

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

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

参数

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

返回值

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