Unity SDK API 参考

查询 SDK 版本号。

返回

当前的 SDK 版本号，格式为字符串，如 2.9.1。

设置频道场景。

该方法用于设置频道场景。声网会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。

注解

• 为保证实时音视频质量，我们建议相同频道内的用户使用同一种频道场景。
• 如果想要切换场景，则需要先调用 Destroy 销毁当前引擎，然后重新调用 GetEngine 初始化引擎后再调用该方法切换频道场景。
• 该方法必须在 JoinChannelByKey 前调用和进行设置，进入频道后无法再设置。
• 声网 SDK 不支持 texture 编码，只支持原始音视频数据。
• 不同的频道场景下，SDK 的默认音频路由和默认视频编码码率是不同的，详见 SetDefaultAudioRouteToSpeakerphone 和 SetVideoEncoderConfiguration 方法中的说明。

参数

profile

频道属性: CHANNEL_PROFILE。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2 (ERR_INVALID_ARGUMENT): 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

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

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

• 调用 MuteLocalAudioStream 和 MuteLocalVideoStream 修改发布状态。
• 本地触发 OnClientRoleChangedHandler 或 OnClientRoleChangeFailedHandler。
• 远端触发 OnUserJoinedHandler 或 OnUserOfflineHandler(BECOME_AUDIENCE)。

注解

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

参数

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

返回

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

设置日志输出等级。

弃用:

该方法从 v3.3.1 起废弃，请改用 GetEngine 中的 logConfig。

设置声网 RTC SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。

例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

参见

SetLogFileSize

SetLogFile

参数

filter

设置过滤等级: LOG_FILTER.

返回

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

设置声网 SDK 输出的日志文件。

弃用:

该方法从 v3.3.1 起废弃，请改用 GetEngine 中的 logConfig。

默认情况下，SDK 会生成 agorasdk.log、agorasdk_1.log、agorasdk_2.log、agorasdk_3.log、agorasdk_4.log 这 5 个日志文件。 每个文件的默认大小为 1024 KB。日志文件为 UTF-8 编码。最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后，SDK 会从 1-4 中删除修改时间最早的一个文件， 然后将 agorasdk.log 重命名为该文件，并建立新的 agorasdk.log 写入最新的日志。

注解

如需调用本方法，请在调用 GetEngine 方法初始化 IRtcEngine 对象后立即调用，否则可能造成输出日志不完整。

参数

filePath

日志文件的完整路径。请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。

参见

SetLogFileSize

SetLogFilter

返回

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

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 LeaveChannel 退出当前通话，才能进入下一个频道。

成功调用该方加入频道后，本地会触发 OnJoinChannelSuccessHandler 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 OnUserJoinedHandler 回调。 在网络状况不理想的情况下，客户端可能会与 声网的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 OnReJoinChannelSuccessHandler 回调。

警告

请务必确保用于生成 Token 的 App ID 和 GetEngine 方法初始化引擎时用的是同一个 App ID，否则会造成旁路推流失败。

注解

• 频道内每个用户的用户 ID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 uid。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 uid 是不同的。
• 用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 Mute 方法实现。

参数

channelName	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a~z； 26 个大写英文字母 A~Z； 10个数字 0~9； 空格； "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
info	(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。
uid	(非必选项) 用户ID，32位无符号整数。建议设置范围：1到 232-1，并保证唯一性。如果不指定（即设为0），SDK 会自动分配一个，并在 OnJoinChannelSuccessHandler 回调中返回，app 层必须记住该返回值并维护，SDK不对该返回值进行维护。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
  • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
    • 已经创建了一个同名的 AgoraChannel 频道。
    • 已经通过 AgoraChannel 加入了一个频道，并在该 AgoraChannel 频道中发布了音视频流。

使用 Token 加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 LeaveChannel 退出当前通话，才能进入下一个频道。

成功调用该方加入频道后，本地会触发 OnJoinChannelSuccessHandler 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 OnUserJoinedHandler 回调。 在网络状况不理想的情况下，客户端可能会与声网的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 OnReJoinChannelSuccessHandler 回调。

警告

请务必确保用于生成 Token 的 App ID 和 GetEngine 方法初始化引擎时用的是同一个 App ID，否则会造成旁路推流失败。

注解

• 频道内每个用户的用户 ID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 uid。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 uid 是不同的。
• 用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 Mute 方法实现。

参数

channelKey	动态秘钥。 安全要求不高: 将值设为 NULL。 安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 Token。
channelName	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a~z； 26 个大写英文字母 A~Z； 10个数字 0~9； 空格； "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
info	(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。
uid	(非必选项) 用户ID，32位无符号整数。建议设置范围：1到 232-1，并保证唯一性。如果不指定（即设为0），SDK 会自动分配一个，并在 OnJoinChannelSuccessHandler 回调中返回，app 层必须记住该返回值并维护，SDK不对该返回值进行维护。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
  • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
    • 已经创建了一个同名的 AgoraChannel 频道。
    • 已经通过 AgoraChannel 加入了一个频道，并在该 AgoraChannel 频道中发布了音视频流。

更新 Token。

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

• 发生 OnTokenPrivilegeWillExpireHandler 回调时，或发生
• OnConnectionStateChangedHandler 回调报告 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 尚未初始化。

离开频道。

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

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

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

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

注解

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

返回

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

通过 JSON 配置 SDK 提供技术预览或特别定制功能。

参数

parameters

JSON 格式的字符串。

返回

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

获取当前通话 ID。

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

注解

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

返回

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

给通话评分。

注解

该方法需要在离开频道后调用。

参数

callId	通话 GetCallId 函数获取的通话 ID。
rating	给通话的评分，最低 1 分，最高 5 分。如超过这个范围，SDK 会返回 ERR_INVALID_ARGUMENT(2) 错误。
desc	(非必选项) 给通话的描述，可选，长度应小于 800 字节。

返回

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

投诉通话质量。

注解

该方法需要在离开频道后调用。

参数

callId	通话 GetCallId 函数获取的通话 ID。
desc	(非必选项) 给通话的描述，可选，长度应小于 800 字节。

返回

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

启用音频模块。

启用音频模块（默认为开启状态）。

注解

• 该方法设置音频模块为启用状态，在频道内和频道外均可调用。在 LeaveChannel 后仍然有效。
• 该方法开启整个音频模块，响应时间较慢，因此声网建议使用如下方法来控制音频模块：
  • EnableLocalAudio: 是否启动麦克风采集并创建本地音频流。
  • MuteLocalAudioStream: 是否发布本地音频流。
  • MuteRemoteAudioStream: 是否接收并播放远端音频流。
  • MuteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。

返回

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

关闭音频模块。

注解

• 该方法设置内部引擎为禁用状态，在频道内和频道外均可调用。在 LeaveChannel 后仍然有效。
• 该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制音频模块：
  • EnableLocalAudio: 是否启动麦克风采集并创建本地音频流。
  • MuteLocalAudioStream: 是否发布本地音频流。
  • MuteRemoteAudioStream: 是否接收并播放远端音频流。
  • MuteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。

返回

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

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

自 v3.4.5 起，该方法仅设置用户在 IRtcEngine 频道中的音频发布状态。

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

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

注解

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

参数

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

返回

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

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

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

注解

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

参数

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

返回

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

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

注解

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

参数

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

返回

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

启用/关闭扬声器播放。

该方法设置是否将语音路由设到扬声器（外放）。 你可以在 SetDefaultAudioRouteToSpeakerphone 方法中查看默认的语音路由。

在 Android 上，SetAudioProfile 中 scenario 及 SetChannelProfile 的设置 会影响 SetEnableSpeakerphone 的行为。SetEnableSpeakerphone 不生效的情况如下：

• 当 scenario 为 AUDIO_SCENARIO_GAME_STREAMING 时，所有用户都无法切换音频播放路由。
• 当 scenario 为 AUDIO_SCENARIO_DEFAULT 或 AUDIO_SCENARIO_SHOWROOM 时，直播场景中的观众无法切换音频播放路由，且当频道中只有一个主播时，该主播也无法切换音频播放路由。
• 当 scenario 为 AUDIO_SCENARIO_EDUCATION 时，直播场景中的观众无法切换音频播放路由。

注解

• 该方法仅适用于 Android 和 iOS 平台。
• 请确保在调用此方法前已调用过 JoinChannelByKey 方法。
• 调用该方法后，SDK 将返回 OnAudioRouteChangedHandler 回调提示状态已更改。

参数

speakerphone

设置是否切换语音路由到扬声器（外放）： true: 切换到外放。如果设备连接了耳机或蓝牙，则无法切换到外放。 false: 切换到听筒。如果设备连接了耳机，则语音路由走耳机。

返回

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

设置默认的语音路由

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，语音默认从听筒出声。

各频道场景下默认的语音路由：

• 语音通话：听筒。
• 视频通话：扬声器。如果有用户在频道中使用 DisableVideo、MuteLocalVideoStream 或 MuteAllRemoteVideoStreams 方法关闭视频，则语音路由会自动切换回听筒。
• 直播：扬声器。
• 游戏语音：扬声器。

注解

• 该方法仅适用于 Android 和 iOS 平台。
• 该方法只在纯音频场景下工作，在有视频的场景下不工作。
• 该方法需要在 JoinChannelByKey 前设置，否则不生效。如需在加入频道后更改默认语音路由，请调用 SetEnableSpeakerphone 方法。

参数

speakerphone

设置默认的语音路由。 true: 设置默认的语音路由。 false: （默认）从听筒出声。

返回

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

查询扬声器启用状态。

注解

• 该方法仅适用于 Android 和 iOS 平台。
• 该方法在加入频道前后都能调用。

返回

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

切换前置/后置摄像头

注解

• 该方法仅适用于 Android 和 iOS 平台。
• 该方法需要在相机启动（如通过调用 StartPreview 或 JoinChannelByKey 实现）后调用。

返回

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

设置视频编码配置。

弃用:

该方法自 v2.3 起废弃。请改用 SetVideoEncoderConfiguration 方法。

该方法设置视频编码属性（Profile）。每个属性对应一套视频参数，如分辨率、帧率、码率等。 当设备的摄像头不支持指定的分辨率时，声网 SDK 会自动选择一个合适的摄像头分辨率，但是编码分辨率仍然用 SetVideoProfile 指定的。

注解

• 如果用户加入频道后不需要重新设置视频编码属性，则声网建议在 EnableVideo 前调用该方法，可以加快首帧出图的时间。 -应在调用 JoinChannelByKey 或 StartPreview 前设置视频属性。
• 你可以直接通过视频属性 (profile) 来定义输出的视频是 Landscape（横屏）还是 Portrait（竖屏）模式，因此，声网建议你将参数 swapWidthAndHeight 设置为默认值 false。
• 该方法在加入频道前后都能调用。

参数

profile	视频属性。详见: VIDEO_PROFILE_TYPE.
swapWidthAndHeight	SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高： true: 交换宽和高。 false: 不交换宽和高（默认）

返回

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

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

自 v3.4.5 起，该方法仅设置用户在 IRtcEngine 频道中的视频发布状态。

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

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

注解

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

参数

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

返回

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

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

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

注解

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

参数

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

返回

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

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

注解

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

参数

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

返回

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

开关双流模式。

该方法设置单流（默认）或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

注解

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

参数

enabled

设置单流或双流模式。 true: 双流 false: 单流

返回

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

设置内置的加密模式。

弃用:

该方法自 v3.2.0 起废弃。请改用 EnableEncryption 方法。

声网 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: 方法调用失败。

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

弃用:

该方法自 v3.2.0 起废弃。请改用 EnableEncryption 方法。

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

注解

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

参数

secret

加密密码。

返回

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

创建数据流。

弃用:

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

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

注解

• 声网不支持你将 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 个数据通道。

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

注解

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

参数

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

返回

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

设置扬声器音量。

弃用:

该方法自 v2.3 起废弃。改用 AdjustRecordingSignalVolume 和 AdjustPlaybackSignalVolume 方法。

注解

该方法仅支持 macOS 平台。

参数

volume

扬声器音量，0 (音量最低) 到 255 (音量最高) 的整数。

返回

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

设置视频质量偏好选项。

弃用:

该方法自 v2.4 起废弃。

该方法仅适用于直播场景。在网络条件不好或者设备性能不足影响到直播体验的情况下，可以使用该方法设置是否要优先保障流畅度。

参数

preferFrameRateOverImageQuality

画质和流畅度里，是否优先保障流畅度： true: 画质和流畅度里，优先保证流畅度。 false: 画质和流畅度里，优先保证画质（默认）。

返回

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

开始语音通话回路测试。

弃用:

该方法自 v2.4 起废弃。

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。 在测试过程中，用户先说一段话，在 10 秒后，声音会回放出来。如果 10 秒后用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注解

• 调用 StartEchoTest 后必须调用 StopEchoTest 以结束测试，否则不能进行下一次回声测试，或者调用 JoinChannelByKey 进行通话。
• 直播场景下，只有主播用户才能调用该方法。如果用户由通信场景切换到直播场景，请务必调用 SetClientRole 方法将用户角色设置为主播后再调用该方法。

返回

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

开始语音通话回路测试。

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在设置的时间间隔后回放出来。如果用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注解

• 请在加入频道前调用该方法。
• 调用该方法后必须调用 StopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。
• 直播场景下，该方法仅能由用户角色为主播的用户调用。

参数

intervalInSeconds

返回语音通话回路测试结果的时间间隔，取值范围为 [2,10]，单位为秒，默认值为 10 秒。

返回

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

开始音视频通话回路测试。

自从

v3.6.1.1

加入频道前，为测试用户本地发流、收流是否正常，你可以调用该方法进行音视频通话回路测试，即测试系统的音视频设备和用户的上下行网络是否正常。

开始测试后，用户需发出声音或面对摄像头，音频或视频会在约 2 秒后播放出来。如果音频播放正常，则表示系统音频设备和用户上下行网络均正常； 如果视频播放正常，则表示系统视频设备和用户上下行网络均正常。

注解

• 请在加入频道前调用该方法。
• 调用该方法后，必须调用 StopEchoTest 结束测试，否则该用户无法进行下一次音视频通话回路测试，也无法加入频道。
• 直播场景下，该方法仅能由主播调用。

参数

config

音视频通话回路测试的配置。详见 EchoTestConfiguration 。

返回

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

停止语音通话回路测试。

返回

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

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后，SDK 会依次返回如下 2 个回调：

• OnLastmileQualityHandler: 视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
• OnLastmileProbeResultHandler: 视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。

该方法主要用于以下两种场景：

• 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
• 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

注解

• 该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要和 EnableLastmileTest 同时使用。
• 调用该方法后，在收到 OnLastmileQualityHandler 和 OnLastmileProbeResultHandler 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。
• 直播场景下，如果本地用户为主播，请勿在加入频道后调用该方法。

参数

lastmileProbeConfig

Last mile 网络探测配置，详见 LastmileProbeConfig 。

返回

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

停止通话前网络质量探测。

返回

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

添加本地视频水印。

弃用:

该方法自 v2.9.1 起废弃，请改用 AddVideoWatermark。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众，旁路推流观众，甚至采集设备都能看到或采集到该水印图片。 如果你仅仅希望在旁路直播推流中添加水印，请参考 SetLiveTranscoding 中描述的用法。

注解

• 在本地直播和旁路推流中，URL 的定义不同。本地直播中，URL 指本地直播视频上图片的本地绝对/相对路径；旁路推流中，URL 指旁路推流视频上图片的地址。
• 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致，SDK 会对 PNG 图片进行裁剪，以与设置相符。
• 声网当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

参数

rtcImage

待添加在本地直播推流中的水印图片：RtcImage 。

返回

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

添加本地视频水印。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众、旁路直播观众和采集设备都能看到或采集到该水印图片。声网当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

水印坐标和 SetVideoEncoderConfiguration 方法中的设置有依赖关系：

• 如果视频编码方向/ ORIENTATION_MODE 固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
• 如果视频编码方向/ ORIENTATION_MODE 固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
• 设置水印坐标时，水印的图像区域不能超出 SetVideoEncoderConfiguration 方法中设置的视频尺寸，否则超出部分将被裁剪。

注解

• 你需要在调用 EnableVideo 方法之后再调用本方法。
• 如果你只是在旁路直播（推流到CDN）中添加水印，你可以使用本方法或 SetLiveTranscoding 方法设置水印。
• 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。
• 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。
• 如果你已经使用 StartPreview 方法开启本地视频预览，那么本方法的 visibleInPreview 可设置水印在预览时是否可见。

参数

watermarkUrl	待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
watermarkOptions	待添加的水印图片的设置选项，详见 WatermarkOptions 。

返回

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

删除已添加的视频水印。

返回

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

设置订阅的视频流类型。

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

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

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

注解

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

参数

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

返回

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

设置采集与播放声音混音后的数据格式。

注解

SDK 会通过 samplesPerCall、sampleRate 和 AudioFrame 中的 channels 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate × channels)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 OnMixedAudioFrameHandler 回调。

参数

sampleRate	指定 OnMixedAudioFrameHandler 中返回数据的采样率，可设置为 8000，16000，32000，44100 或 48000。
samplesPerCall	指定 OnMixedAudioFrameHandler 中返回数据的采样点数，如转码推流应用中通常为 1024。

返回

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

设置音乐文件的播放位置。该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而非从头到尾播放整个文件。

注解

该方法需要在 StartAudioMixing 后调用。

参数

pos	整数。进度条位置，单位为毫秒。

返回

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

启用用户音量提示。

该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。启用该方法后，只要频道内有发流用户，SDK 会在加入频道后按设置的时间间隔触发 OnVolumeIndicationHandler 回调。

注解

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

参数

interval	指定音量提示的时间间隔： ≤ 0: 禁用音量提示功能。 > 0: 返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 OnVolumeIndicationHandler 回调。
smooth	平滑系数，指定音量提示的灵敏度。取值范围为 [0,10]，建议值为 3。数字越大，波动越灵敏；数字越小，波动越平滑。
report_vad	true: 开启本地人声检测功能。开启后，OnVolumeIndicationHandler 回调的 vad 参数会报告是否在本地检测到人声。 false: (Default) （默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，OnVolumeIndicationHandler 回调的 vad 参数不会报告是否在本地检测到人声。

返回

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

调节麦克风采集信号音量。

注解

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

参数

volume

麦克风采集信号音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回

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

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

注解

• 该方法调节的是本地播放的所有远端用户混音后的音量。
• 从 v2.3.2 开始，静音本地音频需同时调用 AdjustPlaybackSignalVolume 和 AdjustAudioMixingVolume 方法，并将 volume 参数设置为 0。
• 该方法在加入频道前后都能调用。

参数

volume

播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回

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

开始播放音乐文件。

弃用:

自v3.4.2 废弃，请改用 StartAudioMixing[2/2]。

指定本地或在线音频文件来和麦克风采集的音频流进行混音和替换。替换是指用音频文件替换采集设备采集的音频流。该方法可以选择是否让对方听到本地播放的音频并指定循环播放的次数。成功调用该方法后，本地会触发 OnAudioMixingStateChangedHandler(PLAYING) 回调。播放结束后，会收到 OnAudioMixingStateChangedHandler(STOPPED) 回调。

注解

• 请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
• 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR(701)。
• Android 设备上，如果 filePath 是 HTTP 格式的 URL，则需要先在项目 AndroidManifest.xml 文件的 <application> 标签中添加 android:usesCleartextTraffic="true"。

参数

filePath	指定需要混音的本地或在线音频文件的绝对路径。建议填写文件后缀名。如果无法确定文件后缀名，可不填。支持的音频格式包括：3GP、ASF、ADTS、AVI、MP3、MP4、MPEG-4、SAMI 和 WAVE。 详见：Supported Media Formats in Media Foundation。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
loopback	true: 只有本地用户可以听到混音的音频； false: 本地用户和远端用户都能听到混音的音频。
replace	true: 只推送指定的本地音频文件或者线上音频文件，不传输麦克风收录的音频。 false: 本地音频文件与来自麦克风的音频流混音。
cycle	循环播放次数： 正整数: 循环播放的次数； -1: 无限循环。

返回

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

开始播放音乐文件。

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后，本地 会触发 OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER) 回调。 播放结束后，本地会触发 OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED) 回调。

注解

• 该方法需要在加入频道后调用。如需多次调用 StartAudioMixing，请确保调用间隔大于 500 ms。
• 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 WARN_AUDIO_MIXING_OPEN_ERROR (701)。
• 在 Android 平台上调用该方法时，请注意如下：
  • 如需调用该方法，请确保使用 Android 4.2 或以上设备，且 API Level 不低于 16。
  • 如果播放的是在线音乐文件，声网建议不要使用重定向地址。重定向地址在某些机型上可能无法打开。
  • 如果 filePath 是 HTTP 格式的 URL，则需要先在项目 AndroidManifest.xml 文件的 <application> 标签中添加 android:usesCleartextTraffic="true"。
  • 如果在模拟器上调用该方法，则请确保音乐文件在 /sdcard/ 目录下，且格式为 MP3。

参数

filePath	音乐文件的绝对路径或 URL 地址，需精确到文件名及后缀。 例如：C:\music\audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Supported Media Formats in Media Foundation。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
loopback	是否只在本地播放音乐文件： true: 只在本地播放音乐文件，只有本地用户能听到音乐。 false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。
replace	是否用音乐文件替换麦克风采集的音频： true: 替换。用户只能听到音乐。 false: 不替换。用户可以听到音乐和麦克风采集的音频。
cycle	音乐文件的播放次数。 ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。 -1: 无限循环播放。
startPos	音乐文件的播放位置，单位为毫秒。

返回

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

停止播放音乐文件。

该方法停止播放音乐文件。请在频道内调用该方法。

返回

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

暂停播放音乐文件。

该方法暂停播放音乐文件。请在频道内调用该方法。

返回

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

恢复播放音乐文件。

该方法恢复混音，继续播放音乐文件。请在频道内调用该方法。

返回

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

调节音乐文件的播放音量。

该方法调节混音音乐文件在本端和远端的播放音量大小。

注解

• 该方法需要在 StartAudioMixing 后调用。
• 调用该方法不影响调用 PlayEffect 播放音效文件的音量。

参数

volume

音乐文件音量范围为 [0,100]。 0: 静音； 100: 原始音量。

返回

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

获取音乐文件总时长。

弃用:

自v3.4.2废弃，请改用 GetAudioMixingDuration[2/2]。

该方法获取音乐文件总时长，单位为毫秒。请在频道内调用该方法。

返回

• ≥ 0: 方法调用成功则返回音乐文件时长。
• < 0: 方法调用失败。

获取指定音乐文件总时长。

弃用:

自 v3.6.1.1 废弃，请改用 GetAudioFileInfo。

注解

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

参数

filePath

本地音乐文件的绝对路径，需精确到文件名及后缀。例如：C:\music\audio.mp4 。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Supported Media Formats in Media Foundation 。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。

返回

• ≥ 0: 方法调用成功，返回指定音乐文件总时长（毫秒）。
• < 0: 方法调用失败.

获取音乐文件的播放进度。

该方法获取当前音乐文件播放进度，单位为毫秒。请在频道内调用该方法。

返回

• ≥ 0: 方法调用成功则返回音乐文件播放进度。
• < 0: 方法调用失败。

开始客户端录音。

弃用:

自 v3.4.2 废弃，请改用新的 StartAudioRecording[3/3] 方法。

声网 RTC SDK 支持通话过程中在客户端进行录音。该方法录制频道内所有用户的音频，并生成一个包含所有用户声音的录音文件，录音文件格式可以为:

• .wav: 文件大，音质保真度高；
• .aac: 文件小，有一定的音质保真度损失。

请确保 app 里指定的目录存在且可写。该接口需在 JoinChannelByKey 之后调用。如果调用 LeaveChannel 时还在录音，录音会自动停止。

参数

filePath	录音文件的本地保存路径，由用户自行指定，需精确到文件名及格式，例如：/dir1/dir2/dir3/audio.aac。
quality	设置录音质量。详见 AUDIO_RECORDING_QUALITY_TYPE.

返回

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

开始客户端录音。

弃用:

自 v3.4.2 废弃。请改用 StartAudioRecording[3/3]。

声网 RTC SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为:

• .wav: 文件大，音质保真度较高。
• .aac: 文件小，音质保真度较低。

注解

• 请确保你在该方法中指定的路径存在并且可写。
• 该接口需在 JoinChannelByKey 之后调用。如果调用 LeaveChannel 时还在录音，录音会自动停止。
• 为保证录音效果，当 sampleRate 设为 441000 Hz 或 48000 Hz 时，建议将 quality 设为 AUDIO_RECORDING_QUALITY_MEDIUM(1) 或 AUDIO_RECORDING_QUALITY_HIGH(2)。

参数

filePath	录音文件在本地保存的绝对路径，由用户自行指定，需精确到文件名及格式，例如：/dir1/dir2/dir3/audio.aac。
sampleRate	录音采样率（Hz），可以设为以下值： 16000 32000（默认） 44100 48000
quality	录音音质。详见 AUDIO_RECORDING_QUALITY_TYPE 。

返回

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

停止客户端录音。

停止录音。该接口需要在 LeaveChannel 之前调用，不然会在调用 LeaveChannel 时自动停止。

返回

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

获取 AudioEffectManagerImpl 对象。

返回

AudioEffectManagerImpl 对象。

获取 AudioRecordingDeviceManager 对象。

返回

AudioRecordingDeviceManager 对象。