文档中心
互动直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

Electron SDK API Reference

概览 AgoraRtcEngine AgoraRtcEngine.on AgoraRtcChannel AgoraRtcChannel.on 警告码 错误码

Hierarchy

  • EventEmitter
    • AgoraRtcEngine

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

customRenderer

customRenderer: any

pauseRender

pauseRender: boolean

renderMode

renderMode: 1 | 2 | 3 | 4

rtcEngine

rtcEngine: NodeRtcEngine

streams

streams: Map<string, Map<string, IRenderer[]>>

Methods

_checkWebGL2

  • _checkWebGL2(): boolean

  • Returns boolean

_getChannelRenderers

  • _getChannelRenderers(channelId: string): Map<string, IRenderer[]>

  • Parameters

    • channelId: string

    Returns Map<string, IRenderer[]>

addPublishStreamUrl

  • addPublishStreamUrl(url: string, transcodingEnabled: boolean): number

  • 增加旁路推流地址。

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

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

    Parameters

    • url: string

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

    • transcodingEnabled: boolean

      设置是否转码：

      • true: 转码。转码是指在旁路推流时对音视频流进行转码处理后， 再推送到其他 RTMP 服务器。多适用于频道内有多个主播，需要进行混流、合图的场景。如果设为 true，需先调用 setLiveTranscoding 方法。
      • false: 不转码。

    Returns number

    • 0：方法调用成功
    • < 0：方法调用失败
      • ERR_INVALID_ARGUMENT (2): RTMP 流地址为空或者字符长度为 0。
      • ERR_NOT_INITIALIZED (7): 使用该功能之前没有初始化 AgoraRtcChannel。

addVideoRenderToHighFPS

  • addVideoRenderToHighFPS(uid: number): void

  • 将指定用户的视频流添加为高帧率流。添加为高帧率流后，你可以调用 setVideoRenderHighFPS 方法对视频流进行控制。

    Parameters

    • uid: number

      用户 ID

    Returns void

addVideoWatermark

  • since

    v3.0.0

    添加本地视频水印。

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

    水印坐标和 setVideoEncoderConfiguration 中的设置有依赖关系：

    • 如果视频编码方向固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
    • 如果视频编码方向固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
    • 设置水印坐标时，水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置 的视频尺寸，否则超出部分将被裁剪。
    note
    • 你需要在调用 enableVideo 后调用该方法。
    • 如果你只是在旁路直播（推流到CDN）中添加水印，你可以使用本方法或 setLiveTranscoding 设置水印。
    • 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。
    • 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。
    • 如果你已经使用 startPreview 开启本地视频预览，那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
    • 如果你已设置本地视频为镜像模式，那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像， 建议你不要对本地视频同时使用镜像和水印功能，请在应用层实现本地水印功能。

    Parameters

    • path: string

      待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。

    • options: WatermarkOptions

      待添加的水印图片的设置选项，详见 WatermarkOptions

    Returns number

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

adjustAudioMixingPlayoutVolume

  • adjustAudioMixingPlayoutVolume(volume: number): number

  • 调节音乐文件的本地播放音量。

    note

    请在频道内调用该方法。

    Parameters

    • volume: number

      音乐文件的本地播放音量，取值范围为 [0, 100]，默认值为 100，表示原始文件音量

    Returns number

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

adjustAudioMixingPublishVolume

  • adjustAudioMixingPublishVolume(volume: number): number

  • 调节音乐文件的远端播放音量。

    note

    请在频道内调用该方法。

    Parameters

    • volume: number

      音乐文件的远端播放音量，取值范围为 [0, 100]，默认值为 100，表示原始文件音量

    Returns number

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

adjustAudioMixingVolume

  • adjustAudioMixingVolume(volume: number): number

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

    note
    • 请在频道内调用该方法。
    • 调用该方法不影响调用 playEffect 播放音效文件的音量。

    Parameters

    • volume: number

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

    Returns number

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

adjustLoopbackRecordingSignalVolume

  • adjustLoopbackRecordingSignalVolume(volume: number): number

  • 调节声卡采集信号音量。

    since

    v3.4.2

    调用 enableLoopbackRecording 开启声卡采集后，你可以调用该方法调节声卡采集的信号音量。

    Parameters

    • volume: number

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

    Returns number

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

adjustLoopbackSignalVolume

  • adjustLoopbackSignalVolume(volume: number): number

  • Parameters

    • volume: number

    Returns number

adjustPlaybackSignalVolume

  • adjustPlaybackSignalVolume(volume: number): number

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

    note
    • 该方法调节的是本地播放的所有远端用户混音后的音量。
    • 静音本地音频需同时调用 adjustPlaybackSignalVolume 和 adjustAudioMixingPlayoutVolume 方法，并将 volume 设置为 0。
    • 该方法在加入频道前后都能调用。

    Parameters

    • volume: number

      播放音量。取值范围为 [0,400]，其中：

      • 0: 静音
      • 100:（默认）原始音量
      • 400: 原始音量的 4 倍（自带溢出保护）

    Returns number

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

adjustRecordingSignalVolume

  • adjustRecordingSignalVolume(volume: number): number

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

    note

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

    Parameters

    • volume: number

      麦克风采集信号音量。取值范围为 [0,400]，其中：

      • 0: 静音
      • 100:（默认）原始音量
      • 400: 原始音量的 4 倍（自带溢出保护）

    Returns number

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

adjustUserPlaybackSignalVolume

  • adjustUserPlaybackSignalVolume(uid: number, volume: number): number
  • since

    v3.0.0

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

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

    note
    • 请在加入频道后，调用该方法。
    • 该方法调节的是本地播放的指定远端用户混音后的音量。

    Parameters

    • uid: number

      远端用户 ID。

    • volume: number

      播放音量，取值范围为 [0,100]:

      • 0: 静音
      • 100: 原始音量

    Returns number

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

clearVideoWatermarks

  • clearVideoWatermarks(): number
  • since

    v3.0.0

    删除已添加的视频水印。

    Returns number

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

complain

  • complain(callId: string, desc: string): number

  • 投诉通话质量。

    Parameters

    • callId: string

      通话 getCallId 方法获取的通话 ID

    • desc: string

      给通话的描述。可选参数，长度应小于 800 字节

    Returns number

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

createChannel

  • 创建并获取一个 AgoraRtcChannel 对象。

    你可以多次调用该方法，创建多个 AgoraRtcChannel 对象，再调用各 AgoraRtcChannel 对象 中的 joinChannel 方法，实现同时加入多个频道。

    加入多个频道后，你可以同时订阅各个频道的音、视频流；但是同一时间只能在一个频道发布一路音、视频流。

    note
    • 该参数没有默认值，请确保对参数设值。
    • 请勿将该参数设为空字符 ""，否则 SDK 会返回 ERR_REFUSED(5)

    Parameters

    • channelName: string

      能标识频道的频道名，长度在 64 字节以内的字符。以下为支持的字符集 范围（共 89 个字符）：

      • 26 个小写英文字母 a~z；
      • 26 个大写英文字母 A~Z；
      • 10 个数字 0~9；
      • 空格；
      • "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、 "@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。

    Returns AgoraRtcChannel | null

    • 方法调用成功，返回 AgoraRtcChannel 对象的指针
    • 方法调用失败，返回一个空指针 NULL
    • 如果将 channelName 设为空字符 ""，SDK 会返回 ERR_REFUSED(5)

createDataStream

  • createDataStream(reliable: boolean, ordered: boolean): number

  • 创建数据流。

    deprecated

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

    该方法用于创建数据流。AgoraRtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。

    note
    • 频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 App 报错。
    • 请将 reliable 和 ordered 同时设置为 true 或 false，暂不支持交叉设置。

    Parameters

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

    Returns number

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

createDataStreamWithConfig

  • 创建数据流。

    since

    v3.3.1

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

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

    Parameters

    Returns number

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

destroyRender

  • destroyRender(key: "local" | "videosource" | number, channelId: string | undefined, onFailure?: undefined | function): void

  • 销毁渲染器对象。

    Parameters

    • key: "local" | "videosource" | number

      存储渲染器 Map 的关键标识，如 uid、videoSource 或 local

    • channelId: string | undefined
    • Optional onFailure: undefined | function

      destroyRenderer 方法的错误回调

    Returns void

destroyRenderView

  • destroyRenderView(key: "local" | "videosource" | number, channelId: string | undefined, view: Element, onFailure?: undefined | function): void

  • Parameters

    • key: "local" | "videosource" | number
    • channelId: string | undefined
    • view: Element
    • Optional onFailure: undefined | function

    Returns void

disableAudio

  • disableAudio(): number

  • 关闭音频模块。

    note

    • 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

    • 该方法重置整个引擎，响应速度较慢，因此建议使用如下方法来控制音频模块：

    Returns number

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

disableLastmileTest

  • disableLastmileTest(): number

  • 关闭网络测试。

    Returns number

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

disableVideo

  • disableVideo(): number

  • 关闭视频模块。

    该方法可以在加入频道前或者通话中调用：

    • 在加入频道前调用，则自动开启纯音频模式；
    • 在通话中调用，则由视频模式切换为纯音频频模式。

    成功掉调用该方法后，远端会触发 userEnableVideo(fasle) 回调。

    若想再次开启视频模块，请调用 enableVideo 方法。

    note

    • 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

    • 该方法重置整个引擎，响应速度较慢，因此声网建议使用如下方法来控制视频模块：

    Returns number

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

enableAudio

  • enableAudio(): number

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

    note

    • 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

    • 该方法重置整个引擎，响应速度较慢，因此建议使用如下方法来控制音频模块：

    Returns number

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

enableAudioVolumeIndication

  • enableAudioVolumeIndication(interval: number, smooth: number, report_vad?: boolean): number

  • 启用说话者音量提示。

    该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。启用该方法后，无论频道内是否有人说话， 都会在说话声音音量提示回调 groupAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

    Parameters

    • interval: number

      指定音量提示的时间间隔：

      • ≤ 0: 不启用音量提示功能
      • > 0: 返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 groupAudioVolumeIndication 回调。
    • smooth: number

      平滑系数，指定音量提示的灵敏度。取值范围为 [0, 10]。建议值为 3，数字越大，波动越灵敏；数字越小，波动越平滑

    • Default value report_vad: boolean = false
      • true: 开启本地人声检测功能。开启后，groupAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
      • false:（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，groupAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

    Returns number

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

enableContentInspect

  • 开启/关闭视频截图上传。

    since

    v3.7.0

    开启视频截图上传后，SDK 会根据你在 ContentInspectConfig 中设置的模块类型和频率对本地用户发送的视频进行截图和上传。截图完成后，Agora 服务器会以 HTTPS 请求的形式向你的服务器发送通知，并将所有截图发送至你指定的第三方云存储。

    相比 takeSnapshot 方法，本方法可以按照你设置的截图频率进行周期性截图，并将截图发送至你指定的第三方云存储。

    note

    调用该方法前，请确保满足以下要求：

    • 提交工单开通声网视频截图上传服务。
    • 已将如下动态库集成到项目中：
      • Android：libagora_ci_extension.so
      • iOS/macOS：AgoraCIExtension.xcframework
      • Windows：libagora_ci_extension.dll

    Parameters

    • enabled: boolean

      设置是否开启视频截图上传：

      • true: 开启。
      • false: 关闭。
    • config: ContentInspectConfig

      视频截图上传配置。详见 ContentInspectConfig 。

    Returns number

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

enableDeepLearningDenoise

  • enableDeepLearningDenoise(enabled: boolean): number

  • 开启或关闭 AI 降噪模式。

    SDK 默认开启传统降噪模式，以消除大部分平稳噪声。如果你还需要消除非平稳噪声，Agora 推荐你按如下步骤开启 AI 降噪模式：

    1. 将 libs 文件夹中的动态库集成到项目中。
      • macOS: AgoraAIDenoiseExtension.framework
      • Windows: libagora_ai_denoise_extension.dll
    2. 调用 enableDeepLearningDenoise(true)。

    AI 降噪模式需使用高性能的设备，如 MacBook Pro 2015。只有在设备性能良好的情况下， SDK 才会成功开启 AI 降噪模式。

    成功开启 AI 降噪模式后，如果 SDK 检测到当前设备的性能不足，SDK 会自动关闭 AI 降噪模式，并开启传统降噪模式。

    在频道内，如果你调用了 enableDeepLearningDenoise(false) 或 SDK 自动关闭了 AI 降噪模式，当你需要重新开启 AI 降噪模式时， 你需要先调用 leaveChannel，再调用 enableDeepLearningDenoise(true)。

    note
    • 该方法需要动态加载动态库，所以推荐在加入频道前调用该方法。
    • 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。

    Parameters

    • enabled: boolean

    Returns number

    • 0: 方法调用成功
    • < 0: 方法调用失败
      • -157: 未集成用于 AI 降噪的动态库。

enableDualStreamMode

  • enableDualStreamMode(enable: boolean): number

  • 开/关视频双流模式。

    该方法设置单流（默认）或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。

    其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

    Parameters

    • enable: boolean

      指定双流或者单流模式：

      • true：开启双流
      • false：不开启双流（默认）

    Returns number

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

enableEncryption

  • 开启或关闭内置加密。

    since

    v3.2.0

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

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

    note

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

    Parameters

    • enabled: boolean

      是否开启内置加密：

      • true: 开启
      • false: 关闭
    • config: EncryptionConfig

      配置内置加密模式和密钥。

    Returns number

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

enableLastmileTest

  • enableLastmileTest(): number

  • 启用网络测试。

    该方法启用网络连接质量测试，用于检测用户网络接入质量。默认该功能为关闭状态。

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

    • 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
    • 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。
    note
    • 该方法请勿与 startLastmileProbeTest 方法同时使用。
    • 调用该方法后，在收到 lastMileQuality 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此回调无法执行。
    • 启用该方法会消耗一定的网络流量，影响通话质量。在收到 lastMileQuality 回调后， 需调用 stopEchoTest 方法停止测试，再加入频道或切换用户角色。
    • 直播场景下，主播在加入频道后，请勿调用该方法。
    • 加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest，SDK 均会自动停止带宽占用。

    Returns number

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

enableLocalAudio

  • enableLocalAudio(enable: boolean): number

  • 开/关本地音频采集。

    当 App 加入频道时，它的语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能，即停止或重新开始本地音频采集。

    该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。语音功能关闭或重新开启后，会收到回调 microphoneEnabled。

    note

    该方法与 muteLocalAudioStream 的区别在于：

    • enableLocalAudio: 使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
    • muteLocalAudioStream: 使用 muteLocalAudioStream 停止或继续发送本地音频流后，本地听远端播放不会有短暂中断。

    Parameters

    • enable: boolean
      • true：开启本地音频采集（默认）
      • false：关闭本地音频采集

    Returns number

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

enableLocalVideo

  • enableLocalVideo(enable: boolean): number

  • 开/关本地视频采集。

    该方法禁用或重新启用本地视频采集，不影响接收远端视频。

    调用 enableVideo 后，本地视频即默认开启。你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想要重新开启，则可调用 enableLocalVideo(true)。

    成功禁用或启用本地视频采集后，远端会触发 userEnableLocalVideo 回调。

    Parameters

    • enable: boolean
      • true：开启本地视频采集和渲染（默认）
      • false：关闭本地视频采集和渲染。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流

    Returns number

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

enableLocalVoicePitchCallback

  • enableLocalVoicePitchCallback(interval: number): number

  • 开启本地语音音调回调。

    since

    v3.7.0

    该方法允许 SDK 定期向 app 报告本地用户的语音音调。开启本地音频采集并调用该方法后，SDK 会按设置的时间间隔触发 localVoicePitchInHz 回调。

    note

    该方法在加入频道前后均可调用。

    Parameters

    • interval: number

      设置 SDK 触发 localVoicePitchInHz 回调的时间间隔：

      • ≤ 0: 关闭 localVoicePitchInHz 回调。
      • > 0: SDK 触发 localVoicePitchInHz 回调的时间间隔，单位为毫秒。取值需大于等于 10 毫秒，如果小于 10 毫秒，SDK 会自动调整为 10 毫秒。

    Returns number

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

enableLoopbackRecording

  • enableLoopbackRecording(enable?: boolean, deviceName?: string | null): number

  • 开启声卡采集。

    启用声卡采集功能后，声卡播放的声音会被合到本地音频流中，从而可以发送到远端。

    note

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

    Parameters

    • Default value enable: boolean = false

      是否开启声卡采集：

      • true：开启声卡采集
      • false：（默认）关闭声卡采集
    • Default value deviceName: string | null = null

      声卡的设备名。

      • 默认设为 null，即使用当前声卡采集。
      • 如果用户使用虚拟声卡，如 Soundflower，可以将虚拟声卡名称 "soundflower" 作为参数传入，SDK 会找到对应的虚拟声卡设备，并开始采集。Note: macOS 系统默认声卡 不支持采集功能，如需开启此功能需要 App 自己启用一个虚拟声卡，并将该虚拟声卡的名字 作为 deviceName 传入 SDK。声网测试并推荐 soundflower 作为虚拟声卡。

    Returns number

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

enableSoundPositionIndication

  • enableSoundPositionIndication(enable: boolean): number

  • 开启/关闭远端用户的语音立体声。

    如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在调用 joinChannel 方法前调用该方法。

    Parameters

    • enable: boolean

      是否开启远端用户语音立体声：

      • true：开启
      • false：（默认）关闭

    Returns number

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

enableSpatialAudio

  • enableSpatialAudio(enabled: boolean): number

  • Parameters

    • enabled: boolean

    Returns number

enableVideo

  • enableVideo(): number

  • 启用视频模块。

    该方法可以在加入频道前或者通话中调用。

    • 在加入频道前调用，则自动开启视频模式；
    • 在通话中调用则由音频模式切换为视频模式。

    成功调用该方法后，远端会触发 userEnableVideo(true) 回调。

    若想关闭视频模式，请调用 disableVideo 方法。

    note

    • 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

    • 该方法重置整个引擎，响应速度较慢，因此声网建议使用如下方法来控制视频模块：

    Returns number

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

enableVirtualBackground

  • 开启/关闭虚拟背景。

    自 v3.4.5 支持 macOS 和 Windows 平台，自 v3.5.0 支持 Android 和 iOS 平台。

    开启虚拟背景功能后，你可以使用自定义的背景图替代本地用户原来的背景图。替换后，频道内所有用户都能看到自定义的背景图。 你可以从 virtualBackgroundSourceEnabled 回调了解虚拟 背景是否成功开启和相应的出错原因。

    note
    • 调用该方法前，请确保你已经将如下动态库集成到项目中：
      • Android: libagora_segmentation_extension.so
      • iOS/macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • 请在 enableVideo 后调用该方法。
    • 该功能对设备性能要求较高，Agora 推荐你在如下设备上使用：
      • Android：搭载如下芯片的设备：
        • 骁龙 700 系列 750G 及以上
        • 骁龙 800 系列 835 及以上
        • 天玑 700 系列 720 及以上
        • 麒麟 800 系列 810 及以上
        • 麒麟 900 系列 980 及以上
      • iOS：搭载 A9 及以上芯片的如下设备：
        • iPhone 6S 及以上
        • iPad Air 第三代及以上
        • iPad 第五代及以上
        • iPad Pro 第一代及以上
        • iPad mini 第五代及以上
      • macOS 和 Windows：CPU 为 i5 及更好的设备
    • 建议你在满足如下条件的场景中使用该功能：
      • 使用高清摄像设备、摄像环境光照均匀。
      • 摄像画面中，物件较少，用户的人像为半身人像且基本无遮挡，背景色较单一且与用户着装颜色不同。
    • 虚拟背景功能不支持 Texture 格式视频和来自 Push 自采集的视频。

    Parameters

    • enabled: Boolean

      设置是否开启虚拟背景：

      • true: 开启。
      • false: 关闭。
    • backgroundSource: VirtualBackgroundSource

      自定义的背景图。详见 VirtualBackgroundSource 。Note: 为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配， SDK 会在保证自定义背景图内容不变形的前提下，对自定义背景图进行缩放和裁剪。

    Returns number

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

enableWebSdkInteroperability

  • enableWebSdkInteroperability(enable: boolean): number
  • deprecated

    该方法已废弃。自 Native SDK v3.0.0 及之后，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。

    打开与 Web SDK 的互通（仅在直播下适用）。

    该方法打开或关闭与 RTC Web SDK 的互通。该方法仅在直播场景下适用，通信场景下默认互通是打开的。

    如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。

    Parameters

    • enable: boolean

      是否打开与 RTC Web SDK 的互通：

      • true：打开互通
      • false：关闭互通（默认）

    Returns number

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

enableWirelessAccelerate

  • enableWirelessAccelerate(enabled: boolean): number

  • 开启或关闭 Wi-Fi 加速功能。

    since

    v3.7.0

    自该版本起，SDK 默认开启 Wi-Fi 加速功能。当 SDK 发现集成加速插件的 Wi-Fi 路由器后，该功能才会生效，使路由器合理分配 Wi-Fi 频谱资源，以降低丢包率和时延，从而减少音视频卡顿。

    当路由器提供加速服务后，SDK 会周期性触发 wlAccStats 回调，报告 Wi-Fi 连接优化数据，并在 Wi-Fi 连接质量不佳时触发 wlAccMessage 回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

    note
    • Wi-Fi 加速功能默认开启，但必须与集成加速插件的路由器配合使用才能生效，详见哪些 Wi-Fi 路由器可支持加速功能。如果 Wi-Fi 路由器不支持加速功能，系统性能不会受损。
    • 加速功能生效后，路由器的 app 会显示加速效果和被加速 app 的名称。如果你不想在路由器的 app 中展示被加速 app 的名称，请调用 enableWirelessAccelerate(false) 关闭加速功能。
    • 请在加入频道前或离开频道后调用该方法。
    • 声网提供的 Wi-Fi 加速功能除应用于音视频流，还可以应用于其他第三方业务流，如私有信令、课件、RTMP 协议等。如有需要，请联系 sales@agora.io。

    Parameters

    • enabled: boolean

      设置是否开启 Wi-Fi 加速功能：

      • true: 开启。
      • false: 关闭。

    Returns number

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

followSystemPlaybackDevice

  • followSystemPlaybackDevice(enable: boolean): number

  • 设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。

    since

    v3.6.1.4

    Parameters

    • enable: boolean

      是否跟随系统默认的音频播放设备：

      • true：跟随。当系统默认音频播放设备发生改变时，SDK 立即切换音频播放设备。
      • false：不跟随。只有当 SDK 使用的音频播放设备被移除后，SDK 才切换至系统默认的音频播放设备。

    Returns number

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

followSystemRecordingDevice

  • followSystemRecordingDevice(enable: boolean): number

  • 设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。

    since

    v3.6.1.4

    Parameters

    • enable: boolean

      是否跟随系统默认的音频采集设备：

      • true：跟随。当系统默认的音频采集设备改变时，SDK 立即切换音频采集设备。
      • false：不跟随。只有当 SDK 使用的音频采集设备被移除后，SDK 才切换至系统默认的音频采集设备。

    Returns number

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

getAudioFileInfo

  • getAudioFileInfo(filePath: string): number

  • 获取指定音频文件信息。

    since

    v3.6.1.4

    成功调用该方法后，SDK 会触发 requestAudioFileInfo 回调， 报告指定音频文件的时长等信息。你可以多次调用该方法，获取多个音频文件的信息。

    note

    Parameters

    • filePath: string

      文件路径：

      • Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C: \music\audio.mp4。
      • Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。
      • Note*: 通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
      • iOS 和 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。

    Returns number

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

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): number

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

    note
    • 播放进度的单位为毫秒。
    • 请在频道内调用该方法。

    Returns number

    • < 0：方法调用失败
    • 其他值：方法调用成功并返回伴奏播放进度

getAudioMixingDuration

  • getAudioMixingDuration(): number

  • 获取音乐文件总时长。

    deprecated

    自 v3.4.2 废弃，请改用 getAudioFileInfo。

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

    note

    你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(710) 回调后调用该方法。

    Returns number

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

getAudioMixingPlayoutVolume

  • getAudioMixingPlayoutVolume(): number

  • 获取音乐文件的本地播放音量。

    该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。

    note

    请在频道内调用该方法。

    Returns number

    • ≥ 0：方法调用成功则返回音量值，范围为 [0,100]
    • < 0：方法调用失败

getAudioMixingPublishVolume

  • getAudioMixingPublishVolume(): number

  • 调节音乐文件远端播放音量。

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

    note
    • 请在频道内调用该方法。
    • 音乐文件音量范围为 0~100。100 （默认值） 为原始文件音量。

    Returns number

    • ≥ 方法调用成功则返回音量值
    • < 0 方法调用失败

getAudioPlaybackDeviceMute

  • getAudioPlaybackDeviceMute(): boolean

  • 获取当前音频播放设备的静音状态。

    Returns boolean

    • true：当前音频播放设备静音
    • false：当前音频播放设备不静音

getAudioPlaybackDevices

  • getAudioPlaybackDevices(): Array<Object>

  • 获取音频播放设备列表。

    Returns Array<Object>

    音频播放设备的 Array

getAudioPlaybackVolume

  • getAudioPlaybackVolume(): number

  • 获取音频播放设备的音量

    Returns number

    播放设备音量（分贝）。取值范围 [0,255]

getAudioRecordingDeviceMute

  • getAudioRecordingDeviceMute(): boolean

  • 获取当前音频录制设备的静音状态。

    Returns boolean

    • true：当前音频录制设备静音
    • false：当前音频录制设备不静音

getAudioRecordingDevices

  • getAudioRecordingDevices(): Array<Object>

  • 获取音频录制设备

    Returns Array<Object>

    音频录制设备的 Array

getAudioRecordingVolume

  • getAudioRecordingVolume(): number

  • 获取录制设备的音量。

    Returns number

    录音设备音量（分贝）。取值范围 [0,255]

getAudioTrackCount

  • getAudioTrackCount(): number

  • 获取当前音乐文件的音轨索引。

    since

    v3.6.1.4

    note

    Returns number

    • ≥ 0: 方法调用成功，返回当前音乐文件的音轨索引。
    • < 0: 方法调用失败。

getCallId

  • getCallId(): string

  • 获取通话 ID。

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

    Returns string

    通话 ID

getConfigObject

  • getConfigObject(): Config

  • Returns Config

getConnectionState

getCurrentAudioPlaybackDevice

  • getCurrentAudioPlaybackDevice(): Object

  • 获取当前的音频播放设备。

    Returns Object

    音频播放设备对象

getCurrentAudioRecordingDevice

  • getCurrentAudioRecordingDevice(): Object

  • 获取当前的音频录制设备。

    Returns Object

    音频录制设备对象

getCurrentVideoDevice

  • getCurrentVideoDevice(): Object

  • 获取当前的视频设备。

    Returns Object

    视频设备对象

getDefaultAudioPlaybackDevices

  • getDefaultAudioPlaybackDevices(): Object

  • 获取系统默认的音频播放设备。

    since

    v3.6.1.4

    Returns Object

getDefaultAudioRecordingDevices

  • getDefaultAudioRecordingDevices(): Object

  • 获取系统默认的音频采集设备。

    since

    v3.6.1.4

    Returns Object

getEffectCurrentPosition

  • getEffectCurrentPosition(soundId: number): number

  • 获取指定音效文件的播放进度。

    since

    v3.4.2

    note

    该方法需要在 playEffect 后调用。

    Parameters

    • soundId: number

      音效 ID。请确保与 playEffect 中设置的 soundId 一致。

    Returns number

    • ≥ 0: 方法调用成功。
    • < 0: 方法调用失败。
      • -22: 无法找到音效文件。请填写正确的 soundId。

getEffectDuration

  • getEffectDuration(filePath: string): number

  • 获取指定音效文件总时长。

    since

    v3.4.2

    note

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

    Parameters

    • filePath: string

      音效文件的绝对路径或 URL 地址，需精确到文件名及后缀。 例如：C:\music\audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Supported Media Formats in Media Foundation。

    Returns number

    • ≥ 0: 方法调用成功，返回指定音效文件时长（毫秒）。
    • < 0: 方法调用失败。
      • -22: 无法找到音效文件。请填写正确的 filePath。

getEffectsVolume

  • getEffectsVolume(): number

  • 获取播放音效文件音量。

    Returns number

    • ≥ 0：方法调用成功则返回音量值，范围为 [0.0, 100.0]
    • < 0：方法调用失败

getErrorDescription

  • getErrorDescription(errorCode: number): string

  • 获取指定错误码的详细错误信息。

    Parameters

    • errorCode: number

      错误码

    Returns string

    errorCode 描述

getPlaybackDeviceInfo

  • getPlaybackDeviceInfo(deviceId: string, deviceName: string): number

  • 获取播放设备信息。

    Parameters

    • deviceId: string

      设备 ID

    • deviceName: string

      设备名称

    Returns number

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

getRealScreenDisplaysInfo

  • getRealScreenDisplaysInfo(callback: function): void

getRecordingDeviceInfo

  • getRecordingDeviceInfo(deviceId: string, deviceName: string): number

  • 获取录制设备信息。

    Parameters

    • deviceId: string

      设备 ID

    • deviceName: string

      设备名

    Returns number

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

getScreenCaptureSources

  • getScreenCaptureSources(thumbSize: SIZE, iconSize: SIZE, includeScreen: boolean): Array<Object>

  • 获取可共享的屏幕和窗口对象列表。

    since

    v3.6.1.4

    屏幕共享或窗口共享前，你可以调用该方法获取可共享的屏幕和窗口的对象列表，方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。 列表中包含窗口 ID 和屏幕 ID 等重要信息，你可以获取到 ID 后再调用 startScreenCaptureByWindow 或 startScreenCaptureByDisplayId 开启共享。

    note

    该方法仅适用于 macOS 和 Windows。

    Parameters

    • thumbSize: SIZE

      屏幕或窗口的缩略图的目标尺寸（宽高单位为像素）。详见 SIZE。 SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，thumbSize 为 100 x 100，缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，缩略图即为原图，SDK 不进行缩放操作。

    • iconSize: SIZE

      程序所对应的图标的目标尺寸（宽高单位为像素）。详见 SIZE。 SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，iconSize 为 100 × 100，图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，图标即为原图，SDK 不进行缩放操作。

    • includeScreen: boolean

      除了窗口信息外，SDK 是否还返回屏幕信息：

      • true: 是。SDK 返回屏幕和窗口信息。
      • false: 否。SDK 仅返回窗口信息。

    Returns Array<Object>

    Array of ScreenCaptureSource objects

getScreenDisplaysInfo

  • getScreenDisplaysInfo(callback: function): void

  • 获取屏幕信息。

    该方法获取所有的系统（macOS 或 Windows）屏幕 ID，以及相关信息。你可以使用获取到的屏幕 ID 进行屏幕共享。

    Windows 和 macOS 系统的屏幕 ID（displayId）不同。你无需关注屏幕 ID 的具体内容，直接使用它进行屏幕共享即可。

    Parameters

    • callback: function

      回调函数。该回调的入参为 DisplayInfo 数组，返回值为空。

    Returns void

getScreenWindowsInfo

  • getScreenWindowsInfo(callback: function): void

  • 获取系统窗口信息。

    该方法获取所有系统（macOS 或 Windows）窗口 ID，以及相关信息。你可以使用获取到的窗口 ID 进行屏幕共享。

    Parameters

    • callback: function

      回调函数。该回调的入参为 WindowInfo 数组，返回值为空。

    Returns void

getUserInfoByUid

  • getUserInfoByUid(uid: number): object

  • 通过 UID 获取用户信息。

    远端用户加入频道后， SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表， 并在本地触发 userInfoUpdated 回调。你收到这个回调后，可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。

    Parameters

    • uid: number

      用户 UID

    Returns object

    • errCode 方法调用失败，返回错误码
    • userInfo 方法调用成功，返回包含了指定用户 User Account 的 UserInfo 对象

getUserInfoByUserAccount

  • getUserInfoByUserAccount(userAccount: string): object

  • 通过 User Account 获取用户信息。

    远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表， 并在本地触发 userInfoUpdated 回调。你收到这个回调后，可以调用该方法，通过传入 User Account 获取包含了指定用户 UID 的 UserInfo 对象。

    Parameters

    • userAccount: string

      用户 User Account

    Returns object

    • errCode 方法调用失败，返回错误码
    • userInfo 方法调用成功，获取包含了指定用户 UID 的 UserInfo 对象

getVersion

  • getVersion(): string

  • 获取当前 SDK 的版本和 Build 信息。

    Returns string

    当前 SDK 的版本

getVideoDevices

  • getVideoDevices(): Array<Object>

  • Returns Array<Object>

initRender

  • initRender(key: "local" | "videosource" | number, view: Element, channelId: string | undefined, options?: RendererOptions): void

  • 初始化渲染器对象。

    Parameters

    • key: "local" | "videosource" | number

      存储渲染器 Map 的关键标识，如 uid、videosource 或 local

    • view: Element

      渲染视频的 Dom

    • channelId: string | undefined
    • Optional options: RendererOptions

    Returns void

initialize

  • 初始化一个 AgoraRtcEngine 实例。

    Parameters

    • appid: string

      声网为 App 开发者签发的 App ID，每个项目都应该有一个独一无二的 App ID

    • Default value areaCode: AREA_CODE = 4294967295

      服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。支持的区域详见 AREA_CODE 指定访问区域后，SDK 会连接指定区域内的声网服务器。注解：仅支持指定单个访问区域。

    • Optional logConfig: LogConfig

      SDK 日志文件配置。默认情况下，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 写入最新的日志。

    Returns number

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

joinChannel

  • joinChannel(token: string, channel: string, info: string, uid: number, options?: ChannelMediaOptions): number

  • 加入频道并设置是否自动订阅音频或视频流。

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

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

    在网络状况不理想的情况下，客户端可能会与声网的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 rejoinedChannel 回调。

    note

    请确保用于生成 Token 的 App ID 和调用 initialize 时传入的 App ID 一致。

    Parameters

    • token: string

      在服务端生成的用于鉴权的 Token。 详见从服务端生成 Token。

    • channel: string

      标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

      • 26 个小写英文字母 a~z；
      • 26 个大写英文字母 A~Z；
      • 10个数字 0~9；
      • 空格；
      • "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
    • info: string

      (非必选项) 预留参数。

    • uid: number

      (非必选项) 用户 ID，32位无符号整数。建议设置范围：1到 232-1，并保证唯一性。如果不指定（即设为0），SDK 会自动分配一个， 并在 joinedChannel 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。 请注意：频道内每个用户的 UID 必须是唯一的。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。

    • Optional options: ChannelMediaOptions

      频道媒体设置选项。

    Returns number

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

joinChannelWithUserAccount

  • joinChannelWithUserAccount(token: string, channel: string, userAccount: string, options?: ChannelMediaOptions): number

  • 使用 User Account 加入频道。

    该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：

    • 本地：localUserRegistered 和 joinedChannel 回调
    • 远端：通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 userJoined 和 userInfoUpdated 回调

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

    note

    为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 RTC Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

    Parameters

    • token: string

      在服务端生成的用于鉴权的 Token。详见从服务端生成 Token。

    • channel: string
    • userAccount: string

      用户 User Account。该参数为必需，最大不超过 255 字节，不可为 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）：

      • 26 个小写英文字母 a-z
      • 26 个大写英文字母 A-Z
      • 10 个数字 0-9
      • 空格
      • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    • Optional options: ChannelMediaOptions

    Returns number

    • 0: 方法调用成功
    • < 0: 方法调用失败
      • -2
      • -3
      • -5
      • -7

leaveChannel

  • leaveChannel(): number

  • 离开频道。

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

    该方法会把回话相关的所有资源都释放掉。该方法是异步操作，调用返回时并没有真正退出频道。 真正退出频道后，本地会触发 leaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 removeStream 回调。

    note
    • 若想开始下一次通话，必须先调用该方法结束本次通话。
    • 不管当前是否在通话中，都可以调用该方法，没有副作用。
    • 如果你调用该方法后立即调用 release 方法，SDK 将无法触发 leaveChannel 回调。

    Returns number

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

muteAllRemoteAudioStreams

  • muteAllRemoteAudioStreams(mute: boolean): number

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

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

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

    Parameters

    • mute: boolean

      是否取消订阅所有远端用户的音频流。

      • true: 取消订阅。
      • false:（默认）订阅。

    Returns number

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

muteAllRemoteVideoStreams

  • muteAllRemoteVideoStreams(mute: boolean): number

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

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

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

    Parameters

    • mute: boolean

      是否取消订阅所有远端用户的视频流。

      • true: 取消订阅。
      • false:（默认）订阅。

    Returns number

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

muteLocalAudioStream

  • muteLocalAudioStream(mute: boolean): number

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

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

    note
    • 该方法不影响音频采集状态，因为没有禁用音频采集设备。
    • 该方法在加入频道前后都能调用。如果你在该方法后调用 setChannelProfile 方法， SDK 会根据你设置的频道场景以及用户角色，重新设置是否取消发布本地音频。因此我们建议在 setChannelProfile 后调用该方法。

    Parameters

    • mute: boolean

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

      • true: 取消发布。
      • false:（默认）发布。

    Returns number

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

muteLocalVideoStream

  • muteLocalVideoStream(mute: boolean): number

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

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

    note
    • 相比于调用 enableLocalVideo 控制本地视频流发送，调用该方法响应速度更快。
    • 该方法不影响视频采集状态，因为没有禁用摄像头。
    • 该方法在加入频道前后都能调用。如果你在该方法后调用 setChannelProfile 方法， SDK 会根据你设置的频道场景以及用户角色，重新设置是否取消发布本地视频。因此我们建议在 setChannelProfile 后调用该方法。

    Parameters

    • mute: boolean

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

      • true: 取消发布。
      • false: （默认）发布。

    Returns number

muteRemoteAudioStream

  • muteRemoteAudioStream(uid: number, mute: boolean): number

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

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

    Parameters

    • uid: number
    • mute: boolean

      是否取消订阅指定远端用户的音频流。

      • true: 取消订阅。
      • false:（默认）订阅。

    Returns number

muteRemoteVideoStream

  • muteRemoteVideoStream(uid: number, mute: boolean): number

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

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

    Parameters

    • uid: number
    • mute: boolean

      是否取消订阅指定远端用户的视频流。

      • true: 取消订阅。
      • false:（默认）订阅。

    Returns number

off

  • off(event: string | symbol, listener: function): this

  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void

        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

on

  • on(event: string | symbol, listener: function): this
  • on(evt: "apiCallExecuted", cb: function): this
  • on(evt: "warning", cb: function): this
  • on(evt: "error", cb: function): this
  • on(evt: "joinedChannel", cb: function): this
  • on(evt: "rejoinedChannel", cb: function): this
  • on(evt: "audioVolumeIndication", cb: function): this
  • on(evt: "groupAudioVolumeIndication", cb: function): this
  • on(evt: "leaveChannel", cb: function): this
  • on(evt: "rtcStats", cb: function): this
  • on(evt: "localVideoStats", cb: function): this
  • on(evt: "localAudioStats", cb: function): this
  • on(evt: "remoteVideoStats", cb: function): this
  • on(evt: "remoteAudioStats", cb: function): this
  • on(evt: "remoteVideoTransportStats", cb: function): this
  • on(evt: "remoteAudioTransportStats", cb: function): this
  • on(evt: "requestAudioFileInfo", cb: function): this
  • on(evt: "audioDeviceStateChanged", cb: function): this
  • on(evt: "audioMixingStateChanged", cb: function): this
  • on(evt: "remoteAudioMixingBegin", cb: function): this
  • on(evt: "remoteAudioMixingEnd", cb: function): this
  • on(evt: "audioEffectFinished", cb: function): this
  • on(evt: "videoDeviceStateChanged", cb: function): this
  • on(evt: "networkQuality", cb: function): this
  • on(evt: "lastMileQuality", cb: function): this
  • on(evt: "lastmileProbeResult", cb: function): this
  • on(evt: "firstLocalVideoFrame", cb: function): this
  • on(evt: "addStream", cb: function): this
  • on(evt: "videoSizeChanged", cb: function): this
  • on(evt: "firstRemoteVideoFrame", cb: function): this
  • on(evt: "firstRemoteVideoDecoded", cb: function): this
  • on(evt: "userJoined", cb: function): this
  • on(evt: "removeStream", cb: function): this
  • on(evt: "userOffline", cb: function): this
  • on(evt: "userMuteAudio", cb: function): this
  • on(evt: "userMuteVideo", cb: function): this
  • on(evt: "userEnableVideo", cb: function): this
  • on(evt: "userEnableLocalVideo", cb: function): this
  • on(evt: "cameraReady", cb: function): this
  • on(evt: "videoStopped", cb: function): this
  • on(evt: "connectionLost", cb: function): this
  • on(evt: "connectionBanned", cb: function): this
  • on(evt: "streamMessage", cb: function): this
  • on(evt: "streamMessageError", cb: function): this
  • on(evt: "mediaEngineStartCallSuccess", cb: function): this
  • on(evt: "requestChannelKey", cb: function): this
  • on(evt: "firstLocalAudioFrame", cb: function): this
  • on(evt: "firstRemoteAudioFrame", cb: function): this
  • on(evt: "firstRemoteAudioDecoded", cb: function): this
  • on(evt: "activeSpeaker", cb: function): this
  • on(evt: "clientRoleChanged", cb: function): this
  • on(evt: "audioDeviceVolumeChanged", cb: function): this
  • on(evt: "videoSourceJoinedSuccess", cb: function): this
  • on(evt: "videoSourceRequestNewToken", cb: function): this
  • on(evt: "videoSourceLeaveChannel", cb: function): this
  • on(evt: "videoSourceScreenCaptureInfoUpdated", cb: function): this
  • on(evt: "videoSourceLocalAudioStats", cb: function): this
  • on(evt: "videoSourceLocalVideoStats", cb: function): this
  • on(evt: "videoSourceVideoSizeChanged", cb: function): this
  • on(evt: "videoSourceLocalVideoStateChanged", cb: function): this
  • on(evt: "videoSourceLocalAudioStateChanged", cb: function): this
  • on(evt: "remoteVideoStateChanged", cb: function): this
  • on(evt: "cameraFocusAreaChanged", cb: function): this
  • on(evt: "cameraExposureAreaChanged", cb: function): this
  • on(evt: "tokenPrivilegeWillExpire", cb: function): this
  • on(evt: "streamPublished", cb: function): this
  • on(evt: "streamUnpublished", cb: function): this
  • on(evt: "rtmpStreamingStateChanged", cb: function): this
  • on(evt: "transcodingUpdated", cb: function): this
  • on(evt: "localPublishFallbackToAudioOnly", cb: function): this
  • on(evt: "remoteSubscribeFallbackToAudioOnly", cb: function): this
  • on(evt: "microphoneEnabled", cb: function): this
  • on(evt: "connectionStateChanged", cb: function): this
  • on(evt: "networkTypeChanged", cb: function): this
  • on(evt: "localUserRegistered", cb: function): this
  • on(evt: "userInfoUpdated", cb: function): this
  • on(evt: "localVideoStateChanged", cb: function): this
  • on(evt: "localAudioStateChanged", cb: function): this
  • on(evt: "remoteAudioStateChanged", cb: function): this
  • on(evt: "channelMediaRelayState", cb: function): this
  • on(evt: "channelMediaRelayEvent", cb: function): this
  • on(evt: "receiveMetadata", cb: function): this
  • on(evt: "sendMetadataSuccess", cb: function): this
  • on(evt: "firstLocalAudioFramePublished", cb: function): this
  • on(evt: "firstLocalVideoFramePublished", cb: function): this
  • on(evt: "rtmpStreamingEvent", cb: function): this
  • on(evt: "audioPublishStateChanged", cb: function): this
  • on(evt: "videoPublishStateChanged", cb: function): this
  • on(evt: "audioSubscribeStateChanged", cb: function): this
  • on(evt: "videoSubscribeStateChanged", cb: function): this
  • on(evt: "uploadLogResult", cb: function): this
  • on(evt: "virtualBackgroundSourceEnabled", cb: function): this
  • on(evt: "localVoicePitchInHz", cb: function): this
  • on(evt: "clientRoleChangeFailed", cb: function): this
  • on(evt: "wlAccMessage", cb: function): this
  • on(evt: "wlAccStats", cb: function): this
  • on(evt: "proxyConnected", cb: function): this
  • on(evt: "agoraVideoRawData", cb: function): this
  • on(evt: string, listener: Function): this

  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void

        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

  • API 方法已执行回调。

    Parameters

    • evt: "apiCallExecuted"
    • cb: function
        • (api: string, err: number): void

        • Parameters

          • api: string

            SDK 所调用的 API。

          • err: number

            方法调用失败时返回的错误码。

          Returns void

    Returns this

  • 发生警告回调。

    Parameters

    • evt: "warning"
    • cb: function
        • (warn: number, msg: string): void

        • Parameters

          • warn: number

            警告码。

          • msg: string

            警告信息。

          Returns void

    Returns this

  • 发生错误回调。

    Parameters

    • evt: "error"
    • cb: function
        • (err: number, msg: string): void

        • Parameters

          • err: number

            错误码。

          • msg: string

            错误信息。

          Returns void

    Returns this

  • 用户加入频道回调。

    Parameters

    • evt: "joinedChannel"
    • cb: function
        • (channel: string, uid: number, elapsed: number): void

        • Parameters

          • channel: string

            频道名。

          • uid: number

            加入频道用户的用户 ID。

          • elapsed: number

            从调用 joinChannel 方法到触发该回调所经过的时间。

          Returns void

    Returns this

  • 重新加入频道回调。

    有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。

    Parameters

    • evt: "rejoinedChannel"
    • cb: function
        • (channel: string, uid: number, elapsed: number): void

        • Parameters

          • channel: string

            频道名

          • uid: number

            用户 ID

          • elapsed: number

            从调用 joinChannel 开始到发生此事件过去的时间（毫秒)

          Returns void

    Returns this

  • deprecated

    本回调为废弃回调。Agora 推荐你使用 groupAudioVolumeIndication 回调。

    Parameters

    • evt: "audioVolumeIndication"
    • cb: function
        • (uid: number, volume: number, speakerNumber: number, totalVolume: number): void

        • Parameters

          • uid: number
          • volume: number
          • speakerNumber: number
          • totalVolume: number

          Returns void

    Returns this

  • 提示频道内谁在说话以及说话者音量的回调。

    该回调提示频道内瞬时音量较高的几个用户的用户 ID 及他们的音量。默认禁用。可以通过 enableAudioVolumeIndication 方法开启；开启后，无论频道内是否有人说话，都会按方法中设置的时间间隔返回提示音量。

    note
    • 本地用户返回 uid 为 0，speakerNumber 始终为 1。
    • 用户调用 muteLocalAudioStream 方法会对该回调产生影响：
      • 本地用户：随即不再返回该回调。
      • 远端用户：15 秒后，该回调的报告中不再包含该远端用户。

    Parameters

    • evt: "groupAudioVolumeIndication"
    • cb: function
        • (speakers: object[], speakerNumber: number, totalVolume: number): void

        • Parameters

          • speakers: object[]

            音量较高的说话者的信息，包含：

            • uid：用户 ID
            • volume：本地用户：该用户的说话音量；远端用户：说话者各自混音后的音量
            • vad：本地用户：报告本地用户人声状态；远端用户：0
          • speakerNumber: number

            音量较高的用户人数：

            • 本地用户：1
            • 远端用户：3
          • totalVolume: number

            混音后总音量（分贝）。取值范围 [0,255]：

            • 本地用户：本地用户混音后的音量
            • 远端用户：所有说话者混音后的总音量

          Returns void

    Returns this

  • 用户离开频道。

    调用 leaveChannel 离开频道后，SDK 触发该回调。

    Parameters

    • evt: "leaveChannel"
    • cb: function

    Returns this

  • 通话相关统计信息。

    Parameters

    • evt: "rtcStats"
    • cb: function

        • Parameters

          Returns void

    Returns this

  • 通话中本地视频流的统计信息回调。

    note

    如果你此前调用 enableDualStreamMode 方法，则本回调描述本地设备发送的视频大流的统计信息。

    Parameters

    Returns this

  • 通话中本地音频流的统计信息回调。

    Parameters

    Returns this

  • 通话中远端视频流的统计信息回调。

    Parameters

    Returns this

  • 通话中远端音频流的统计信息回调。

    Parameters

    Returns this

  • deprecated

    该回调已废弃。请改用 remoteVideoStats 回调。

    通话中远端视频流传输的统计信息回调。

    该回调描述远端用户通话中端到端的网络统计信息，通过视频包计算，用客观的数据，如丢包、网络延迟等 ，展示当前网络状态。

    通话中，当用户收到远端用户/主播发送的视频数据包后，会每 2 秒触发一次该回调。和 remoteVideoStats 回调相比，该回调以数据展示当前网络状态，因此更客观。

    Parameters

    Returns this

  • deprecated

    该回调已废弃。请改用 remoteAudioStats 回调。

    通话中远端音频流传输的统计信息回调。

    Parameters

    Returns this

  • 音频文件信息回调。

    since

    v3.6.1.4

    成功调用 getAudioFileInfo 后，SDK 会触发该回调并报告音频文件的路径、时长等信息。

    Parameters

    Returns this

  • 音频设备状态已改变回调。

    Parameters

    • evt: "audioDeviceStateChanged"
    • cb: function
        • (deviceId: string, deviceType: number, deviceState: number): void

        • Parameters

          • deviceId: string

            设备 ID

          • deviceType: number

            设备类型，详见 MediaDeviceType

          • deviceState: number

            设备状态：

            • macOS：
              • 0: 设备就绪
              • 8: 设备被拔出
            • Windows：
              • 0：设备就绪
              • 1：设备正在使用
              • 2：设备被禁用
              • 4：没有此设备
              • 8：设备被拔出
              • 16：不推荐使用该设备

          Returns void

    Returns this

  • 本地用户的音乐文件播放状态已改变回调。

    since

    v3.4.2

    该回调在音乐文件播放状态发生改变时触发，并报告当前的播放状态和播放状态改变的原因。

    Parameters

    • evt: "audioMixingStateChanged"
    • cb: function
        • (state: number, reason: number): void

        • Parameters

          • state: number

            当前音乐文件播放状态：

            • 710：音乐文件正常播放。该状态可能由 reason 720、721、722、或 726 导致。
            • 711：音乐文件暂停播放。该状态由 reason 725 导致。
            • 713：音乐文件停止播放。该状态可能由 reason 723 或 724 导致。
            • 714：音乐文件播放失败。该状态可能由 reason 701、702、或 703 导致。
          • reason: number

            音乐文件播放状态改变的原因：

            • 701：音乐文件打开出错。例如，本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL。
            • 702：音乐文件打开太频繁。如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。
            • 703：音乐文件播放中断。
            • 720：成功调用 startAudioMixing 播放音乐文件。
            • 721：音乐文件完成一次循环播放。
            • 722：音乐文件开始新的一次循环播放。
            • 723：音乐文件完成所有循环播放。
            • 724：成功调用 stopAudioMixing 停止播放音乐文件。
            • 725：成功调用 pauseAudioMixing 暂停播放音乐文件。
            • 726：成功调用 resumeAudioMixing 恢复播放音乐文件。

          Returns void

    Returns this

  • 远端音乐文件播放已开始回调。

    当远端有用户调用 startAudioMixing 播放本地音乐文件，SDK 会触发该回调。

    Parameters

    • evt: "remoteAudioMixingBegin"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 远端音乐文件播放已结束回调。

    Parameters

    • evt: "remoteAudioMixingEnd"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 本地音效文件播放已结束回调。

    当播放音效结束后，会触发该回调。

    Parameters

    • evt: "audioEffectFinished"
    • cb: function
        • (soundId: number): void

        • Parameters

          • soundId: number

            指定音效的 ID。每个音效均有唯一的 ID。

          Returns void

    Returns this

  • 视频设备变化回调。

    该回调提示系统视频设备状态发生改变，比如被拔出或移除。如果设备已使用外接摄像头采集，外接摄像头被拔开后，视频会中断。

    Parameters

    • evt: "videoDeviceStateChanged"
    • cb: function
        • (deviceId: string, deviceType: number, deviceState: number): void

        • Parameters

          • deviceId: string

            设备 ID

          • deviceType: number

            设备类型，详见 MediaDeviceType

          • deviceState: number

            设备状态：

            • macOS：
              • 0: 设备就绪
              • 1: 设备被拔出
            • Windows：
              • 0：设备就绪
              • 1：设备正在使用
              • 2：设备被禁用
              • 4：没有此设备
              • 8：设备被拔出
              • 16：不推荐使用该设备

          Returns void

    Returns this

  • 通话中每个用户的网络上下行 last mile 质量报告回调。

    该回调描述每个用户在通话中的 last mile 网络状态，其中 last mile 是指设备到声网边缘服务器的网络状态。

    该回调每 2 秒触发一次。如果远端有多个用户，该回调每 2 秒会被触发多次。

    Parameters

    • evt: "networkQuality"
    • cb: function

        • Parameters

          • uid: number

            用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。 当 uid 为 0 时，返回的是本地用户的网络质量

          • txquality: AgoraNetworkQuality

            该用户的上行网络质量，基于上行发送码率、上行丢包率、平均往返时延和网络 抖动计算。

          • rxquality: AgoraNetworkQuality

            该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。

          Returns void

    Returns this

  • 通话前网络上下行 last mile 质量报告回调。

    该回调描述本地用户在加入频道前的 last mile 网络探测的结果，其中 last mile 是指设备到声网边缘服务器的网络状态。

    在调用 enableLastmileTest 之后，该回调函数每 2 秒触发一次。如果远端有多个用户/主播，该回调每 2 秒会被触发多次。

    Parameters

    • evt: "lastMileQuality"
    • cb: function

        • Parameters

          • quality: AgoraNetworkQuality

            网络上下行质量，基于上下行网络的丢包率和抖动计算，探测结果主要反映上行网络的状态。

          Returns void

    Returns this

  • 通话前网络质量探测报告回调。

    在调用 startLastmileProbeTest 之后，SDK 会在约 30 秒内返回该回调。

    Parameters

    Returns this

  • 已显示本地视频首帧回调。

    本地视频首帧显示在本地视图上时，SDK 会触发此回调。

    Parameters

    • evt: "firstLocalVideoFrame"
    • cb: function
        • (width: number, height: number, elapsed: number): void

        • Parameters

          • width: number

            本地渲染视频的宽 (px)

          • height: number

            本地渲染视频的高 (px)

          • elapsed: number

            从本地调用 joinChannel 到发生此事件过去的时间（毫秒)

          Returns void

    Returns this

  • deprecated

    这个回调已被废弃，请改用 remoteVideoStateChanged 回调。

    已接收到远端视频并完成解码回调。

    引擎收到第一帧远端视频流并解码成功时，触发此调用。有两种情况：

    • 远端用户首次上线后发送视频
    • 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括：
      • 远端用户离开频道
      • 远端用户掉线
      • 远端用户调用 muteLocalVideoStream 方法停止发送本地视频流
      • 远端用户调用 disableVideo 方法关闭视频模块

    Parameters

    • evt: "addStream"
    • cb: function
        • (uid: number, elapsed: number): void

        • Parameters

          • uid: number

            用户 ID，指定是哪个用户的视频流

          • elapsed: number

            从本地调用 joinChannel 到发生此事件过去的时间（毫秒)

          Returns void

    Returns this

  • 本地或远端视频大小和旋转信息发生改变回调。

    Parameters

    • evt: "videoSizeChanged"
    • cb: function
        • (uid: number, width: number, height: number, rotation: number): void

        • Parameters

          • uid: number

            图像尺寸和旋转信息发生变化的用户的用户 ID（本地用户的 uid 为 0）

          • width: number

            视频流的宽度（px）

          • height: number

            视频流的高度（px）

          • rotation: number

            旋转信息 [0, 360]

          Returns void

    Returns this

  • depreacted

    该回调已废弃，请改用 remoteVideoStateChanged。

    已显示首帧远端视频回调。

    第一帧远端视频显示在视图上时，触发此调用。

    Parameters

    • evt: "firstRemoteVideoFrame"
    • cb: function
        • (uid: number, width: number, height: number, elapsed: number): void

        • Parameters

          • uid: number

            用户 ID，指定是哪个用户的视频流

          • width: number

            视频流宽（px）

          • height: number

            视频流高（px）

          • elapsed: number

            从本地调用 joinChannel 到发生此事件过去的时间（毫秒)

          Returns void

    Returns this

  • 已接收到远端视频并完成解码回调。

    SDK 收到第一帧远端视频流并解码成功时，触发此调用。

    Parameters

    • evt: "firstRemoteVideoDecoded"
    • cb: function
        • (uid: number, width: number, height: number, elapsed: number): void

        • Parameters

          • uid: number

            用户 ID，指定是哪个用户的视频流。

          • width: number

            视频流宽（px）。

          • height: number

            视频流高（px）。

          • elapsed: number

            从本地调用 joinChannel 开始到该回调触发的延迟（毫秒)。

          Returns void

    Returns this

  • 远端用户（通信场景）/主播（直播场景）加入当前频道回调。

    • 通信场景下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
    • 直播场景下，该回调提示有主播加入了频道，并返回该主播的 ID。如果在加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。声网建议连麦主播不超过 17 人。

    该回调在如下情况下会被触发：

    • 远端用户/主播调用 joinChannel 方法加入频道
    • 远端用户加入频道后调用 setClientRole 将用户角色改变为主播
    • 远端用户/主播网络中断后重新加入频道
    note

    直播场景下

    • 主播间能相互收到新主播加入频道的回调，并能获得该主播的 uid
    • 观众也能收到新主播加入频道的回调，并能获得该主播的 uid
    • 当 Web 端加入直播频道时，只要 Web 端有推流，SDK 会默认该 Web 端为主播，并触发该回调。

    Parameters

    • evt: "userJoined"
    • cb: function
        • (uid: number, elapsed: number): void

        • Parameters

          • uid: number

            新加入频道的远端用户/主播 ID

          • elapsed: number

            从本地调用 joinChannel 到发生此事件过去的时间（毫秒)

          Returns void

    Returns this

  • 远端用户离开当前频道回调。

    deprecated

    该回调已废弃，请改用 userOffline。

    用户离开频道有两个原因：

    • 正常离开的时候，远端用户/主播会发送类似“再见”的消息。接收此消息后，判断用户离开频道。
    • 超时掉线的依据是，在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。声网建议使用信令系统来做可靠的掉线检测。

    Parameters

    • evt: "removeStream"
    • cb: function
        • (uid: number, reason: number): void

        • Parameters

          • uid: number

            离线用户或主播的用户 ID。

          • reason: number

            离线原因

            • 0：用户主动离开。
            • 1：因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。
            • 2：用户身份从主播切换为观众。

          Returns void

    Returns this

  • 远端用户（通信场景）/主播（直播场景）离开当前频道回调。

    用户离开频道有两个原因，即正常离开和超时掉线：

    • 正常离开的时候，远端用户/主播会收到类似“再见”的消息，接收此消息后，判断用户离开频道
    • 超时掉线的依据是，在一定时间内（约 20 秒），用户没有收到对方 的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。Agora 建议使用信令系统 来做可靠的掉线检测

    Parameters

    • evt: "userOffline"
    • cb: function
        • (uid: number, reason: number): void

        • Parameters

          • uid: number

            主播 ID

          • reason: number

            离线原因

            • 0：用户主动离开
            • 1：因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方 主动离开本方没收到对方离开消息而误判为超时掉线
            • 2：（直播场景下）用户身份从主播切换为观众

          Returns void

    Returns this

  • deprecated

    该回调已废弃，请改用 remoteAudioStateChanged。

    远端用户暂停/重新发送音频流回调。

    该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

    note

    当频道内的主播超过 20 人时，该回调不生效。

    Parameters

    • evt: "userMuteAudio"
    • cb: function
        • (uid: number, muted: boolean): void

        • Parameters

          • uid: number

            远端用户 ID

          • muted: boolean

            该用户是否暂停发送音频流

            • true：该用户已暂停发送音频流
            • false：该用户已重新发送音频流

          Returns void

    Returns this

  • 远端用户暂停/重新发送视频流回调。

    该回调是由远端用户调用 muteLocalVideoStream 方法关闭或开启音频发送触发的。

    note

    当频道内的主播超过 20 人时，该回调不生效。

    Parameters

    • evt: "userMuteVideo"
    • cb: function
        • (uid: number, muted: boolean): void

        • Parameters

          • uid: number

            远端用户 ID

          • muted: boolean

            该用户是否暂停发送视频流

            • true：该用户已暂停发送视频流
            • false：该用户已重新发送视频流

          Returns void

    Returns this

  • deprecated

    这个回调已被废弃，请改用 remoteVideoStateChanged 回调。

    远端用户开启/关闭视频模块回调。

    该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。

    note

    声网视频模块指视频处理过程，而不是 SDK 中的模块实物。发送视频流时，视频模块指视频采集、前处理、编码等处理过程；接收视频流时，视频模块指视频解码、后处理、渲染/播放等处理过程。

    Parameters

    • evt: "userEnableVideo"
    • cb: function
        • (uid: number, enabled: boolean): void

        • Parameters

          • uid: number

            用户 ID

          • enabled: boolean

            该用户是否开启或关闭视频模块：

            • true：该用户已启用视频模块。启用后，该用户可以进行视频通话或直播。
            • false：该用户已关闭视频模块。关闭后，该用户只能进行语音通话或直播，不能显示、发送自己的视频，也不能接收、显示别人的视频。

          Returns void

    Returns this

  • deprecated

    这个回调已被废弃，请改用 remoteVideoStateChanged 回调。

    远端用户开启/关闭本地视频采集。

    该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。

    Parameters

    • evt: "userEnableLocalVideo"
    • cb: function
        • (uid: number, enabled: boolean): void

        • Parameters

          • uid: number

            用户 ID

          • enabled: boolean

            该用户是否开启或关闭本地视频采集：

            • true：该用户已启用本地视频采集。启用后，其他用户可以接收到该用户的视频流。
            • false：该用户已关闭视频采集。关闭后，该用户仍然可以接收其他用户的视频流，但其他用户接收不到该用户的视频流。

          Returns void

    Returns this

  • deprecated

    该回调已废弃。请改用 localVideoStateChanged 回调。

    摄像头就绪回调。

    Parameters

    • evt: "cameraReady"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • deprecated

    该回调已废弃。请改用 localVideoStateChanged 回调。

    视频停止播放回调。

    Parameters

    • evt: "videoStopped"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 网络连接中断，且 SDK 无法在 10 秒内连接服务器回调。

    note

    SDK 在调用 joinChannel 后，无论是否加入成功，只要 10 秒和服务器无法连接 就会触发该回调。如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

    Parameters

    • evt: "connectionLost"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • deprecated

    该回调已废弃。请改用 connectionStateChanged 回调。

    网络连接已被服务器禁止回调。

    当你被服务端禁掉连接的权限时，会触发该回调。

    Parameters

    • evt: "connectionBanned"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 接收到对方数据流消息的回调。

    该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。

    Parameters

    • evt: "streamMessage"
    • cb: function
        • (uid: number, streamId: number, msg: string, len: number): void

        • Parameters

          • uid: number

            用户 ID

          • streamId: number

            数据流 ID

          • msg: string

            接收到的流消息

          • len: number

            流消息数据长度

          Returns void

    Returns this

  • 接收对方数据流小时发生错误回调。

    该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。

    Parameters

    • evt: "streamMessageError"
    • cb: function
        • (uid: number, streamId: number, code: number, missed: number, cached: number): void

        • Parameters

          • uid: number

            用户 ID

          • streamId: number

            数据流 ID

          • code: number
          • missed: number

            丢失的消息数量

          • cached: number

            数据流中断后，后面缓存的消息数量

          Returns void

    Returns this

  • 媒体引擎成功启动的回调。

    Parameters

    • evt: "mediaEngineStartCallSuccess"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • Token 已过期回调。

    调用 joinChannel 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中 SDK 可能由于网络原因和服务器失去连接，重连时可能需要新的 Token。

    该回调通知 App 需要生成新的 Token，并需调用 renewToken 为 SDK 指定新的 Token。

    Parameters

    • evt: "requestChannelKey"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 已发送本地音频首帧回调。

    deprecated

    该回调自 v3.2.0 已废弃，请改用 firstLocalAudioFramePublished。

    Parameters

    • evt: "firstLocalAudioFrame"
    • cb: function
        • (elapsed: number): void

        • Parameters

          • elapsed: number

            从本地用户调用 joinChannel 方法直至该回调被触发的延迟（毫秒）。

          Returns void

    Returns this

  • deprecated

    该回调已废弃，请改用 remoteAudioStateChanged。

    已接收远端音频首帧回调。

    Parameters

    • evt: "firstRemoteAudioFrame"
    • cb: function
        • (uid: number, elapsed: number): void

        • Parameters

          • uid: number

            发送音频帧的远端用户的 ID

          • elapsed: number

            从调用 joinChannel 方法直至该回调被触发的延迟（毫秒）

          Returns void

    Returns this

  • deprecated

    该回调已废弃，请改用 remoteAudioStateChanged。

    已解码远端音频首帧的回调

    SDK 完成远端音频首帧解码，并发送给音频模块用以播放时，会触发此回调。有两种情况：

    • 远端用户首次上线后发送音频
    • 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
      • 远端用户离开频道
      • 远端用户掉线
      • 远端用户停止发送音频流（通过调用 muteLocalAudioStream 方法）
      • 远端用户关闭音频 （通过调用 disableAudio 方法）

    Parameters

    • evt: "firstRemoteAudioDecoded"
    • cb: function
        • (uid: number, elapsed: number): void

        • Parameters

          • uid: number

            用户 ID，指定是哪个用户的音频流

          • elapsed: number

            从本地用户调用 joinChannel 方法加入频道直至该回调触发的延迟，单位为毫秒

          Returns void

    Returns this

  • 检测到活跃用户回调。

    如果用户开启了 enableAudioVolumeIndication 功能，则当音量检测模块监测到频道内有新的活跃用户说话时，会通过本回调返回该用户的 uid。

    Parameters

    • evt: "activeSpeaker"
    • cb: function
        • (uid: number): void

        • Parameters

          • uid: number

            当前时间段内声音最大的用户的 uid（本地用户 uid 为 0）

          Returns void

    Returns this

  • 用户角色已切换回调。

    回调由本地用户在加入频道后调用 setClientRole 改变用户角色触发的。

    Parameters

    Returns this

  • 回放、录音设备、或 App 的音量发生改变。

    Parameters

    • evt: "audioDeviceVolumeChanged"
    • cb: function

        • Parameters

          • deviceType: MediaDeviceType

            设备类型

          • volume: number

            当前音量（分贝）。取值范围 [0, 255]

          • muted: boolean

            音频设备是否为静音状态

            • true：音频设备已静音
            • false：音频设备未被静音

          Returns void

    Returns this

  • 屏幕共享对象成功加入频道回调。

    Parameters

    • evt: "videoSourceJoinedSuccess"
    • cb: function
        • (uid: number): void

        • Parameters

          • uid: number

            该对象的用户 ID

          Returns void

    Returns this

  • 屏幕共享对象 Token 已过期回调。

    Parameters

    • evt: "videoSourceRequestNewToken"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 屏幕共享对象离开频道回调。

    Parameters

    • evt: "videoSourceLeaveChannel"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • Parameters

    Returns this

  • 通话中本地音频流的统计信息回调。

    Parameters

    • evt: "videoSourceLocalAudioStats"
    • cb: function

    Returns this

  • 通话中本地视频流的统计信息回调。

    note

    如果你此前调用 enableDualStreamMode 方法，则本回调描述本地设备发送的视频大流的统计信息。

    Parameters

    • evt: "videoSourceLocalVideoStats"
    • cb: function

    Returns this

  • 本地或远端视频大小和旋转信息发生改变回调。

    Parameters

    • evt: "videoSourceVideoSizeChanged"
    • cb: function
        • (uid: number, width: number, height: number, rotation: number): void

        • Parameters

          • uid: number

            图像尺寸和旋转信息发生变化的用户的用户 ID（本地用户的 uid 为 0）

          • width: number

            视频流的宽度（px）

          • height: number

            视频流的高度（px）

          • rotation: number

            旋转信息 [0, 360]

          Returns void

    Returns this

  • 本地视频状态发生改变回调

    本地视频的状态发生改变时，SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因，方便排查问题。

    SDK 会在如下情况触发 localVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) 回调：

    • 应用退到后台，系统回收摄像头。
    • 摄像头正常启动，但连续 4 秒都没有输出采集的视频。

    摄像头输出采集的视频帧时，如果连续 15 帧中，所有视频帧都一样，SDK 触发 localVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) 回调。 注意：帧重复检测仅针对分辨率大于 200 × 200，帧率大于等于 10 fps，码率小于 20 Kbps 的视频帧。

    note

    对某些机型而言，当本地视频采集设备正在使用中时，SDK 不会在本地视频状态发生改变时触发该回调，你需要自行做超时判断。

    Parameters

    Returns this

  • 本地音频状态发生改变回调。

    本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态）， SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时， 该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。

    note

    当状态为 LOCAL_AUDIO_STREAM_STATE_FAILED(3) 时， 你可以在 err 参数中查看返回的错误信息。

    Parameters

    Returns this

  • 远端用户视频流状态发生改变回调。

    Parameters

    • evt: "remoteVideoStateChanged"
    • cb: function

    Returns this

  • 相机对焦区域已改变回调。

    Parameters

    • evt: "cameraFocusAreaChanged"
    • cb: function
        • (x: number, y: number, width: number, height: number): void

        • Parameters

          • x: number

            发生改变的对焦区域相对于左上角的 x 坐标。

          • y: number

            发生改变的对焦区域相对于左上角的 y 坐标。

          • width: number

            发生改变的对焦区域的宽度 (px)。

          • height: number

            发生改变的对焦区域的高度 (px)。

          Returns void

    Returns this

  • 摄像头曝光区域已改变回调。

    Parameters

    • evt: "cameraExposureAreaChanged"
    • cb: function
        • (x: number, y: number, width: number, height: number): void

        • Parameters

          • x: number

            发生改变的曝光区域相对于左上角的 x 坐标。

          • y: number

            发生改变的曝光区域相对于左上角的 y 坐标。

          • width: number

            发生改变的曝光区域的宽度 (px)。

          • height: number

            发生改变的曝光区域的高度 (px)。

          Returns void

    Returns this

  • Token 服务即将过期回调。

    在调用 joinChannel 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒 App 更新 Token。当收到该回调时，用户需要重新在服务端生成新的 Token，然后调用 renewToken 将新生成的 Token 传给 SDK。

    Parameters

    • evt: "tokenPrivilegeWillExpire"
    • cb: function
        • (token: string): void

        • Parameters

          • token: string

            即将服务失效的 Token

          Returns void

    Returns this

  • deprecated

    该回调已废弃，请改用 rtmpStreamingStateChanged。

    开启旁路推流的结果回调。

    该回调返回 addPublishStreamUrl 方法的调用结果。用于通知主播是否推流成功。如果不成功，你可以在 error 参数中查看详细的错误信息。

    Parameters

    • evt: "streamPublished"
    • cb: function
        • (url: string, error: number): void

        • Parameters

          • url: string

            新增的推流地址。

          • error: number

            详细的错误信息

            • 0：推流成功
            • 1：推流失败
            • 2：参数错误。如果你在调用 addPublishStreamUrl 前没有调用 setLiveTranscoding 配置 LiveTranscoding，SDK 会返回该错误
            • 10：推流超时未成功
            • 19：推流地址已经在推流
            • 130：推流已加密不能推流

          Returns void

    Returns this

  • 停止旁路推流的结果回调。

    该回调返回 removePublishStreamUrl 方法的调用结果。用于通知主播是否停止推流成功。

    Parameters

    • evt: "streamUnpublished"
    • cb: function
        • (url: string): void

        • Parameters

          • url: string

            主播停止推流的 RTMP 地址。

          Returns void

    Returns this

  • 旁路推流状态发生改变回调。

    该回调返回本地用户调用 addPublishStreamUrl 或 removePublishStreamUrl 方法的结果。

    旁路推流状态发生改变时，SDK 会触发该回调，并在回调中明确状态发生改变的 URL 地址及 当前推流状态。该回调方便推流用户了解当前的推流状态；推流出错时，你可以通过返回的错误码 了解出错的原因，方便排查问题。

    Parameters

    • evt: "rtmpStreamingStateChanged"
    • cb: function
        • (url: string, state: number, code: number): void

        • Parameters

          • url: string

            推流状态发生改变的 URL 地址

          • state: number

            推流状态：

            • 0: 推流未开始或已结束。成功调用 removePublishStreamUrl 后会返回该状态。
            • 1: 正在连接声网推流服务器和 RTMP 服务器。调用 addPublishStreamUrl 后会返回该状态。
            • 2: 推流正在进行。成功推流后，会返回该状态。
            • 3: 正在恢复推流。当 CDN 出现异常，或推流短暂中断时，SDK 会自动尝试恢复推流，并返回该状态。
              • 如成功恢复推流，则进入状态 2。
              • 如服务器出错或 60 秒内未成功恢复，则进入状态 4。如果觉得 60 秒太长，也可以主动调用 addPublishStreamUrl，再调用 removePublishStreamUrl 尝试重连。
            • 4: 推流失败。失败后，你可以通过返回的错误码排查错误原因，也可以再次调用 addPublishStreamUrl 重新尝试推流。
            • 5: SDK 正在与声网推流服务器和 CDN 服务器断开连接。 当你调用 remove 或 stop 方法正常结束推流时，SDK 会依次报告推流状态为 DISCONNECTING、IDLE。
          • code: number

            推流错误码：

            • 0: 推流成功。
            • 1: 参数无效。请检查输入参数是否正确。
            • 2: 推流已加密，不能推流。
            • 3: 推流超时未成功。可调用 addPublishStreamUrl 重新推流。
            • 4: 推流服务器出现错误。请调用 addPublishStreamUrl 重新推流。
            • 5: RTMP 服务器出现错误。
            • 6: 推流请求过于频繁。
            • 7: 单个主播的推流地址数目达到上线 10。请删掉一些不用的推流地址再增加推流地址。
            • 8: 主播操作不属于自己的流。例如更新其他主播的流参数、停止其他主播的流。请检查 App 逻辑。
            • 9: 服务器未找到这个流。
            • 10: 推流地址格式有错误。请检查推流地址格式是否正确。
            • 11: 用户角色不是主播，该用户无法使用推流功能。请检查你的应用代码逻辑。
            • 13: 非转码推流情况下，调用了 updateRtmpTranscoding 或 setLiveTranscoding 方法更新转码属性。请检查你的应用代码逻辑。
            • 14: 主播的网络出错。
            • 15: 你的 App ID 没有使用声网推流服务的权限。请参考前提条件开启推流服务。
            • 100: 推流已正常结束。当你调用 removePublishStreamUrl 结束推流后，SDK 会返回该值。

          Returns void

    Returns this

  • 旁路推流设置被更新回调。该

    回调用于通知主播 CDN 转码已成功更新。

    setLiveTranscoding 方法中的转码合图参数（LiveTranscoding）更新时，transcodingUpdated 回调会被触发并向主播报告更新信息。

    note

    首次调用 setLiveTranscoding 方法设置转码合图参数（LiveTranscoding）时，不会触发此回调。

    Parameters

    • evt: "transcodingUpdated"
    • cb: function
        • (): void

        • Returns void

    Returns this

  • 本地发布流已回退为音频流回调。

    如果你调用了设置本地推流回退选项 setLocalPublishFallbackOption 并将 option 设置为 2 时，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。

    如果本地推流已回退为音频流，远端的 App 上会收到 userMuteVideo 的回调事件。

    Parameters

    • evt: "localPublishFallbackToAudioOnly"
    • cb: function
        • (isFallbackOrRecover: boolean): void

        • Parameters

          • isFallbackOrRecover: boolean

            本地推流已回退或恢复：

            • true：由于网络环境不理想，本地发布的媒体流已回退为音频流
            • false：由于网络环境改善，发布的音频流已恢复为音视频流

          Returns void

    Returns this

  • 远端订阅流已回退为音频流回调。

    如果你调用了设置远端订阅流回退选项 setRemoteSubscribeFallbackOption 并将 option 设置为 2 时， 当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。

    远端订阅流因弱网环境不能同时满足音视频而回退为小流时，你可以使用 remoteVideoStats 回调来监控远端视频大小流的切换。

    Parameters

    • evt: "remoteSubscribeFallbackToAudioOnly"
    • cb: function
        • (uid: number, isFallbackOrRecover: boolean): void

        • Parameters

          • uid: number

            远端用户的 ID

          • isFallbackOrRecover: boolean

            远端订阅流已回退或恢复：

            • true：由于网络环境不理想，远端订阅流已回退为音频流
            • false：由于网络环境改善，订阅的音频流已恢复为音视频流

          Returns void

    Returns this

  • deprecated

    这个回调已被废弃，请改用 localAuidoStateChanged 回调。

    麦克风状态已改变回调。

    该回调由本地用户开启或关闭本地音频采集触发的。

    Parameters

    • evt: "microphoneEnabled"
    • cb: function
        • (enabled: boolean): void

        • Parameters

          • enabled: boolean

            是否开启麦克风：

            • true：麦克风已启用
            • false：麦克风已禁用

          Returns void

    Returns this

  • 网络连接状态已改变回调。

    该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态，和引起网络状态改变的原因。

    Parameters

    Returns this

  • 本地网络类型发生改变回调。

    当连接中断时，该回调能辨别引起中断的原因是网络切换还是网络条件不好。

    Parameters

    Returns this

  • 本地用户成功注册 User Account 回调。

    本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account，或调用 joinChannelWithUserAccount 加入频道后，SDK 会触发该回调，并告知本地用户的 UID 和 User Account。包含如下参数：

    Parameters

    • evt: "localUserRegistered"
    • cb: function
        • (uid: number, userAccount: string): void

        • Parameters

          • uid: number

            本地用户的 UID

          • userAccount: string

            本地用户的 User account

          Returns void

    Returns this

  • 远端用户信息已更新回调。

    远端用户加入频道后， SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发该回调。

    Parameters

    • evt: "userInfoUpdated"
    • cb: function
        • (uid: number, userInfo: UserInfo): void

        • Parameters

          • uid: number

            远端用户的 ID

          • userInfo: UserInfo

            标识用户信息的 UserInfo 对象，包含用户 UID 和 User account

          Returns void

    Returns this

  • 本地视频状态发生改变回调

    本地视频的状态发生改变时，SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因，方便排查问题。

    SDK 会在如下情况触发 localVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) 回调：

    • 应用退到后台，系统回收摄像头。
    • 摄像头正常启动，但连续 4 秒都没有输出采集的视频。

    摄像头输出采集的视频帧时，如果连续 15 帧中，所有视频帧都一样，SDK 触发 localVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) 回调。 注意：帧重复检测仅针对分辨率大于 200 × 200，帧率大于等于 10 fps，码率小于 20 Kbps 的视频帧。

    note

    对某些机型而言，当本地视频采集设备正在使用中时，SDK 不会在本地视频状态发生改变时触发该回调，你需要自行做超时判断。

    Parameters

    Returns this

  • 本地音频状态发生改变回调。

    本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态）， SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时， 该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。

    note

    当状态为 LOCAL_AUDIO_STREAM_STATE_FAILED(3) 时， 你可以在 err 参数中查看返回的错误信息。

    Parameters

    Returns this

  • 远端音频流状态发生改变回调。

    远端用户/主播音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

    Parameters

    • evt: "remoteAudioStateChanged"
    • cb: function

    Returns this

  • 跨频道媒体流转发状态发生改变回调。

    当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的 错误信息。

    Parameters

    Returns this

  • 跨频道媒体流转发事件回调。

    该回调报告跨频道媒体流转发过程中发生的事件。详见 ChannelMediaRelayEvent

    Parameters

    Returns this

  • 媒体附属信息接收成功回调。

    发送方调用 sendMetadata 方法发送媒体附属信息后，当接收方接收到该媒体附属信息 时，SDK 触发本回调向接收方报告媒体附属信息。

    Parameters

    • evt: "receiveMetadata"
    • cb: function

        • Parameters

          • metadata: Metadata

            媒体附属信息。

          Returns void

    Returns this

  • 媒体附属信息发送成功回调。

    发送方调用 sendMetadata 方法成功发送媒体附属信息后，SDK 触发本回调向发送方 报告媒体附属信息。

    Parameters

    • evt: "sendMetadataSuccess"
    • cb: function

        • Parameters

          • metadata: Metadata

            媒体附属信息。

          Returns void

    Returns this

  • 已发布本地音频首帧回调。

    since

    v3.2.0

    SDK 会在以下三种时机触发该回调：

    Parameters

    • evt: "firstLocalAudioFramePublished"
    • cb: function
        • (elapsed: number): void

        • Parameters

          • elapsed: number

            从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

          Returns void

    Returns this

  • 已发布本地视频首帧回调。

    since

    v3.2.0

    SDK 会在以下三种时机触发该回调：

    Parameters

    • evt: "firstLocalVideoFramePublished"
    • cb: function
        • (elapsed: number): void

        • Parameters

          • elapsed: number

            从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

          Returns void

    Returns this

  • 旁路推流事件回调。

    since

    v3.2.0

    Parameters

    • evt: "rtmpStreamingEvent"
    • cb: function

    Returns this

  • 音频发布状态改变回调。

    since

    v3.2.0

    Parameters

    • evt: "audioPublishStateChanged"
    • cb: function

    Returns this

  • 视频发布状态改变回调。

    since

    v3.2.0

    Parameters

    • evt: "videoPublishStateChanged"
    • cb: function

    Returns this

  • 音频订阅状态发生改变回调。

    since

    v3.2.0

    Parameters

    • evt: "audioSubscribeStateChanged"
    • cb: function

    Returns this

  • 视频订阅状态发生改变回调。

    since

    v3.2.0

    Parameters

    • evt: "videoSubscribeStateChanged"
    • cb: function

    Returns this

  • 预留

    Parameters

    • evt: "uploadLogResult"
    • cb: function
        • (requestId: string, success: boolean, reason: number): void

        • Parameters

          • requestId: string
          • success: boolean
          • reason: number

          Returns void

    Returns this

  • 报告虚拟背景是否成功开启。（beta 功能）

    since

    v3.4.5

    调用 enableVirtualBackground 后，SDK 触发该回调报告虚拟背景是否成功开启。

    note

    如果虚拟背景中自定义的背景图为 PNG、JPG 格式的图片，该回调的触发时机会延迟到图片 读取完毕。

    Parameters

    • evt: "virtualBackgroundSourceEnabled"
    • cb: function

    Returns this

  • 报告本地用户的语音音调。

    since

    v3.7.0

    开启本地音频采集并调用 enableLocalVoicePitchCallback 后，SDK 会按 enableLocalVoicePitchCallback 中设置的时间间隔触发本回调，报告本地用户的语音音调。

    note

    启用该功能后，如果用户关闭了本地音频采集，例如，调用了 enableLocalAudio(false)，SDK 会停止发送本回调。

    Parameters

    • evt: "localVoicePitchInHz"
    • cb: function
        • (pitchInHz: number): void

        • Parameters

          • pitchInHz: number

            本地用户的语音音调，单位为 Hz。

          Returns void

    Returns this

  • 直播场景下切换用户角色失败回调。

    since

    v3.7.0

    直播场景下，本地用户加入频道后调用 setClientRole 切换用户角色失败时，SDK 会触发该回调，报告切换失败的原因和当前的用户角色。

    Parameters

    Returns this

  • 报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

    since

    v3.7.0

    调用 enableWirelessAccelerate (true) 开启 Wi-Fi 加速功能后，当 Wi-Fi 连接质量不佳时，SDK 会触发该回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

    note

    声网强烈建议你在 app 中展示将该回调报告的 action 和 wlAccMsg，提示用户采取网络优化措施，以获得更好的音视频体验。

    Parameters

    • evt: "wlAccMessage"
    • cb: function

        • Parameters

          • reason: WLACC_MESSAGE_REASON

            Wi-Fi 连接质量不佳的原因。详见 WLACC_MESSAGE_REASON 。

          • action: WLACC_SUGGEST_ACTION

            改善 Wi-Fi 连接质量的操作建议。详见 WLACC_SUGGEST_ACTION 。

          • wlAccMsg: string

            根据 action 的值提供的详细帮助信息：

            • 当 action 为 WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI，该参数的值为 NULL。
            • 当 action 为 WLACC_SUGGEST_ACTION_CONNECT_SSID，该参数的值为推荐用户连接的网络名称（SSID）。
            • 当 action 为 WLACC_SUGGEST_ACTION_CHECK_5G，该参数的值为开启路由器 5G 频道的操作步骤的链接。
            • 当 action 为 WLACC_SUGGEST_ACTION_MODIFY_SSID，该参数的值为修改网络名称（SSID）的操作步骤的链接。

          Returns void

    Returns this

  • 报告 Wi-Fi 加速效果。

    since

    v3.7.0

    调用 enableWirelessAccelerate (true) 开启 Wi-Fi 加速功能后，SDK 每隔两秒触发一次该回调，报告当前的 Wi-Fi 加速效果和自加入频道后平均的 Wi-Fi 加速效果。Wi-Fi 加速效果用端到端延时、丢包率和音视频卡顿率三个指标下降的百分比来衡量。

    Parameters

    Returns this

  • 代理连接状态回调。

    since

    v3.7.0

    通过该回调你可以监听 SDK 连接代理的状态。例如，当用户调用 setCloudProxy 设置代理并成功加入频道后， SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 joinChannel 到触发该回调经过的时间等。

    Parameters

    • evt: "proxyConnected"
    • cb: function
        • (channel: string, uid: number, proxyType: PROXY_TYPE, localProxyIp: string, elapsed: number): void

        • Parameters

          • channel: string

            频道名称。

          • uid: number

            用户 ID。

          • proxyType: PROXY_TYPE

            连接上的代理类型。详见 PROXY_TYPE 。

          • localProxyIp: string

            预留参数，暂不支持。

          • elapsed: number

            从调用 joinChannel 到 SDK 触发该回调的经过的时间（毫秒）。

          Returns void

    Returns this

  • 预留接口，暂不支持。

    Parameters

    • evt: "agoraVideoRawData"
    • cb: function
        • (info: object): void

        • Parameters

          • info: object
            • channelId: string
            • header: any
            • type: number
            • udata: Uint8Array
            • uid: number
            • vdata: Uint8Array
            • ydata: Uint8Array

          Returns void

    Returns this

  • Parameters

    • evt: string
    • listener: Function

    Returns this

pauseAllChannelMediaRelay

  • pauseAllChannelMediaRelay(): number

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

    since

    v3.6.1.4

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

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

    note

    该方法需要在 startChannelMediaRelay 后调用。

    Returns number

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

pauseAllEffects

  • pauseAllEffects(): number

  • 暂停所有音效文件播放。

    Returns number

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

pauseAudio

  • pauseAudio(): number
  • deprecated

    该方法已废弃。请改用 disableAudio 禁用频道内的音频功能。

    Returns number

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

pauseAudioMixing

  • pauseAudioMixing(): number

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

    Returns number

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

pauseEffect

  • pauseEffect(soundId: number): number

  • 暂停音效文件播放。

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID

    Returns number

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

playEffect

  • playEffect(soundId: number, filePath: string, loopcount: number, pitch: number, pan: number, gain: number, publish: boolean, startPos?: undefined | number): number

  • 播放指定的本地或在线音效文件。

    你可以多次调用该方法，传入不同的 soundId 和 filePath，同时播放多个音效文件。 为获得最佳用户体验，Agora 推荐同时播放的音效文件不超过 3 个。

    音效文件播放结束后，SDK 会触发 audioEffectFinished 回调。

    note

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

    Parameters

    • soundId: number

      音效的 ID。每个音效的 ID 具有唯一性。 如果你已通过 preloadEffect 将音效加载至内存， 请确保该参数与 preloadEffect 中设置的 soundId 相同。

    • filePath: string

      音效文件的绝对路径或 URL 地址，需精确到文件名及后缀。 例如：C:\music\audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Supported Media Formats in Media Foundation。 如果你已通过 preloadEffect 将音效加载至内存， 请确保该参数与 preloadEffect 中设置的 filePath 相同。

    • loopcount: number

      音效循环播放的次数。

      • ≥ 0: 循环播放次数。例如，1 表示循环播放 1 次，即总计播放 2 次。
      • -1: 无限循环播放。
    • pitch: number

      音效的音调，取值范围为 [0.5,2.0]。默认值为 1.0，表示原始音调。取值越小，则音调越低。

    • pan: number

      音效的空间位置。取值范围为 [-1.0,1.0]，例如：

      • -1.0: 音效出现在左边
      • 0.0: 音效出现在正前方
      • 1.0: 音效出现在右边
    • gain: number

      音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0，表示原始音量。取值越小，则音量越低。

    • publish: boolean

      是否将音效发布至远端：

      • true: 发布。本地用户和远端用户都能听到音效。
      • false: 不发布。只有本地用户能听到音效。
    • Optional startPos: undefined | number

      音效文件的播放位置，单位为毫秒。

    Returns number

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

preloadEffect

  • preloadEffect(soundId: number, filePath: string): number

  • 预加载音效文件。

    为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannel 前就使用该方法完成音效预加载。 音效文件支持以下音频格式：mp3，aac，m4a，3gp，wav。

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID。

    • filePath: string

      音效文件的绝对路径

    Returns number

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

rate

  • rate(callId: string, rating: number, desc: string): number

  • 给通话评分。

    Parameters

    • callId: string

      通过 getCallId 函数获取的通话 ID

    • rating: number

      给通话的评分，最低 1 分，最高 5 分

    • desc: string

      （非必选项）给通话的描述，可选，长度应小于 800 字节

    Returns number

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

registerLocalUserAccount

  • registerLocalUserAccount(appId: string, userAccount: string): number

  • 注册本地用户 User account。

    该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。 成功注册 User Account 后，本地会触发 onLocalUserRegistered 回调，告知本地用户的 UID 和 User Account。

    该方法为可选。如果你希望用户使用 User Account 加入频道，可以选用以下两种方式：

    两种方式的区别在于，提前调用 registerLocalUserAccount，可以缩短使用 joinChannelWithUserAccount 进入频道的时间。

    为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 RTC Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

    note
    • 请确保 userAccount 不能为空，否则该方法不生效。
    • 请确保在该方法中设置的 userAccount 在频道中的唯一性。

    Parameters

    • appId: string

      你的项目在声网控制台注册的 App ID

    • userAccount: string

      用户 User Account。该参数为必填，最大不超过 255 字节，不可填 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）：

      • 26 个小写英文字母 a-z
      • 26 个大写英文字母 A-Z
      • 10 个数字 0-9
      • 空格
      • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

    Returns number

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

registerMediaMetadataObserver

  • registerMediaMetadataObserver(): number

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

    Returns number

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

release

  • release(sync?: boolean): number

  • 释放 AgoraRtcEngine 实例。

    调用该方法后，用户将无法再使用和回调该 SDK 内的其它方法。

    note
    • 该方法需要在子线程中操作。
    • 如需再次使用，必须重新初始化 initialize 一个 AgoraRtcEngine 实例。

    Parameters

    • Default value sync: boolean = false

    Returns number

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

removePublishStreamUrl

  • removePublishStreamUrl(url: string): number

  • 删除旁路推流地址。

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

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

    Parameters

    • url: string

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

    Returns number

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

removeVideoRenderFromHighFPS

  • removeVideoRenderFromHighFPS(uid: number): void

  • 将指定用户的视频从高帧率流中删除。删除后，你可以调用 setVideoRenderFPS 方法对视频流进行控制。

    Parameters

    • uid: number

      用户 ID

    Returns void

renewToken

  • renewToken(newtoken: string): number

  • 更新 Token。

    如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当报告错误码 109或 tokenPrivilegeWillExpire 回调时， 你应重新获取 Token，然后调用该 API 更新 Token，否则 SDK 无法和服务器建立连接。

    Parameters

    • newtoken: string

      新的 Token

    Returns number

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

resizeRender

  • resizeRender(key: "local" | "videosource" | number, channelId: string | undefined): void

  • 更新渲染尺寸。 当视图尺寸发生改变时，该方法可以根据视窗尺寸长宽比更新缩放比例，在收到下一个视频帧时，按照新的比例进行渲染。 该方法可以防止视图不连贯的问题。

    Parameters

    • key: "local" | "videosource" | number

      存储渲染器 Map 的关键标识，如 uid、videoSource 或 local

    • channelId: string | undefined

    Returns void

resumeAllChannelMediaRelay

  • resumeAllChannelMediaRelay(): number

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

    since

    v3.6.1.4

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

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

    note

    该方法需要在 pauseAllChannelMediaRelay 后调用。

    Returns number

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

resumeAllEffects

  • resumeAllEffects(): number

  • 恢复播放所有音效文件。

    Returns number

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

resumeAudio

  • resumeAudio(): number
  • deprecated

    该方法已弃用。请改用 enableAudio 启用频道内的音频功能。

    Returns number

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

resumeAudioMixing

  • resumeAudioMixing(): number

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

    Returns number

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

resumeEffect

  • resumeEffect(soundId: number): number

  • 恢复播放指定音效文件。

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID

    Returns number

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

selectAudioTrack

  • selectAudioTrack(index: number): number

  • 指定当前音乐文件的播放音轨。

    since

    v3.6.1.4

    获取音乐文件的音轨索引后，你可以调用该方法指定任一音轨进行播放。例如，如果一个多音轨文件的 不同音轨存放了不同语言的歌曲，则你可以调用该方法设置音乐文件的播放语言。

    note

    Parameters

    • index: number

      指定的播放音轨。该参数需小于或等于 \ref IRtcEngine::getAudioTrackCount "getAudioTrackCount" 的返回值。

    Returns number

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

sendCustomReportMessage

  • sendCustomReportMessage(id: string, category: string, event: string, label: string, value: number): number

  • 声网提供自定义数据上报和分析服务。

    since

    v3.2.0

    该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据，每条自定义数据 不能超过 256 字节，每个字符串不能超过 100 字节。如需试用该服务，请 联系 sales@agora.io 开通并商定自定义数据格式。

    Parameters

    • id: string
    • category: string
    • event: string
    • label: string
    • value: number

    Returns number

sendMetadata

  • sendMetadata(metadata: Metadata): number

  • 发送媒体附属信息。

    调用 registerMediaMetadataObserver 后，你可以调用本方法来发送媒体附属信息。

    如果发送成功，发送方会收到 sendMetadataSuccess 回调，接收方会收到 receiveMetadata 回调。

    Parameters

    • metadata: Metadata

      媒体附属信息。

    Returns number

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

sendStreamMessage

  • sendStreamMessage(streamId: number, msg: string): number

  • 发送数据流。

    该方法发送数据流消息到频道内所有用户。

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

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

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

    Parameters

    • streamId: number

      数据流 ID，createDataStream 的返回值

    • msg: string

      待发送的数据

    Returns number

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

sendStreamMessageWithArrayBuffer

  • sendStreamMessageWithArrayBuffer(streamId: number, buffer: UInt8ArrayBuffer): number

setAVSyncSource

  • setAVSyncSource(channelId: string, uid: number): number

  • Parameters

    • channelId: string
    • uid: number

    Returns number

setAddonLogFile

  • setAddonLogFile(filepath: string): number

  • Parameters

    • filepath: string

    Returns number

setAudioEffectParameters

  • setAudioEffectParameters(preset: AUDIO_EFFECT_PRESET, param1: number, param2: number): number

  • 设置 SDK 预设人声音效的参数。

    since

    v3.2.0

    调用该方法可以对本地发流用户进行如下设置：

    • 3D 人声音效：设置 3D 人声音效的环绕周期。
    • 电音音效：设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效，Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。

    设置后，频道内所有用户都能听到该效果。

    该方法可以单独使用，也可以搭配 setAudioEffectPreset 使用。搭配使用时， 需要先调用 setAudioEffectPreset 并使用 ROOM_ACOUSTICS_3D_VOICE 或 PITCH_CORRECTION 枚举，再调用该方法使用相同的枚举。 否则，该方法设置的效果会覆盖 setAudioEffectPreset 设置的效果。

    note

    Parameters

    • preset: AUDIO_EFFECT_PRESET

      SDK 预设的音效：

      • 3D 人声音效: ROOM_ACOUSTICS_3D_VOICE.
        • 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置 为 3 或 5，否则该枚举设置无效。
        • 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。
      • 电音音效：PITCH_CORRECTION。为获取更好的人声效果， 建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 4 或 5。
    • param1: number
      • 如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE，则 param1 表示 3D 人声音效的环绕周期。 取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。
      • 如果 preset 设为 PITCH_CORRECTION，则 param1 表示电音音效的基础调式。可设为如下值：
        • 1:（默认）自然大调。
        • 2: 自然小调。
        • 3: 和风小调。
    • param2: number
      • 如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE，你需要将 param2 设置为 0。
      • 如果 preset 设为 PITCH_CORRECTION，则 param2 表示电音音效的主音音高。可设为如下值：
        • 1: A
        • 2: A#
        • 3: B
        • 4:（默认）C
        • 5: C#
        • 6: D
        • 7: D#
        • 8: E
        • 9: F
        • 10: F#
        • 11: G
        • 12: G#

    Returns number

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

setAudioEffectPreset

setAudioMixingDualMonoMode

  • 设置当前音乐文件的声道模式。

    since

    v3.6.1.4

    在双声道音乐文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、 左声道模式、右声道模式或混合模式。例如，在 KTV 场景中，音乐文件的左声道存储了伴奏，右声道存储了原唱的歌声。 如果你只需听伴奏，调用该方法设置音乐文件的声道模式为左声道模式；如果你需要同时听伴奏和原唱，调用该方法设置声 道模式为混合模式。

    note
    • 你需要在调用 startAudioMixing 并 收到 audioMixingStateChanged (710) 回调后调用该方法。
    • 该方法仅适用于双声道的音乐文件。

    Parameters

    Returns number

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

setAudioMixingPitch

  • setAudioMixingPitch(pitch: number): number

  • 调整本地播放的音乐文件的音调。

    since

    v3.2.0

    本地人声和播放的音乐文件混音时，调用该方法可以仅调节音乐文件的音调。

    note

    调用该方法前，请确保你已调用 startAudioMixing。

    Parameters

    • pitch: number

      按半音音阶调整本地播放的音乐文件的音调，默认值为 0，即不调整音调。 取值范围为 [-12,12]，每相邻两个值的音高距离相差半音。取值的绝对值越大，音调升高或降低得越多。

    Returns number

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

setAudioMixingPlaybackSpeed

  • setAudioMixingPlaybackSpeed(speed?: number): number

  • 设置当前音乐文件的播放速度。

    since

    v3.6.1.4

    note

    你需要在调用 startAudioMixing 并 收到 audioMixingStateChanged (710) 回调后调用该方法。

    Parameters

    • Default value speed: number = 100

      播放速度。推荐取值范围为 [50,400]，其中：

      • 50: 0.5 倍速。
      • 100: 原始速度。
      • 400: 4 倍速。

    Returns number

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

setAudioMixingPosition

  • setAudioMixingPosition(position: number): number

  • 设置音乐文件的播放位置。

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

    note

    你需要在调用 startAudioMixing 并收到 audioMixingStateChanged 回调 返回状态码 710 后调用该方法。

    Parameters

    • position: number

      当前播放进度，单位为毫秒

    Returns number

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

setAudioPlaybackDevice

  • setAudioPlaybackDevice(deviceId: string): number

  • 通过设备 ID 指定音频播放设备

    Parameters

    • deviceId: string

      音频播放设备的 ID

    Returns number

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

setAudioPlaybackDeviceMute

  • setAudioPlaybackDeviceMute(mute: boolean): number

  • 设置当前音频播放设备为静音/不静音。

    Parameters

    • mute: boolean

      是否设置当前音频播放设备静音：

      • true：设置当前音频播放设备静音
      • false：设置当前音频播放设备不静音

    Returns number

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

setAudioPlaybackVolume

  • setAudioPlaybackVolume(volume: number): number

  • 设置音频播放设备的音量

    Parameters

    • volume: number

      播放设备音量（分贝）。取值范围 [0,255]

    Returns number

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

setAudioProfile

  • setAudioProfile(profile: 0 | 1 | 2 | 3 | 4 | 5, scenario: 0 | 1 | 2 | 3 | 4 | 5 | 8): number

  • 设置音频编码配置。

    note
    • 请在 joinChannel 之前调用该方法，否则不生效。
    • 通信和直播场景下，音质（码率）会有网络自适应的调整，通过该方法设置的是一个最高码率。
    • 在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 4，scenario 设置为 3。

    Parameters

    • profile: 0 | 1 | 2 | 3 | 4 | 5

      设置采样率、码率、编码模式和声道数：

      • 0：默认设置：
        • 直播场景：48 KHz 采样率，音乐编码，单声道，编码码率最大值为 52 Kbps
        • 通信场景：32 KHz 采样率，音乐编码，单声道，编码码率最大值为 18 Kbps（macOS）； 16 KHz 采样率，音乐编码，单声道，编码码率最大值为 16 Kbps（Windows）
      • 1：Speech standard：指定 32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps
      • 2：Music standard：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 48 Kbps
      • 3：Music standard stereo：指定 48 kHz采样率，音乐编码，双声道，编码码率最大值为 56 Kbps
      • 4：Music high quality：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 128 Kbps
      • 5：Music high quality stereo：指定 48 kHz 采样率，音乐编码，双声道，编码码率最大值为 192 Kbps
      • 6：IOT。
    • scenario: 0 | 1 | 2 | 3 | 4 | 5 | 8

      设置音频应用场景：

      • 0：默认的音频应用场景
      • 1：Chatroom entertainment：娱乐应用，需要频繁上下麦的场景
      • 2：Education：教育应用，流畅度和稳定性优先
      • 3：Game streaming：游戏直播应用，需要外放游戏音效也直播出去的场景
      • 4：Showroom：秀场应用，音质优先和更好的专业外设支持
      • 5：Chatroom gaming：游戏开黑
      • 8：Meeting：会议场景，适用于人声为主的多人会议。

    Returns number

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

setAudioRecordingDevice

  • setAudioRecordingDevice(deviceId: string): number

  • 设置音频录制设备

    Parameters

    • deviceId: string

      设备 ID

    Returns number

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

setAudioRecordingDeviceMute

  • setAudioRecordingDeviceMute(mute: boolean): number

  • 设置当前音频录制设备静音/不静音。

    Parameters

    • mute: boolean

      是否设置当前音频录制设备静音：

      • true：设置静音
      • false：设置不静音

    Returns number

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

setAudioRecordingVolume

  • setAudioRecordingVolume(volume: number): number

  • 设置录音设备的音量

    Parameters

    • volume: number

      录音设备的音量（分贝）。取值范围 [0, 255]

    Returns number

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

setBeautyEffectOptions

  • setBeautyEffectOptions(enable: boolean, options: BeautyOptions): number

  • 开启或关闭本地美颜功能，并设置美颜效果选项。

    since

    v3.0.0 (适用于 Windows 平台)

    since

    v3.2.0 (适用于 macOS 平台)

    note

    调用 enableVideo 之后再调用该方法。

    Parameters

    • enable: boolean

      是否开启美颜功能：

      • true：开启
      • false：（默认）关闭
    • options: BeautyOptions

      设置美颜选项，包含如下字段：

    Returns number

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

setCameraCapturerConfiguration

  • 设置摄像头的采集偏好。

    一般的视频通话或直播中，默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中，默认的参数通常无法满足需求，或可能引起设备性能问题，我们推荐调用该接口设置摄像头的采集偏好：

    • 使用裸数据自采集接口时，如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时， 会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，避免性能问题。
    • 如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，以优化 CPU 和内存的资源分配
    • 如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2)
    • 如果用户需要自定义本地采集的视频宽高，请将采集偏好设为 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3)。
    note

    请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo

    Parameters

    Returns number

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

setChannelProfile

  • setChannelProfile(profile: number): number

  • 设置频道场景。

    声网会根据你的 app 使用场景进行不同的优化。

    note
    • 该方法必须在 joinChannel 方法之前调用
    • 相同频道内的所有用户必须使用相同的频道场景

    Parameters

    • profile: number

      频道场景：

      • 0：（默认）通信
      • 1：直播
      • 2：游戏

    Returns number

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

setClientRole

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

    加入频道前，用户需要通过本方法设置观众或主播模式。

    加入频道后，用户可以通过本方法切换用户模式。直播场景下，如果你在加入频道后调用该方法切换用户角色， 调用成功后，本地会触发 clientRoleChanged 事件；远端会触发 userJoined 事件。

    Parameters

    Returns number

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

setClientRoleWithOptions

  • 设置直播场景下的用户角色和观众端延时级别。

    since

    v3.2.0

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

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

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

    Parameters

    Returns number

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

setCloudProxy

  • 设置声网云代理服务。

    since

    v3.3.1

    当用户防火墙限制 IP 和端口号时，你需要参考《使用云代理》开放相应 IP 和端口号，然后调用该方法开启云代理，并将 type 参数设置为 1，即 UDP 协议的云代理。

    成功连接云代理后，SDK 会触发 connectionStateChanged(2, 11) 回调。

    如果你想关闭已设置的云代理，请调用 setCloudProxy(0)。如果你想更改已设置的云代理类型， 请先调用 setCloudProxy(0)，再调用 setCloudProxy 并传入你期望的 type 值。

    note
    • 推荐你在频道外调用该方法。
    • 使用 UDP 协议的云代理时，旁路推流 和跨频道媒体流转发功能不可用。

    Parameters

    • type: CLOUD_PROXY_TYPE

      云代理类型。该参数为必填参数，如果你不赋值，SDK 会报错。

    Returns number

    • 0: 方法调用成功
    • < 0: 方法调用失败
      • -2: 传入的参数无效
      • -7: SDK 尚未初始化

setColorEnhanceOptions

  • 设置色彩增强功能。

    since

    v3.7.0

    摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性，提升视频色彩丰富度和色彩还原度，最终使视频画面更生动。

    你可以调用该方法开启色彩增强功能并设置色彩增强的效果。

    note
    • 调用该方法前，请确保你已经将如下动态库集成到项目中：
      • macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • 请在 enableVideo 后调用该方法。
    • 色彩增强对设备性能有一定要求。开启色彩增强后，如果设备出现严重发烫等问题，Agora 推荐你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。

    Parameters

    • enabled: boolean

      是否开启色彩增强功能：

      • true: 开启。
      • false:（默认）关闭。
    • options: ColorEnhanceOptions

      色彩增强选项，用于设置色彩增强的效果。详见 ColorEnhanceOptions 。

    Returns number

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

setCustomRenderer

  • setCustomRenderer(customRenderer: IRenderer): void

  • 当 setRenderMode 方法中的渲染模式设置为 3 时，调用该方法可以设备自定义的渲染器。 customRender 是一个类.

    Parameters

    • customRenderer: IRenderer

      自定义渲染器

    Returns void

setDefaultMuteAllRemoteAudioStreams

  • setDefaultMuteAllRemoteAudioStreams(mute: boolean): number

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

    deprecated

    该方法自 v3.3.1 起废弃。

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

    note

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

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

    Parameters

    • mute: boolean

      是否默认取消订阅远端用户的音频流：

      • true: 默认取消订阅。
      • false:（默认）默认订阅。

    Returns number

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

setDefaultMuteAllRemoteVideoStreams

  • setDefaultMuteAllRemoteVideoStreams(mute: boolean): number

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

    deprecated

    该方法自 v3.3.1 起废弃。

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

    note

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

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

    Parameters

    • mute: boolean

      是否默认取消订阅远端用户的视频流：

      • true: 默认取消订阅。
      • false:（默认）默认订阅。

    Returns number

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

setEffectPosition

  • setEffectPosition(soundId: number, pos: number): number

  • 设置指定音效文件的播放位置。

    since

    v3.4.2

    成功设置后，本地音效文件会在指定位置开始播放。

    note

    该方法需要在 playEffect 后调用。

    Parameters

    • soundId: number

      音效 ID。请确保与 playEffect 中设置的 soundId 一致。

    • pos: number

      音效文件的播放位置，单位为毫秒。

    Returns number

    • 0: 方法调用成功。
    • < 0: 方法调用失败。
      • -22: 无法找到音效文件。请填写正确的 soundId。

setEffectsVolume

  • setEffectsVolume(volume: number): number

  • 设置播放音效文件音量。

    Parameters

    • volume: number

      音效文件的音量。取值范围为 [0.0, 100.0]，100.0 为默认值，表示原始音量。

    Returns number

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

setEncryptionMode

  • setEncryptionMode(mode: string): number

  • 设置内置的加密方案。

    depercated

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

    RTC Native SDK 支持内置加密功能，默认使用 AES-128-XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。

    同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

    note

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

    Parameters

    • mode: string

      加密方式。目前支持以下几种：

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

    Returns number

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

setEncryptionSecret

  • setEncryptionSecret(secret: string): number
  • deprecated

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

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

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

    note

    为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

    Parameters

    • secret: string

      加密密码

    Returns number

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

setHighQualityAudioParameters

  • setHighQualityAudioParameters(fullband: boolean, stereo: boolean, fullBitrate: boolean): number
  • deprecated

    该方法已废弃。请改用 setAudioProfile 设置音频高音质选项。

    请在加入频道前调用该方法，对其中的三个模式完成设置。加入频道后调用该方法不生效。

    Parameters

    • fullband: boolean

      是否启用全频带编解码器（48 kHz 采样率）：

      • true：启用全频带编解码器
      • false：禁用全频带编解码器
    • stereo: boolean

      是否启用立体声编解码器：

      • true：启用立体声编解码器
      • false：禁用立体声编解码器
    • fullBitrate: boolean

      是否启用高码率模式：

      • true：启用高码率模式
      • false：禁用高码率模式

    Returns number

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

setLiveTranscoding

  • 设置直播转码。

    调用该方法更新 transcoding 参数时，SDK 会触发 transcodingUpdated 回调。

    note
    • 该方法只适用于直播场景下的主播。
    • 请确保已开通旁路推流的功能，详见《旁路推流》文档中的 “前提条件”。
    • 首次调用 setLiveTranscoding 方法设置 transcoding 时，不会触发该回调。

    Parameters

    Returns number

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

setLocalAccessPoint

setLocalPublishFallbackOption

  • setLocalPublishFallbackOption(option: 0 | 1 | 2): number

  • 设置弱网条件下发布的音视频流回退选项。

    网络不理想的环境下，音、视频的质量都会下降。使用该接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 后，SDK 会：

    • 在上行弱网且音视频质量严重受影响时，自动关断视频流，从而保证或提高音频质量。
    • 持续监控网络质量，并在网络质量改善时恢复音视频流。

    当本地推流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发 localPublishFallbackToAudioOnly 回调。

    note

    旁路推流场景下，设置本地推流回退为 Audio-only 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下，Agora 建议不开启该功能。

    Parameters

    • option: 0 | 1 | 2

      本地推流回退处理选项：

      • STREAM_FALLBACK_OPTION_DISABLED (0)：（默认）上行网络较弱时，不对音视频流作回退处理，但不能保证音视频流的质量
      • STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1)：（默认）下行网络较弱时只接收视频小流。该选项只对本方法无效。
      • STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)：上行网络较弱时只发布音频流

    Returns number

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

setLocalVoiceChanger

setLocalVoiceEqualization

  • setLocalVoiceEqualization(bandFrequency: number, bandGain: number): number

  • 设置本地语音音效均衡。

    Parameters

    • bandFrequency: number

      频谱子带索引。取值范围是 [0, 9]，分别代表 10 个频带，对应的中心频率分别是 31，62，125，250，500，1k，2k，4k，8k，16 kHz

    • bandGain: number

      增益 (dB)。取值范围是 [-15, 15]，默认值为 0

    Returns number

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

setLocalVoicePitch

  • setLocalVoicePitch(pitch: number): number

  • 设置本地语音音调。

    Parameters

    • pitch: number

      语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调

    Returns number

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

setLocalVoiceReverb

  • setLocalVoiceReverb(reverbKey: number, value: number): number

  • 设置本地音效混响。

    note

    SDK 提供一个使用更为简便的接口 setLocalVoiceReverbPreset，该 方法通过一系列内置参数的调整，直接实现流行、R&B、摇滚、嘻哈等预置的混响效果。

    Parameters

    • reverbKey: number

      混响音效类型。：

      • 0：原始声音强度 (dB)，即所谓的 dry signal，取值范围 [-20, 10]
      • 1：早期反射信号强度 (dB)，即所谓的 wet signal，取值范围 [-20, 10]
      • 2：所需混响效果的房间尺寸。一般房间越大，混响越强，取值范围 [0, 100]
      • 3：Wet signal 的初始延迟长度 (ms)，取值范围 [0, 200]
      • 4：混响持续的强度，取值范围为 [0, 100]
    • value: number

      设置混响音效的效果数值，各数值请参考 reverbKey

    Returns number

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

setLocalVoiceReverbPreset

setLogFile

  • setLogFile(filepath: string): number

  • 设置日志文件。

    deprecated

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

    设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。你的 app 必须保证指定的目录存在而且可写。

    note

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

    Parameters

    • filepath: string

      日志文件的完整路径

    Returns number

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

setLogFileSize

  • setLogFileSize(size: number): number

  • 设置 SDK 输出的单个日志文件大小。

    deprecated

    该方法从 v3.3.1 起废弃，请改用 initialize 中的 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 写入最新的日志。

    note

    如果想要设置日志文件的大小，则需要在 setLogFile 前调用本方法，否则日志会被清空。

    相关 API：

    Parameters

    • size: number

      单个日志文件的大小，单位为 KB。默认值为 1024 KB。 如果你将 size 设为 1024 KB，SDK 会最多输出 5 MB 的日志文件。如果你将 size 设为 小于 1024 KB，单个日志文件最大仍为 1024 KB。

    Returns number

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

setLogFilter

  • setLogFilter(filter: number): number

  • 设置日志文件过滤器。

    deprecated

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

    该方法设置 SDK 的输出日志过滤等级。不同的过滤等级可以单独或组合使用。

    日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。 例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

    Parameters

    • filter: number

      设置过滤器等级

      • 0：不输出任何日志
      • 0x080f：输出所有的 API 日志，即CRITICAL、ERROR、WARNING、INFO 和 DEBUG 级别的日志。如果你想获取最完整的日志，可将日志级别设为该等级
      • 0x000f：输出 CRITICAL、ERROR、WARNING、INFO 级别的日志。我们推荐你将日志级别设为该等级
      • 0x000e：仅输出 CRITICAL、ERROR、WARNING 级别的日志
      • 0x000c：仅输出 CRITICAL、ERROR 级别的日志
      • 0x0008：仅输出 CRITICAL 级别的日志

    Returns number

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

setLowlightEnhanceOptions

  • 设置暗光增强功能。

    since

    v3.7.0

    暗光增强功能可以在光线亮度偏低（如背光、阴天、暗场景）和亮度不均匀的环境下自适应调整视频画面的亮度值，恢复或凸显图像的细节信息，最终提升视频图像的整体视觉效果。

    你可以调用该方法开启暗光增强功能并设置暗光增强的效果。

    note
    • 调用该方法前，请确保你已经将如下动态库集成到项目中：
      • macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • 请在 enableVideo 后调用该方法。
    • 暗光增强对设备性能有一定要求。开启暗光增强后，如果设备出现严重发烫等问题，Agora 推荐你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。

    Parameters

    Returns number

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

setMaxMetadataSize

  • setMaxMetadataSize(size: number): number

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

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

    Parameters

    • size: number

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

    Returns number

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

setParameters

  • setParameters(param: string): number

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

    JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

    Parameters

    • param: string

      JSON 字符串形式的参数

    Returns number

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

setPauseRenderer

  • setPauseRenderer(pause?: boolean): void

  • Parameters

    • Default value pause: boolean = false

    Returns void

setProcessDpiAwareness

  • setProcessDpiAwareness(): number

  • Returns number

setRecordingAudioFrameParameters

  • setRecordingAudioFrameParameters(sampleRate: number, channel: 1 | 2, mode: 0 | 1 | 2, samplesPerCall: number): number

  • Parameters

    • sampleRate: number
    • channel: 1 | 2
    • mode: 0 | 1 | 2
    • samplesPerCall: number

    Returns number

setRemoteDefaultVideoStreamType

  • setRemoteDefaultVideoStreamType(streamType: StreamType): number

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

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

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

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

    Parameters

    • streamType: StreamType

      设置视频流的类型：

      • 0：视频大流，即高分辨、高码率的视频流
      • 1：视频小流，即低分辨、低码率的视频流

    Returns number

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

setRemoteSubscribeFallbackOption

  • setRemoteSubscribeFallbackOption(option: 0 | 1 | 2): number

  • 设置弱网条件下订阅的音视频流回退选项。

    网络不理想的环境下，音、视频的质量都会下降。使用该接口并将 option 设置为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1) 或者 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)后，SDK 会：

    • 在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高音频质量。
    • 持续监控网络质量，并在网络质量改善时恢复音视频流。

    当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发 remoteSubscribeFallbackToAudioOnly 回调。

    Parameters

    • option: 0 | 1 | 2

      远端订阅流回退处理选项：

      • STREAM_FALLBACK_OPTION_DISABLED (0)：下行网络较弱时，不对音视频流作回退处理，但不能保证音视频流的质量
      • STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1)：（默认）下行网络较弱时只接收视频小流。该选项只对该方法有效，对 setLocalPublishFallbackOption 方法无效
      • STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)：下行网络较弱时，先尝试只接收视频小流；如果网络环境无法显示视频，则再回退到只接收远端订阅的音频流

    Returns number

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

setRemoteUserPriority

  • setRemoteUserPriority(uid: number, priority: Priority): number

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

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

    该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项，弱网下 SDK 会优先保证高优先级用户收到的流的质量。

    note
    • 该方法仅适用于直播场景。
    • 目前 SDK 仅允许将一名远端用户设为高优先级。

    Parameters

    • uid: number

      远端用户的 ID

    • priority: Priority

      远端用户的需求优先级

    Returns number

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

setRemoteUserSpatialAudioParams

  • setRemoteUserSpatialAudioParams(uid: number, spatial_audio_params?: SpatialAudioParams): number

setRemoteVideoStreamType

  • setRemoteVideoStreamType(uid: number, streamType: StreamType): number

  • 设置订阅的视频流类型。

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

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

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

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

    Parameters

    • uid: number

      用户 ID

    • streamType: StreamType

      视频流类型

    Returns number

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

setRemoteVoicePosition

  • setRemoteVoicePosition(uid: number, pan: number, gain: number): number

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

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

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

    Parameters

    • uid: number

      远端用户的 ID

    • pan: number

      设置远端用户声音出现的位置，取值范围为 [-1.0, 1.0]：

      • 0.0：（默认）声音出现在正前方
      • -1.0：声音出现在左边
      • 1.0：声音出现在右边
    • gain: number

      设置远端用户声音的音量，取值范围为 [0.0, 100.0]，默认值为 100.0，表示该用户的原始音量。取值越小，则音量越低

    Returns number

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

setRenderMode

  • setRenderMode(mode?: 1 | 2 | 3 | 4): void

  • 设置渲染模式。

    该方法确定是使用 WebGL 渲染还是软件渲染。

    Parameters

    • Default value mode: 1 | 2 | 3 | 4 = 1

      渲染模式：

      • 1：使用 WebGL 渲染
      • 2：使用软件渲染
      • 3：使用自定义渲染

    Returns void

setScreenCaptureContentHint

  • 设置屏幕共享内容类型。

    设置屏幕共享的内容类型。SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。 如果不调用该方法，SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE ，即无指定的内容类型。

    Parameters

    Returns number

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

setScreenCaptureScenario

  • 设置屏幕共享的场景。

    since

    v3.7.0

    开启屏幕共享或窗口共享时，你可以调用该方法设置屏幕共享的场景，SDK 会根据你设置的场景调整共享画质和体验。

    note

    该方法仅适用于 macOS 和 Windows。

    Parameters

    Returns number

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

setVideoDenoiserOptions

  • 设置视频降噪功能。

    since

    v3.7.0

    采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声，影响视频画质。在实时互动场景下，视频噪声还会在编码过程中占用码流资源并降低编码效率。

    你可以调用该方法开启视频降噪功能并设置视频降噪的效果。

    note
    • 调用该方法前，请确保你已经将如下动态库集成到项目中：
      • macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • 请在 enableVideo 后调用该方法。
    • 视频降噪对设备性能有一定要求。开启视频降噪后，如果设备出现严重发烫等问题，Agora 推荐你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。

    Parameters

    • enabled: boolean

      是否开启视频降噪功能：

      • true: 开启。
      • false:（默认）关闭。
    • options: VideoDenoiserOptions

      视频降噪选项，用于设置视频降噪的效果。详见 VideoDenoiserOptions。

    Returns number

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

setVideoDevice

  • setVideoDevice(deviceId: string): number

  • 设置视频设备。

    Parameters

    • deviceId: string

      设备 ID

    Returns number

    • true：方法调用成功
    • false：方法调用失败

setVideoEncoderConfiguration

  • 设置视频编码属性。

    该方法设置视频编码属性。每个属性对应一套视频参数，如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。

    如果用户加入频道后不需要重新设置视频编码属性，则声网建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

    Parameters

    Returns number

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

setVideoProfile

  • deprecated

    该方法已废弃。请改用 setVideoEncoderConfiguration

    设置视频属性。

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

    Parameters

    • profile: VIDEO_PROFILE_TYPE

      视频属性

    • Default value swapWidthAndHeight: boolean = false

      是否交换宽高值：

      • true：交换
      • false：不交换（默认）

    Returns number

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

setVideoQualityParameters

  • setVideoQualityParameters(preferFrameRateOverImageQuality: boolean): number
  • deprecated

    该方法已废弃。请改用 setCameraCapturerConfiguration 和 setVideoEncoderConfiguration

    设置视频偏好选项。

    note

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

    Parameters

    • preferFrameRateOverImageQuality: boolean

      视频偏好选项：

      • true：视频画质和流畅度里，优先保证流畅度
      • false：视频画质和流畅度里，优先保证画质（默认）

    Returns number

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

setVideoRenderDimension

  • setVideoRenderDimension(rendertype: number, uid: number, width: number, height: number): void

  • 设置视频渲染的分辨率。

    该方法只对发送给 js 层的视频数据有效。其他端的视频分辨率由 setVideoEncoderConfiguration 方法决定。

    Parameters

    • rendertype: number

      渲染器的类型：

      • 0：本地渲染器
      • 1：远端渲染器
      • 2：设备测试
      • 3：视频源
    • uid: number

      目标用户的 ID

    • width: number

      想要发送的视频宽度

    • height: number

      想要发送的视频高度

    Returns void

setVideoRenderFPS

  • setVideoRenderFPS(fps: number): void

  • 设置视频的全局渲染帧率。

    该方法主要用来提升 js 渲染的性能。完成设置后，视频数据会被强制按设置的帧率进行传输，以降低 js 渲染的 CPU 消耗。

    note

    该方法不适用于添加至高帧率传输流的视频视图。

    Parameters

    • fps: number

      渲染帧率（fps）

    Returns void

setVideoRenderHighFPS

  • setVideoRenderHighFPS(fps: number): void

  • 设置高帧率流的渲染帧率。

    其中高帧率流指调用 addVideoRenderToHighFPS 方法添加至高帧率的视频流。

    note
    • 请注意区分高帧率流和双流模式里的大流。
    • 该方法适用于将大多数视图设置为低帧率，只将一或两路流设置为高帧率的场景，如屏幕共享。

    Parameters

    • fps: number

      渲染帧率（fps）

    Returns void

setVoiceBeautifierParameters

  • 设置 SDK 预设美声效果的参数。

    since

    v3.3.1

    调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后，频道内所有用户都能听到该效果。

    为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 3，并将 profile 设为 4 或 5。

    note

    Parameters

    • preset: VOICE_BEAUTIFIER_PRESET

      SDK 预设的音效：

      • SINGING_BEAUTIFIER: 歌唱美声。
    • param1: number

      歌声的性别特征：

      • 1: 男声。
      • 2: 女声。
    • param2: number

      歌声的混响效果：

      • 1: 歌声在小房间的混响效果。
      • 2: 歌声在大房间的混响效果。
      • 3: 歌声在大厅的混响效果。

    Returns number

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

setVoiceBeautifierPreset

setVoiceConversionPreset

setVolumeOfEffect

  • setVolumeOfEffect(soundId: number, volume: number): number

  • 设置单个音效文件的音量。

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID

    • volume: number

      音效文件的音量。取值范围为 [0.0, 100.0]。100.0 为默认值

    Returns number

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

setupLocalVideo

  • 设置本地视图和渲染器。

    note

    请在主线程调用该方法。

    Parameters

    Returns number

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

setupLocalVideoSource

  • setupLocalVideoSource(view: Element): void

  • 双实例方法：设置 videoSource 的渲染器

    Parameters

    • view: Element

      播放共享视频的 Dom

    Returns void

setupRemoteVideo

  • setupRemoteVideo(uid: number, view?: Element, channel?: undefined | string, options?: RendererOptions): number

  • 设置远端视图和渲染器。

    Parameters

    • uid: number

      远端用户的用户 ID

    • Optional view: Element

      初始化视图的 Dom

    • Optional channel: undefined | string

      远端用户所在的频道名称

    • Optional options: RendererOptions

    Returns number

setupViewContentMode

  • setupViewContentMode(uid: number | "local" | "videosource", mode: 0 | 1, channelId: string | undefined): number

  • 设置视窗内容显示模式。

    Parameters

    • uid: number | "local" | "videosource"

      用户 ID，表示设置的是哪个用户的流。设置远端用户的流时，请确保你已先调用 subscribe 方法订阅该远端用户流。

    • mode: 0 | 1

      视窗内容显示模式：

      • 0：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉
      • 1： 优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑
    • channelId: string | undefined

    Returns number

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

startAudioDeviceLoopbackTest

  • startAudioDeviceLoopbackTest(interval: number): number

  • 开始音频设备回路测试。

    该方法测试本地的音频设备是否正常工作。

    调用该方法后，麦克风会采集本地语音并通过扬声器播放出来，用户需要配合说一段话。SDK 会通过 groupAudioVolumeIndication 回调向 App 上报音量信息。

    note

    该方法仅在本地进行音频设备测试，不涉及网络连接。

    Parameters

    • interval: number

      SDK 返回 groupAudioVolumeIndication 回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。

    Returns number

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

startAudioMixing

  • startAudioMixing(filepath: string, loopback: boolean, replace: boolean, cycle: number, startPos?: number): number

  • 开始播放音乐文件。

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

    note
    • 如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。
    • 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告警告码 701。

    Parameters

    • filepath: string

      音乐文件的绝对路径或 URL 地址，需精确到文件名及后缀。 例如：C:\music\audio.mp4。支持的音频格式包括 MP3、AAC、 M4A、MP4、WAV、3GP。 详见 Supported Media Formats in Media Foundation。

    • loopback: boolean

      是否只在本地播放音乐文件：

      • true: 只在本地播放音乐文件，只有本地用户能听到音乐。
      • false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。
    • replace: boolean

      是否用音乐文件替换麦克风采集的音频：

      • true: 替换。用户只能听到音乐。
      • false: 不替换。用户可以听到音乐和麦克风采集的音频。
    • cycle: number

      音乐文件的播放次数。

      • ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。
      • -1: 无限循环播放。
    • Default value startPos: number = 0

      音乐文件的播放位置，单位为毫秒。

    Returns number

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

startAudioPlaybackDeviceTest

  • startAudioPlaybackDeviceTest(filepath: string): number

  • 开始音频播放设备测试。

    该方法检测音频播放设备是否正常工作。SDK 会播放用户指定的音乐文件，如果用户可以听到声音，则说明播放设备正常工作。

    Parameters

    • filepath: string

      用来测试的音乐文件的路径

    Returns number

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

startAudioRecording

  • 开始客户端录音。

    deprecated

    自 v3.4.2 废弃。请改用 startAudioRecordingWithConfig 方法。

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

    • .wav: 文件大，音质保真度较高。
    • .aac: 文件小，音质保真度较低。
    note
    • 请确保你在该方法中指定的路径存在并且可写。
    • 该接口需在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。
    • 为保证录音效果，当 sampleRate 设为 44.1 kHz 或 48 kHz 时，建议将 quality 设为 MEDIUM 或 HIGH 。

    Parameters

    • filePath: string

      录音文件在本地保存的绝对路径，由用户自行指定，需精确到文件名及格式， 例如：c:/music/audio.aac（Windows）和 /var/mobile/Containers/Data/audio.aac（macOS）。

    • Default value recordingSampleRate: number = 32000
    • recordingQuality: AUDIO_RECORDING_QUALITY_LOW
    • recordingPosition: AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK
    • Default value recordingChannel: number = 1

    Returns number

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

startAudioRecordingDeviceTest

  • startAudioRecordingDeviceTest(indicateInterval: number): number

  • 开始音频录制设备测试。

    该方法测试麦克风是否正常工作。开始测试后，SDK 会通过 groupAudioVolumeIndication 回调向 App 上报音量信息。

    Parameters

    • indicateInterval: number

      groupAudioVolumeIndication 回调的周期（毫秒）

    Returns number

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

startAudioRecordingWithConfig

  • 开始客户端录音。

    since

    v3.4.2

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

    • WAV：音质保真度较高，文件较大。例如，采样率为 32000 Hz，录音时长为 10 分钟的文件大小约为 73 M。
    • AAC：音质保真度较低，文件较小。例如，采样率为 32000 Hz，录音音质为 AUDIO_RECORDING_QUALITY_MEDIUM，录音时长为 10 分钟的文件大小约为 2 M。

    一旦用户离开频道，录音会自动停止。

    note

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

    Parameters

    Returns number

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

startChannelMediaRelay

  • 开始跨频道媒体流转发。

    该方法可用于实现跨频道连麦等场景。

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

    note
    • 该功能需要联系 sales@agora.io 开通。
    • 请在成功加入频道后调用该方法。
    • 该方法仅对直播场景下的主播有效。
    • 该功能不支持使用 String 型 uid。
    • 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

    Parameters

    Returns number

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

startEchoTest

  • startEchoTest(): number
  • deprecated

    该方法已废弃。请改用 startEchoTestWithInterval

    开始语音通话回路测试。

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

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

    Returns number

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

startEchoTestWithConfig

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

    since

    v3.6.1.4

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

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

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

    Parameters

    Returns number

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

startEchoTestWithInterval

  • startEchoTestWithInterval(interval: number): number

  • 开始语音通话回路测试。

    该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。

    在测试过程中，用户先说一段话，声音会在设置的时间间隔（单位为秒）后回放出来。如果用户能正常听到自己刚才说的话， 就表示系统音频设备和网络连接都是正常的。

    note
    • 请在加入频道 joinChannel 前调用该方法。
    • 调用该方法后必须调用 stopEchoTest 已结束测试，否则不能进行下一次回声测试，也不能调用 joinChannel 进行通话。
    • 直播场景下，只有主播能调用该方法。

    Parameters

    • interval: number

      设置返回语音通话回路测试结果的时间间隔（s）。取值范围为 [2, 10]，默认为 10。

    Returns number

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

startLastmileProbeTest

  • 开始通话前网络质量探测。

    启用该方法后，SDK 会向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。SDK 会一次返回如下两个回调：

    • lastMileQuality：视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
    • lastmileProbeResult：视网络情况约 30 秒内返回。该回调通过客观数据反馈上下行网络质量，因此更客观。

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

    • 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
    • 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。
    note
    • 该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要同时使用该方法和 enableLastmileTest
    • 调用该方法后，在收到 lastMileQuality 和 lastmileProbeResult 回调之前请不用调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行
    • 直播场景下，如果本地用户为主播，请勿在加入频道后调用该方法

    Parameters

    Returns number

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

startPreview

  • startPreview(): number

  • 开启视频预览。

    该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须：

    note
    • 本地预览默认开启镜像功能
    • 使用该方法启用了本地视频预览后，如果直接调用 leaveChannel 退出频道，并不会关闭预览。如需关闭预览，请调用 stopPreview

    Returns number

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

startRtmpStreamWithTranscoding

  • startRtmpStreamWithTranscoding(url: string, transcoding: TranscodingConfig): number

  • 开始 CDN 直播推流并设置转码属性。

    since

    v3.6.1.4

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

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

    note
    • 请确保已开通旁路推流服务，详见进阶功能《旁路推流》中的前提条件。
    • 请在加入频道后调用该方法。
    • 只有直播场景下的主播才能调用该方法。
    • 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。
    • 如果你想向 CDN 推送 RTMPS 协议的媒体流，请调用 startRtmpStreamWithTranscoding，而非 startRtmpStreamWithoutTranscoding。

    Parameters

    • url: string

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

    • transcoding: TranscodingConfig

      CDN 直播推流的转码属性，详见 LiveTranscoding 类。

    Returns number

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

startRtmpStreamWithoutTranscoding

  • startRtmpStreamWithoutTranscoding(url: string): number

  • 开始非转码推流。

    since

    v3.6.1.4

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

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

    note
    • 请确保已开通旁路推流服务，详见进阶功能《旁路推流》中的前提条件。
    • 请在加入频道后调用该方法。
    • 只有直播场景下的主播才能调用该方法。
    • 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。
    • 如果你想向 CDN 推送 RTMPS 协议的媒体流，请调用 startRtmpStreamWithTranscoding，而非 startRtmpStreamWithoutTranscoding。

    Parameters

    • url: string

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

    Returns number

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

startScreenCapture

  • startScreenCapture(windowId: number, captureFreq: number, rect: object, bitrate: number): number

  • 通过窗口信息共享屏幕

    deprecated

    该方法已废弃，请改用 startScreenCaptureByWindow 方法。

    共享一个窗口或该窗口的部分区域。你需要在该方法中指定想要共享的窗口 ID。

    note

    设置 rect 时你需要注意：

    • 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容
    • 如果 left 和 right 值一样，即宽为 0，则共享整个窗口
    • 如果 top 和 bottom 值一样，即高 为 0，则共享整个窗口

    Parameters

    • windowId: number

      待共享的窗口 ID

    • captureFreq: number

      共享视频的编码帧率（fps）。默认值为 5，建议不要超过 15

    • rect: object

      （可选）共享区域相对于整个屏幕左上角的位置。如不填，则表示共享整个窗口。由如下参数组成：

      • bottom: number

        窗口底部位置

      • left: number

        窗口左侧位置

      • right: number

        窗口右侧位置

      • top: number

        窗口顶部位置

    • bitrate: number

      共享视频的码率（Kbps）；默认值为 0，表示由 SDK 根据当前共享的分辨率计算出一个合理的值

    Returns number

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

startScreenCapture2

  • startScreenCapture2(windowId: number, captureFreq: number, rect: object, bitrate: number): number
  • deprecated

    该方法已废弃，请改用 videoSourceStartScreenCaptureByScreen 或 videoSourceStartScreenCaptureByWindow

    双实例方法：共享屏幕。

    共享一个窗口或该窗口的部分区域。你需要在该方法中指定想要共享的窗口 ID。

    note

    设置 rect 时你需要注意：

    • 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容
    • 如果 left 和 right 值一样，即宽为 0，则共享整个窗口
    • 如果 top 和 bottom 值一样，即高 为 0，则共享整个窗口

    Parameters

    • windowId: number

      待共享的窗口 ID

    • captureFreq: number

      共享视频的编码帧率（fps）。默认值为 5，建议不要超过 15

    • rect: object

      共享窗口相对于屏幕左上角的相对位置和大小，可设为 null

      • bottom: number
      • left: number
      • right: number
      • top: number
    • bitrate: number

      共享视频的码率（Kbps）；默认值为 0，表示由 SDK 根据当前共享的分辨率计算出一个合理的值

    Returns number

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

startScreenCaptureByDisplayId

  • 通过屏幕 ID 共享屏幕。

    共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。

    note
    • 该方法仅适用于 macOS 和 Windows。
    • 该方法需要在加入频道后调用。
    warning

    Windows 平台上，如果用户设备外接其他显示屏，为避免屏幕共享出现问题，请使用 startScreenCaptureByDisplayId 开启共享， 不要使用 startScreenCaptureByScreenRect。

    Parameters

    • displayId: DisplayId

      指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。关于如何获取屏幕 ID，请参考基础功能《共享屏幕》 或从 getScreenCaptureSources 返回的 sourceId 获取。

    • rect: CaptureRect
    • param: CaptureParam

    Returns number

    • 0: 方法调用成功
    • < 0: 方法调用失败:
      • #ERR_INVALID_ARGUMENT: 传入的参数无效。

startScreenCaptureByScreen

  • 通过指定区域共享屏幕。

    共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕区域。

    Parameters

    • screenSymbol: ScreenSymbol

      指定待共享的屏幕相对于虚拟屏的位置。详见 {@link screenSymbol}

    • rect: CaptureRect

      (可选）指定待共享区域相对于整个屏幕屏幕的位置。如不填，则表示共享整个屏幕。 如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ， 则共享整个屏幕。详见 CaptureRect

    • param: CaptureParam

      屏幕共享的编码参数配置。详见 CaptureParam

    Returns number

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

startScreenCaptureByWindow

  • 通过窗口 ID 共享窗口。

    共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

    Parameters

    • windowSymbol: number

      指定待共享的窗口 ID

    • rect: CaptureRect

      可选）指定待共享的区域相对于整个窗口的位置。如不填，则表示共享整个窗口。 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容； 如果宽或高为 0，则共享整个窗口。详见 CaptureRect

    • param: CaptureParam

      屏幕共享的编码参数配置。详见 CaptureParam

    Returns number

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

startScreenCapturePreview

  • startScreenCapturePreview(): number

  • 双实例方法：开启预览共享屏幕。

    Returns number

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

startVideoDeviceTest

  • startVideoDeviceTest(): number

  • 开始视频设备测试。

    该方法测试视频采集设备是否正常工作。

    note

    请确保在调用该方法前已调用 enableVideo，且输入视频的 HWND/View 是有效的。

    Returns number

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

stopAllEffects

  • stopAllEffects(): number

  • 停止播放所有音效文件。

    Returns number

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

stopAudioDeviceLoopbackTest

  • stopAudioDeviceLoopbackTest(): number

  • 停止音频设备回路测试。

    Returns number

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

stopAudioMixing

  • stopAudioMixing(): number

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

    Returns number

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

stopAudioPlaybackDeviceTest

  • stopAudioPlaybackDeviceTest(): number

  • 停止播放设备测试。

    Returns number

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

stopAudioRecording

  • stopAudioRecording(): number

  • Returns number

stopAudioRecordingDeviceTest

  • stopAudioRecordingDeviceTest(): number

  • 停止音频录制设备测试。

    Returns number

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

stopChannelMediaRelay

  • stopChannelMediaRelay(): number

  • 停止跨频道媒体流转发。

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

    成功调用该方法后，SDK 会触发 channelMediaRelayState 回调。 如果报告 ChannelMediaRelayState 中的状态码 0 和 ChannelMediaRelayError 中的错误码 0，则表示已停止转发媒体流。

    note

    如果该方法调用不成功，SDK 会触发 channelMediaRelayState 回调，并报告 ChannelMediaRelayError 中的错误码 2 或 8。你可以调用 leaveChannel 方法离开频道，跨频道媒体流转发会自动停止。

    Returns number

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

stopEchoTest

  • stopEchoTest(): number

  • 停止语音通话回路测试。

    Returns number

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

stopEffect

  • stopEffect(soundId: number): number

  • 停止播放指定音效文件。

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID

    Returns number

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

stopLastmileProbeTest

  • stopLastmileProbeTest(): number

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

    Returns number

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

stopPreview

  • stopPreview(): number

  • 停止视频预览。

    Returns number

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

stopRtmpStream

  • stopRtmpStream(url: string): number

  • 结束 CDN 直播推流。

    since

    v3.6.1.4

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

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

    Parameters

    • url: string

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

    Returns number

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

stopScreenCapture

  • stopScreenCapture(): number

  • 停止共享屏幕。

    Returns number

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

stopScreenCapture2

  • stopScreenCapture2(): number

  • 双实例方法：停止共享屏幕。

    Returns number

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

stopScreenCapturePreview

  • stopScreenCapturePreview(): number

  • 双实例方法：停止预览共享屏幕。

    Returns number

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

stopVideoDeviceTest

  • stopVideoDeviceTest(): number

  • 停止视频设备测试。

    Returns number

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

subscribe

  • 订阅远端用户并初始化渲染器。

    Parameters

    • uid: number

      想要订阅的远端用户的 ID

    • view: Element

      初始化渲染器的 Dom

    • Optional options: RendererOptions

    Returns number

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

switchChannel

  • 快速切换直播频道。

    当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

    成功调用该方切换频道后，本地会先收到离开原频道的回调 leaveChannel， 再收到成功加入新频道的回调 joinedChannel。

    note

    该方法仅适用直播场景下的的观众。

    Parameters

    Returns number

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

takeSnapshot

  • takeSnapshot(channel: string, uid: number, filePath: string): number

  • 获取视频截图。

    since

    v3.6.1.4

    该方法用于对指定用户的视频流进行截图，生成一张 JPG 格式的图片，并保存至指定的路径。

    该方法是异步操作，调用返回时 SDK 并没有真正获取截图。成功调用该方法后，SDK 会触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。

    相比 enableContentInspect 方法，本方法是即时截图，截图会保存在你指定的本地路径。

    note
    • 该方法需要在加入频道后调用。
    • 如果用户的视频经过前处理，例如，添加了水印或美颜，生成的截图会包含前处理效果。

    Parameters

    • channel: string

      频道名。

    • uid: number

      用户 ID。如果要对本地用户的视频截图，uid 设为 0。

    • filePath: string

      截图的本地保存路径，需精确到文件名及格式， 例如：C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg（Windows）或 /App Sandbox/Library/Caches/example.jpg（iOS）或 ～/Library/Logs/example.jpg（macOS） 或 /storage/emulated/0/Android/data/<package name>/files/example.jpg（Android）。请确保目录存在且可写。

    Returns number

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

unRegisterMediaMetadataObserver

  • unRegisterMediaMetadataObserver(): number

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

    Returns number

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

unloadEffect

  • unloadEffect(soundId: number): number

  • 释放音效文件。

    Parameters

    • soundId: number

      指定音效的 ID。每个音效均有唯一的 ID

    Returns number

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

updateChannelMediaRelay

  • 更新媒体流转发的频道。

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

    成功调用该方法后，SDK 会触发 channelMediaRelayState 回调，向你报告 ChannelMediaRelayEvent 中的 事件码 7。

    note

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

    Parameters

    Returns number

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

updateRtmpTranscoding

  • 更新转码属性。

    since

    v3.6.1.4

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

    Parameters

    • transcoding: TranscodingConfig

      CDN 直播推流的转码属性，详见 LiveTranscoding 类。

    Returns number

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

updateScreenCaptureParameters

  • updateScreenCaptureParameters(param: CaptureParam): number

  • 更新屏幕共享的编码参数配置。

    Parameters

    Returns number

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

updateScreenCaptureRegion

  • updateScreenCaptureRegion(rect: object): number

  • 更新共享区域。

    note

    设置 rect 时你需要注意：

    • 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容
    • 如果 left 和 right 值一样，即宽为 0，则共享整个窗口
    • 如果 top 和 bottom 值一样，即高 为 0，则共享整个窗口

    Parameters

    • rect: object

      共享区域相对于整个屏幕左上角的位置。如不填，则表示共享整个窗口。由如下参数组成：

      • bottom: number

        窗口底部位置

      • left: number

        窗口左侧位置

      • right: number

        窗口右侧位置

      • top: number

        窗口顶部位置

    Returns number

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

videoSourceAdjustLoopbackRecordingSignalVolume

  • videoSourceAdjustLoopbackRecordingSignalVolume(volume: number): number

  • Parameters

    • volume: number

    Returns number

videoSourceAdjustRecordingSignalVolume

  • videoSourceAdjustRecordingSignalVolume(volume: number): number

  • Parameters

    • volume: number

    Returns number

videoSourceDisableAudio

  • videoSourceDisableAudio(): number

  • Returns number

videoSourceEnableAudio

  • videoSourceEnableAudio(): number

  • 双实例方法：启用音频模块（默认为关闭状态）。

    note

    • 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

    • 该方法重置整个引擎，响应速度较慢，因此建议使用如下方法来控制音频模块：

    Returns number

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

videoSourceEnableEncryption

  • videoSourceEnableEncryption(enabled: boolean, encryptionConfig: EncryptionConfig): number

  • 双实例方法：开启或关闭内置加密。

    since

    v3.2.0

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

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

    note

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

    Parameters

    • enabled: boolean

      是否开启内置加密：

      • true: 开启
      • false: 关闭
    • encryptionConfig: EncryptionConfig

      配置内置加密模式和密钥。

    Returns number

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

videoSourceEnableLoopbackRecording

  • videoSourceEnableLoopbackRecording(enabled: boolean, deviceName?: string | null): number

  • 双实例方法：开启声卡采集。

    启用声卡采集功能后，声卡播放的声音会被合到本地音频流中，从而可以发送到远端。

    note

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

    Parameters

    • enabled: boolean
    • Default value deviceName: string | null = null

      声卡的设备名。

      • 默认设为 null，即使用当前声卡采集。
      • 如果用户使用虚拟声卡，如 Soundflower，可以将虚拟声卡名称 "soundflower" 作为参数传入，SDK 会找到对应的虚拟声卡设备，并开始采集。Note: macOS 系统默认声卡 不支持采集功能，如需开启此功能需要 App 自己启用一个虚拟声卡，并将该虚拟声卡的名字 作为 deviceName 传入 SDK。声网测试并推荐 soundflower 作为虚拟声卡。

    Returns number

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

videoSourceEnableWebSdkInteroperability

  • videoSourceEnableWebSdkInteroperability(enabled: boolean): number
  • deprecated

    该方法已废弃。自 Native SDK v3.0.0 及之后，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。

    双实例方法：开启 videoSource 与 Web SDK 互通

    note

    该方法需要在 videoSourceInitialize 之后调用。

    Parameters

    • enabled: boolean

      是否开启与 Web SDK 之间的互通：

      • true：开启与 Web SDK 的互通
      • false：不开启与 Web SDK 的互通

    Returns number

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

videoSourceInitialize

  • videoSourceInitialize(appId: string, areaCode?: AREA_CODE, groupId?: undefined | string, bundleId?: undefined | string): number

  • 双实例方法：初始化 videoSource 对象

    Parameters

    • appId: string

      你在声网控制台创建项目的 APP ID

    • Default value areaCode: AREA_CODE = 4294967295
    • Optional groupId: undefined | string
    • Optional bundleId: undefined | string

    Returns number

    • 0：方法调用成功
    • < 0：方法调用失败
      • ERR_INVALID_APP_ID (101): App ID 无效，请检查你的 App ID

videoSourceJoin

  • videoSourceJoin(token: string, cname: string, info: string, uid: number, options?: ChannelMediaOptions): number

  • 双实例方法：videoSource 加入频道。

    Parameters

    • token: string

      在 App 服务器端生成的用于鉴权的 Token：

      • 安全要求不高：你可以填入在声网控制台获取到的临时 Token。详见获取临时 Token
      • 安全要求高：将值设为在 App 服务端生成的正式 Token。详见获取 Token
    • cname: string

      标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）：

      • 26 个小写英文字母 a-z
      • 26 个大写英文字母 A-Z
      • 10 个数字 0-9
      • 空格
      • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    • info: string

      频道信息

    • uid: number

      videoSource 的用户 ID。一个频道内不能出现相同的用户 ID。请确保 videoSource 用户 ID 和用户 joinChannel 时使用的 uid 不同。

    • Optional options: ChannelMediaOptions

    Returns number

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

videoSourceLeave

  • videoSourceLeave(): number

  • 双实例方法：videoSource 离开频道。

    Returns number

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

videoSourceMuteAllRemoteAudioStreams

  • videoSourceMuteAllRemoteAudioStreams(mute: boolean): number

  • Parameters

    • mute: boolean

    Returns number

videoSourceMuteAllRemoteVideoStreams

  • videoSourceMuteAllRemoteVideoStreams(mute: boolean): number

  • Parameters

    • mute: boolean

    Returns number

videoSourceMuteRemoteAudioStream

  • videoSourceMuteRemoteAudioStream(uid: number, mute: boolean): number

  • Parameters

    • uid: number
    • mute: boolean

    Returns number

videoSourceMuteRemoteVideoStream

  • videoSourceMuteRemoteVideoStream(uid: number, mute: boolean): number

  • Parameters

    • uid: number
    • mute: boolean

    Returns number

videoSourceRelease

  • videoSourceRelease(): number

  • 双实例方法：释放 videoSource 对象。

    Returns number

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

videoSourceRenewToken

  • videoSourceRenewToken(token: string): number

  • 双实例方法：更新 videoSource 的 Token

    Parameters

    • token: string

      新的 Token

    Returns number

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

videoSourceSetAddonLogFile

  • videoSourceSetAddonLogFile(filepath: string): number

  • Parameters

    • filepath: string

    Returns number

videoSourceSetChannelProfile

  • videoSourceSetChannelProfile(profile: number): number

  • 双实例方法：设置 videoSource 的频道场景。

    Parameters

    • profile: number

      频道场景：

      • 0：通信场景（默认）
      • 1：直播场景
      • 2：游戏模式

    Returns number

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

videoSourceSetEncryptionMode

  • videoSourceSetEncryptionMode(mode: string): number

  • 双实例方法：设置内置的加密方案。

    deprecated

    该方法自 v3.2.0 废弃，请改用 videoSourceEnableEncryption。

    RTC Native SDK 支持内置加密功能，默认使用 AES-128-XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。

    同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

    note

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

    Parameters

    • mode: string

      加密方式。目前支持以下几种：

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

    Returns number

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

videoSourceSetEncryptionSecret

  • videoSourceSetEncryptionSecret(secret: string): number
  • deprecated

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

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

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

    note

    为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

    Parameters

    • secret: string

      加密密码

    Returns number

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

videoSourceSetLocalAccessPoint

videoSourceSetLogFile

  • videoSourceSetLogFile(filepath: string): number

  • 双实例方法：设置屏幕共享对象的日志。

    note

    请在初始化 videoSource 后调用。

    Parameters

    • filepath: string

      日志文件的完整路径

    Returns number

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

videoSourceSetParameters

  • videoSourceSetParameters(parameter: string): number

  • 双实例方法：通过 JSON 配置 SDK 提供技术预览或特别定制功能。

    Parameters

    • parameter: string

      JSON 格式的字符串。

    Returns number

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

videoSourceSetProcessDpiAwareness

  • videoSourceSetProcessDpiAwareness(): number

  • Returns number

videoSourceSetScreenCaptureContentHint

  • 双实例方法：设置共享屏幕的内容类型。

    SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。 如果不调用该方法，SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE (0)，即无指定的内容类型。

    Parameters

    Returns number

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

videoSourceSetVideoProfile

  • videoSourceSetVideoProfile(profile: VIDEO_PROFILE_TYPE, swapWidthAndHeight?: boolean): number

  • 双实例方法：设置摄像头流的视频属性。

    note

    请在 startScreenCapture2 后调用该方法。

    Parameters

    • profile: VIDEO_PROFILE_TYPE

      视频属性

    • Default value swapWidthAndHeight: boolean = false

      是否交换视频的宽和高：

      • true：交换视频的宽和高
      • false：不交换视频的宽和高（默认）

    Returns number

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

videoSourceStartScreenCaptureByDisplayId

videoSourceStartScreenCaptureByScreen

  • 双实例方法：通过屏幕信息共享屏幕。

    note

    设置 rect 时你需要注意：

    • 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容
    • 如果 width 或 height 为 0，则共享整个窗口

    Parameters

    • screenSymbol: ScreenSymbol

      屏幕标识：

      • macOS 系统：屏幕 ID
      • Windows 系统：屏幕位置
    • rect: CaptureRect

      （可选）共享区域相对于整个屏幕左上角的位置。如不填，则表示共享整个屏幕。

    • param: CaptureParam

      屏幕共享的编码配置

    Returns number

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

videoSourceStartScreenCaptureByWindow

  • 双实例方法：通过窗口信息共享屏幕。

    note

    设置 rect 时你需要注意：

    • 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容
    • 如果 width 或 height 为 0，则共享整个窗口

    Parameters

    • windowSymbol: number

      窗口 ID

    • rect: CaptureRect

      （可选）共享区域相对于整个窗口左上角的位置。如不填，则表示共享整个窗口。

    • param: CaptureParam

      屏幕共享的编码配置

    Returns number

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

videoSourceUpdateScreenCaptureParameters

  • videoSourceUpdateScreenCaptureParameters(param: CaptureParam): number

  • 双实例方法：更新共享屏幕的编码配置。

    Parameters

    Returns number

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

videoSourceUpdateScreenCaptureRegion

  • videoSourceUpdateScreenCaptureRegion(rect: object): number

  • 双实例方法：更新共享区域。

    note

    设置 rect 时你需要注意：

    • 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容
    • 如果 left 和 right 值一样，即宽为 0，则共享整个窗口
    • 如果 top 和 bottom 值一样，即高 为 0，则共享整个窗口

    Parameters

    • rect: object

      共享区域相对于整个屏幕左上角的位置。如不填，则表示共享整个窗口。由如下参数组成：

      • bottom: number

        窗口底部位置

      • left: number

        窗口左侧位置

      • right: number

        窗口右侧位置

      • top: number

        窗口顶部位置

    Returns number

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