文档中心
视频通话 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

Agora React Native API Reference

概览 RtcEngine RtcEngineEvents RtcChannel RtcChannelEvents 警告码 错误码

RtcEngine 类提供了供 App 调用的主要接口方法。

Hierarchy

  • RtcEngine

Implements

  • RtcEngineInterface

Index

Methods

Methods

addInjectStreamUrl

  • 输入在线媒体流。 该方法通过在服务端拉取视频流并发送到频道中，将正在播出的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。

    调用该方法后，SDK 会在本地触发 StreamInjectedStatus 回调， 报告输入在线媒体流的状态； 成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 UserJoined 回调， 其中 uid 为 666。

    Warning

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

    Note

    • 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
    • 该方法仅适用于直播场景中的主播用户。
    • 频道内同一时间只允许输入一个在线媒体流。

    Parameters

    • url: string

      添加到直播中的视频流 URL 地址，支持 RTMP，HLS，HTTP-FLV 协议传输。

      • 支持的音频编码格式：AAC
      • 支持的视频编码格式：H264 (AVC)

    • config: LiveInjectStreamConfig

      外部输入的音视频流的配置。

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument): 输入的 URL 为空。请重新调用该方法，并确认输入的媒体流的 URL 是有效的
      • 3(NotReady)：用户没有加入频道。
      • 4(NotSupported): 频道非直播场景。请调用 setChannelProfile 并将频道设置为直播场景再调用该方法
      • 7(NotInitialized): SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。

addListener

  • addListener<EventType>(event: EventType, listener: RtcEngineEvents[EventType]): Subscription

  • 添加 RtcEngineEvents 回调事件。

    设置后，你可以通过 RtcEngineEvents 回调监听对应 RtcEngine 对象的事件、获取数据。

    Type parameters

    Parameters

    • event: EventType

      事件类型。

    • listener: RtcEngineEvents[EventType]

      RtcEngineEvents 回调事件。

    Returns Subscription

addPublishStreamUrl

  • addPublishStreamUrl(url: string, transcodingEnabled: boolean): Promise<void>

  • 增加旁路推流地址。

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

    Note

    • 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
    • 该方法仅适用直播场景。
    • 请确保在成功加入频道后才能调用该接口。
    • 该方法每次只能增加一路旁路推流地址。如需推送多路流，则需多次调用该方法。
    • Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

    Parameters

    • url: string

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

    • transcodingEnabled: boolean

      是否转码。如果设为 true，则需要在该方法前先调用 setLiveTranscoding 方法。

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

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument)：参数无效，一般是 URL 为空或是长度为 0 的字符串
      • 7(NotInitialized)：推流时未初始化引擎。

addVideoWatermark

  • addVideoWatermark(watermarkUrl: string, options: WatermarkOptions): Promise<void>

  • 添加本地视频水印。

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

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

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

    Note

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

    Parameters

    • watermarkUrl: string

      待添加的水印图片的本地路径。本方法支持从本地路径和 assets 路径添加水印图片。 如果使用 assets 路径，需要以 /assets/ 开头。

    • options: WatermarkOptions

      待添加的水印图片的设置选项。

    Returns Promise<void>

adjustAudioMixingPlayoutVolume

  • adjustAudioMixingPlayoutVolume(volume: number): Promise<void>

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

    该方法调节混音里音乐文件在本端播放的音量大小。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

    Parameters

    • volume: number

      伴奏音量范围为 [0,100]。默认 100 为原始文件音量。

    Returns Promise<void>

adjustAudioMixingPublishVolume

  • adjustAudioMixingPublishVolume(volume: number): Promise<void>

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

    Note

    该方法调节混音里音乐文件在远端播放的音量大小。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

    Parameters

    • volume: number

      伴奏音量范围为 [0,100]。默认 100 为原始文件音量。

    Returns Promise<void>

adjustAudioMixingVolume

  • adjustAudioMixingVolume(volume: number): Promise<void>

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

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

    Note

    • 该方法调节混音里伴奏在本端和远端播放的音量大小。请在频道内调用该方法。
    • 调用该方法不影响调用 playEffect 播放音效文件的音量。

    Parameters

    • volume: number

      伴奏音量范围为 [0,100]。默认 100 为原始文件音量。

    Returns Promise<void>

adjustPlaybackSignalVolume

  • adjustPlaybackSignalVolume(volume: number): Promise<void>

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

    Note

    • 该方法调节的是本地播放的所有远端用户混音后的音量。
    • 静音本地音频需同时调用该方法和 adjustAudioMixingVolume 方法， 并将 volume 参数设置为 0。

    Parameters

    • volume: number

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

    Returns Promise<void>

adjustRecordingSignalVolume

  • adjustRecordingSignalVolume(volume: number): Promise<void>

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

    Parameters

    • volume: number

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

    Returns Promise<void>

adjustUserPlaybackSignalVolume

  • adjustUserPlaybackSignalVolume(uid: number, volume: number): Promise<void>

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

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

    Note

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

    Parameters

    • uid: number

      远端用户的 ID。

    • volume: number

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

      • 0：静音。
      • 100：原始音量。

    Returns Promise<void>

clearVideoWatermarks

  • clearVideoWatermarks(): Promise<void>

  • 删除本地视频水印。

    该方法删除使用 addVideoWatermark 方法添加的本地视频水印。

    Returns Promise<void>

complain

  • complain(callId: string, description: string): Promise<void>

  • 投诉通话质量。

    该方法让用户就通话质量进行投诉。一般在通话结束后调用。

    Parameters

    • callId: string

      通话 getCallId 函数获取的通话 ID。

    • description: string

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

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument): 参数无效。
      • 3(NotReady)：SDK 初始化失败，请尝试重新初始化 SDK。

configRhythmPlayer

  • 配置虚拟节拍器。

    since

    v3.4.2

    调用 startRhythmPlayer 后，你可以调用该方法重新配置虚拟节拍器。

    note

    重新配置虚拟节拍器后，SDK 会从头开始播放指定的音效文件，并根据你设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。

    Parameters

    Returns Promise<void>

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

createDataStream

  • createDataStream(reliable: boolean, ordered: boolean): Promise<number>

  • 创建数据流。

    deprecated

    This method is deprecated from v3.3.1. Use the createDataStreamWithConfig method instead.

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

    Parameters

    • reliable: boolean

      是否可靠。

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

      是否有序。

      • true: 接收方会按照发送方发送的顺序收到数据包。
      • false: 接收方不保证按照发送方发送的顺序收到数据包。

    Returns Promise<number>

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

createDataStreamWithConfig

  • 创建数据流。

    since

    v3.3.1

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

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

    Parameters

    Returns Promise<number>

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

destroy

  • destroy(): Promise<void>

  • 销毁 RtcEngine 实例。

    该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行语音通话， 不需要时则将资源释放出来用于其他操作，该方法对这类程序可能比较有用。只要调用了 destroy 方法， 用户将无法再使用和回调该 SDK 内的其它方法。如需再次使用通信功能，必须重新创建一个 RtcEngine 实例。

    Note

    • 该方法需要在子线程中操作。
    • 该方法为同步调用。在等待 RtcEngine 实例资源释放后再返回。 APP 不应该在 SDK 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。
    • 如果需要在销毁后再次创建 RtcEngine 实例，需要等待 destroy 方法执行结束， 收到返回值后才能再创建实例。

    Returns Promise<void>

disableAudio

  • disableAudio(): Promise<void>

  • 关闭音频模块。

    Note

    • 该方法设置的是音频模块为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
    • 该方法开启/关闭整个音频模块，响应速度较慢，因此 Agora 建议使用如下方法来控制音频模块：

    Returns Promise<void>

disableLastmileTest

  • disableLastmileTest(): Promise<void>

  • 关闭网络测试。

    Returns Promise<void>

disableVideo

  • disableVideo(): Promise<void>

  • 关闭视频模块。

    该方法用于关闭视频。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频频模式。 调用 enableVideo 方法可开启视频模式。

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

    Note

    • 该方法设置的是音频模块为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

    • 该方法关闭整个音频模块，响应速度较慢，因此 Agora 建议使用如下方法来控制视频模块：

    Returns Promise<void>

enableAudio

  • enableAudio(): Promise<void>

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

    Note

    • 该方法设置的是音频模块为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
    • 该方法开启整个音频模块，响应速度较慢，因此我们建议使用如下方法来控制音频模块：

    Returns Promise<void>

enableAudioVolumeIndication

  • enableAudioVolumeIndication(interval: number, smooth: number, report_vad: boolean): Promise<void>

  • 启用说话者音量提示。

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

    Parameters

    • interval: number

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

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

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

    • report_vad: boolean

      是否开启人声检测

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

    Returns Promise<void>

enableDeepLearningDenoise

  • enableDeepLearningDenoise(enabled: boolean): Promise<void>

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

    since

    v3.3.1

    AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下，SDK 才会成功开启 AI 降噪模式。

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

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

    note

    该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。

    Parameters

    • enabled: boolean

      是否开启 AI 降噪模式：

      • true:（默认）开启。
      • false: 关闭。

    Returns Promise<void>

    • 0: 方法调用成功
    • 错误码: 方法调用失败

enableDualStreamMode

  • enableDualStreamMode(enabled: boolean): Promise<void>

  • 开/关视频双流模式。

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

    Parameters

    • enabled: boolean

      指定双流或者单流模式：

      • true: 双流。
      • false: （默认）单流。

    Returns Promise<void>

enableEncryption

  • 开启或关闭内置加密。

    since

    v3.1.2。

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

    同一频道内所有用户必须使用相同的加密模式和密钥。一旦所有用户都离开频道，该频道的加密密钥会自动清除。

    Note

    • 如果开启了内置加密，则不能使用 RTMP 推流功能。
    • Agora 支持 4 种加密模式。除 SM4128ECB 模式外，其他加密模式都需要在集成 SDK 时，额外添加加密库文件。详见《媒体流加密》。

    Parameters

    • enabled: boolean

      是否开启内置加密：

      • true：开启内置加密。
      • false：开启内置加密。
    • config: EncryptionConfig

      配置内置加密模式和密钥。详见 EncryptionConfig。

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument): 参数无效。
      • 4(NotSupported): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
      • 7(NotInitialized): SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。

enableFaceDetection

  • enableFaceDetection(enable: boolean): Promise<void>

  • 开启/关闭本地人脸检测。

    开启本地人脸检测后，SDK 会触发 FacePositionChanged 回调向你报告人脸检测的信息：

    • 摄像头采集的画面大小。
    • 人脸在画面中的位置。
    • 人脸距设备屏幕的距离。

    Parameters

    • enable: boolean

      是否开启人脸检测：

      • true: 开启人脸检测。
      • false: （默认）关闭人脸检测。

    Returns Promise<void>

enableInEarMonitoring

  • enableInEarMonitoring(enabled: boolean): Promise<void>

  • 开启耳返功能。

    Parameters

    • enabled: boolean

      是否开启耳返功能：

      • true: 开启耳返功能。
      • false: （默认）关闭耳返功能。

    Returns Promise<void>

enableLastmileTest

  • enableLastmileTest(): Promise<void>

  • 启用网络测试。

    该方法启用网络连接质量测试，用于检测用户网络接入质量。默认该功能为关闭状态。该方法主要用于以下两种场景：

    • 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
    • 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。 无论哪种场景，启用该方法会消耗一定的网络流量，影响通话质量。在收到 LastmileQuality 回调后 须调用 disableLastmileTest 停止测试，再加入频道或切换用户角色。

    Note

    该方法请勿与 startLastmileProbeTest 同时使用。

    • 调用该方法后，在收到 LastmileQuality 回调之前请不要调用其他方法， 否则可能会由于 API 操作过于频繁导致此回调无法执行。
    • 直播场景下，主播在加入频道后，请勿调用该方法。
    • 加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率 与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest，SDK 均会自动停止带宽占用。

    Returns Promise<void>

enableLocalAudio

  • enableLocalAudio(enabled: boolean): Promise<void>

  • 开启/关闭本地音频采集。

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

    该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。

    语音功能关闭或重新开启后，会收到回调 LocalAudioStateChanged， 并报告 Stopped 或 Recording。

    Note 该方法与 muteLocalAudioStream 的区别在于：

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

    Parameters

    • enabled: boolean

      是否开启本地语音。

      • true:（默认）重新开启本地语音，即开启本地语音采集。
      • false: 关闭本地语音，即停止本地语音采集。

    Returns Promise<void>

enableLocalVideo

  • enableLocalVideo(enabled: boolean): Promise<void>

  • 开启/关闭本地视频采集。

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

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

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

    Note

    该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel 后仍然有效。

    Parameters

    • enabled: boolean

      是否启用本地视频：

      • true: 开启本地视频采集和渲染（默认）。
      • false: 关闭使用本地摄像头设备。关闭后， 远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。

    Returns Promise<void>

enableSoundPositionIndication

  • enableSoundPositionIndication(enabled: boolean): Promise<void>

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

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

    Parameters

    • enabled: boolean

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

      • true: 开启。
      • false: （默认）关闭。

    Returns Promise<void>

enableVideo

  • enableVideo(): Promise<void>

  • 启用视频模块。

    该方法用于打开视频模式。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启视频模式， 在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。

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

    Note

    • 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
    • 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制视频模块：

    Returns Promise<void>

enableWebSdkInteroperability

  • enableWebSdkInteroperability(enabled: boolean): Promise<void>

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

    deprecated

    该方法已废弃。自 v3.0.1 起，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。

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

    该方法仅在直播场景下适用，通信场景下默认互通是打开的。

    Parameters

    • enabled: boolean

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

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

    Returns Promise<void>

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): Promise<number>

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

    Note

    该方法获取当前伴奏播放进度，单位为毫秒。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

    Returns Promise<number>

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

getAudioMixingDuration

  • getAudioMixingDuration(filePath?: undefined | string): Promise<number>

  • 获取音乐文件的时长。

    Note

    该方法获取音乐文件时长，单位为毫秒。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

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

    Parameters

    • Optional filePath: undefined | string

      @since v3.4.2 文件路径，需精确到文件名及后缀。

      • Android：支持本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。 例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：支持文件的绝对路径，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Best Practices for iOS Audio。

    Returns Promise<number>

    • 方法调用成功，并返回伴奏时长。
    • < 0：方法调用失败。

getAudioMixingPlayoutVolume

  • getAudioMixingPlayoutVolume(): Promise<number>

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

    该方法获取音乐文件的本地播放音量。该接口可以方便开发者排查音量相关问题。

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

    Returns Promise<number>

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

getAudioMixingPublishVolume

  • getAudioMixingPublishVolume(): Promise<number>

  • 获取音乐文件的远端播放音量。

    该方法获取音乐文件的远端播放音量。该接口可以方便开发者排查音量相关问题。

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

    Returns Promise<number>

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

getCallId

  • getCallId(): Promise<string>

  • 获取通话 ID。

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

    Returns Promise<string>

    通话 ID。

getCameraMaxZoomFactor

  • getCameraMaxZoomFactor(): Promise<number>

  • 获取摄像头支持最大缩放比例。

    Returns Promise<number>

    该相机支持的最大缩放比例。

getConnectionState

getEffectCurrentPosition

  • getEffectCurrentPosition(soundId: number): Promise<number>

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

    since

    v3.4.2

    note

    该方法需要在 playEffect 后调用。

    Parameters

    • soundId: number

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

    Returns Promise<number>

    • ≥ 0：方法调用成功，返回指定音效文件的播放进度（毫秒）。
    • < 0：方法调用失败。

getEffectDuration

  • getEffectDuration(filePath: string): Promise<number>

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

    since

    v3.4.2

    note

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

    Parameters

    • filePath: string

      文件路径，需精确到文件名及后缀。

      • Android：支持本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。 例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：支持文件的绝对路径，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Best Practices for iOS Audio。

    Returns Promise<number>

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

getEffectsVolume

  • getEffectsVolume(): Promise<number>

  • 获取所有音效文件播放音量, 范围为 [0.0,100.0]。

    Returns Promise<number>

    • 方法调用成功返回音效的音量值。
    • 错误码: 方法调用失败。

getNativeHandle

  • getNativeHandle(): Promise<number>

  • 该方法获取 native SDK engine 的 C++ handle，用于包括注册音视频帧观测器在内的特殊场景。

    Returns Promise<number>

getUserInfoByUid

  • getUserInfoByUid(uid: number): Promise<UserInfo>

  • 通过 UID 获取用户信息。

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

    Parameters

    • uid: number

      用户 ID。该参数为必填。

    Returns Promise<UserInfo>

getUserInfoByUserAccount

  • getUserInfoByUserAccount(userAccount: string): Promise<UserInfo>

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

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

    Parameters

    • userAccount: string

      用户 User Account。该参数为必填。

    Returns Promise<UserInfo>

isCameraAutoFocusFaceModeSupported

  • isCameraAutoFocusFaceModeSupported(): Promise<boolean>

  • 检测设备是否支持人脸对焦功能。

    Returns Promise<boolean>

    • true：设备支持人脸对焦功能。
    • false：设备不支持人脸对焦功能。

isCameraExposurePositionSupported

  • isCameraExposurePositionSupported(): Promise<boolean>

  • 检测设备是否支持手动曝光功能。

    Returns Promise<boolean>

    • true：设置支持手动曝光功能。
    • false：设备不支持手动曝光功能。

isCameraFocusSupported

  • isCameraFocusSupported(): Promise<boolean>

  • 检测设备是否支持手动对焦功能。

    Returns Promise<boolean>

    • true：设备支持手动对焦功能。
    • false：设备不支持手动对焦功能。

isCameraTorchSupported

  • isCameraTorchSupported(): Promise<boolean>

  • 检测设备是否支持闪光灯常开。

    Returns Promise<boolean>

    • true：设备支持闪光灯常开。
    • false：设备不支持闪光灯常开。

isCameraZoomSupported

  • isCameraZoomSupported(): Promise<boolean>

  • 检测设备是否支持摄像头缩放功能。

    Returns Promise<boolean>

    • true：设备支持相机缩放功能。
    • false：设备不支持相机缩放功能。

isSpeakerphoneEnabled

  • isSpeakerphoneEnabled(): Promise<boolean>

  • 检查扬声器状态启用状态。

    note

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

    Returns Promise<boolean>

    • true：扬声器已开启，语音会输出到扬声器。
    • false：扬声器未开启，语音会输出到非扬声器（听筒，耳机等）。

joinChannel

  • joinChannel(token: string | undefined | null, channelName: string, optionalInfo: string | undefined | null, optionalUid: number, options?: ChannelMediaOptions): Promise<void>

  • 加入频道。

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

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

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

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

    Note

    • 频道内每个用户的 UID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 UID。 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。
    • 请确保用于生成 Token 的 App ID 和 create 方法创建 RtcEngine 对象时用的 App ID 一致。

    Parameters

    • token: string | undefined | null

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

    • channelName: string

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

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

      （非必选项）开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。

    • optionalUid: number

      （非必选项）用户 ID，32 位无符号整数。建议设置范围：1 到 (2^32-1)，并保证唯一性。 如果不指定（即设为 0），SDK 会自动分配一个，并在 JoinChannelSuccess 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。

    • Optional options: ChannelMediaOptions

      @since v3.3.1 频道媒体设置选项。详见 ChannelMediaOptions。

    Returns Promise<void>

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

joinChannelWithUserAccount

  • joinChannelWithUserAccount(token: string | undefined | null, channelName: string, userAccount: string, options?: ChannelMediaOptions): Promise<void>

  • 使用 User Account 加入频道。

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

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

    Note

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

    Parameters

    • token: string | undefined | null

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

    • channelName: string

      标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）：

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

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

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

      @since v3.3.1 频道媒体设置选项。详见 ChannelMediaOptions。

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument): 参数无效。
      • 3(NotReady): SDK 初始化失败，请尝试重新初始化 SDK。
      • 5(Refused): 调用被拒绝。

leaveChannel

  • leaveChannel(): Promise<void>

  • 离开频道。

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

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

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

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

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

    Note

    • 如果你调用了 leaveChannel 后立即调用 destroy 方法，SDK 将 无法触发 LeaveChannel 回调。
    • 如果你在旁路推流过程中调用了 leaveChannel 方法， SDK 将自动调用 removePublishStreamUrl 方法。

    Returns Promise<void>

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

muteAllRemoteAudioStreams

  • muteAllRemoteAudioStreams(muted: boolean): Promise<void>

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

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

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

    Parameters

    • muted: boolean

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

    Returns Promise<void>

muteAllRemoteVideoStreams

  • muteAllRemoteVideoStreams(muted: boolean): Promise<void>

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

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

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

    Parameters

    • muted: boolean

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

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

    Returns Promise<void>

muteLocalAudioStream

  • muteLocalAudioStream(muted: boolean): Promise<void>

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

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

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

    Parameters

    • muted: boolean

      是否取消发布本地音频流。 - true: 取消发布。 - false:（默认）发布。

    Returns Promise<void>

muteLocalVideoStream

  • muteLocalVideoStream(muted: boolean): Promise<void>

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

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

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

    Parameters

    • muted: boolean

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

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

    Returns Promise<void>

muteRemoteAudioStream

  • muteRemoteAudioStream(uid: number, muted: boolean): Promise<void>

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

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

    Parameters

    • uid: number

      指定用户的用户 ID。

    • muted: boolean

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

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

    Returns Promise<void>

muteRemoteVideoStream

  • muteRemoteVideoStream(uid: number, muted: boolean): Promise<void>

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

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

    Parameters

    • uid: number

      指定用户的用户 ID。

    • muted: boolean

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

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

    Returns Promise<void>

pauseAllEffects

  • pauseAllEffects(): Promise<void>

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

    Returns Promise<void>

pauseAudioMixing

  • pauseAudioMixing(): Promise<void>

  • 暂停播放音乐文件及混音。

    该方法暂停播放伴奏。请在频道内调用该方法。

    Returns Promise<void>

pauseEffect

  • pauseEffect(soundId: number): Promise<void>

  • 暂停播放指定音效文件。

    Parameters

    • soundId: number

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

    Returns Promise<void>

playEffect

  • playEffect(soundId: number, filePath: string, loopCount: number, pitch: number, pan: number, gain: number, publish: Boolean, startPos?: undefined | number): Promise<void>

  • 播放指定音效文件。该方法播放指定的本地或在线音效文件。你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益，以及远端用户是否能听到该音效。

    你可以多次调用该方法，通过传入不同的音效文件的 soundId 和 filePath，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。

    调用该方法播放音效结束后，SDK 会触发 AudioEffectFinished 回调。

    Parameters

    • soundId: number

      音效文件的 ID。每个音效均有唯一的 ID。如果你已通过 preloadEffect 将音效加载至内存，确保这里的 soundID 与 preloadEffect 设置的 soundId 相同。

    • filePath: string

      文件路径，需精确到文件名及后缀。

      • Android：支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：支持文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Best Practices for iOS Audio。
    • loopCount: number

      音效文件循环播放的次数：

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

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

    • pan: number

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

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

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

    • publish: Boolean

      是否将音效发布到远端：

      • true: 音效在本地播放的同时，会发布到 Agora 云上，因此远端用户也能听到该音效。
      • false: 音效不会发布到 Agora 云上，因此只能在本地听到该音效。
    • Optional startPos: undefined | number

      @since v3.4.2 音乐文件的播放位置，单位为毫秒。

    Returns Promise<void>

preloadEffect

  • preloadEffect(soundId: number, filePath: string): Promise<void>

  • 将音效文件预加载至内存。

    支持音频格式为 mp3、mp4、m4a、aac、3gp、mkv 和 wav。

    Note

    • 该方法不支持预加载在线音效文件。
    • 为保证通话流畅度，请注意控制音效文件的大小。Agora 推荐你在加入频道前调用该方法。

    Parameters

    • soundId: number

      音效文件的 ID。

    • filePath: string

      文件路径，需精确到文件名及后缀。

      • Android：支持本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。 例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：支持文件的绝对路径，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Best Practices for iOS Audio。

    Returns Promise<void>

rate

  • rate(callId: string, rating: Rate, description?: undefined | string): Promise<void>

  • 给通话评分。

    Parameters

    • callId: string

      通过 getCallId 函数获取的通话 ID。

    • rating: Rate

      给通话的评分，最低 1 分，最高 5 分，如超过这个范围，SDK 会 返回 InvalidArgument(2) 错误。

    • Optional description: undefined | string

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

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument): 参数无效。
      • 3(NotReady)：SDK 初始化失败，请尝试重新初始化 SDK。

registerLocalUserAccount

  • registerLocalUserAccount(appId: string, userAccount: string): Promise<void>

  • 注册本地用户 User Account。

    该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。

    成功注册 User Account 后，本地会触发 LocalUserRegistered 回调， 告知本地用户的 UID 和 User Account。

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

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

    Note

    • userAccount 不能为空，否则该方法不生效。
    • 请确保在该方法中设置的 userAccount 在频道中的唯一性。
    • 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

    Parameters

    • appId: string

      你的项目在 Agora 控制台注册的 App ID。

    • userAccount: string

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

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

    Returns Promise<void>

registerMediaMetadataObserver

  • registerMediaMetadataObserver(): Promise<void>

  • 注册媒体 Metadata 观测器。

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

    Note

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

    Returns Promise<void>

removeAllListeners

  • removeAllListeners<EventType>(event?: EventType): void

  • 删除所有的回调句柄。

    Type parameters

    Parameters

    Returns void

removeInjectStreamUrl

  • removeInjectStreamUrl(url: string): Promise<void>

  • 删除输入的在线媒体流。

    成功删除后，会触发 UserOffline 回调，其中 uid 为 666。

    Warning

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

    Parameters

    • url: string

      已输入、待删除的外部视频流 URL 地址，格式为 HTTP 或 HTTPS。

    Returns Promise<void>

removeListener

  • removeListener<EventType>(event: EventType, listener: RtcEngineEvents[EventType]): void

  • 删除指定的 RtcEngineEvents 回调句柄。

    该方法删除指定的回调句柄。对于某些注册的回调句柄， 如果你在收到相应回调事件后无需再次接收回调消息，可以调用该方法移除回调句柄。

    Type parameters

    Parameters

    • event: EventType

      事件类型。

    • listener: RtcEngineEvents[EventType]

      RtcEngineEvents 回调句柄。

    Returns void

removePublishStreamUrl

  • removePublishStreamUrl(url: string): Promise<void>

  • 删除旁路推流地址。

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

    Note

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

    Parameters

    • url: string

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

    Returns Promise<void>

renewToken

  • renewToken(token: string): Promise<void>

  • 更新 Token。

    该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。以下两种情况下，app 应重新获取 Token，然后 调用 renewToken 更新 Token，否则 SDK 无法和服务器建立连接：

    Parameters

    • token: string

      新的 Token。

    Returns Promise<void>

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

resumeAllEffects

  • resumeAllEffects(): Promise<void>

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

    Returns Promise<void>

resumeAudioMixing

  • resumeAudioMixing(): Promise<void>

  • 恢复播放音乐文件及混音。

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

    Returns Promise<void>

resumeEffect

  • resumeEffect(soundId: number): Promise<void>

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

    Parameters

    • soundId: number

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

    Returns Promise<void>

sendCustomReportMessage

  • sendCustomReportMessage(id: string, category: string, event: string, label: string, value: number): Promise<void>

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

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

    Parameters

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

    Returns Promise<void>

sendMetadata

  • sendMetadata(metadata: string): Promise<void>

  • 发送 Metadata。

    Parameters

    • metadata: string

      想要发送的 Metadata。

      Note 请确保在该方法中传入的 Metadata 大小不超过 setMaxMetadataSize 中设定的值。

    Returns Promise<void>

sendStreamMessage

  • sendStreamMessage(streamId: number, message: string): Promise<void>

  • 发送数据流。

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

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

    Note

    • 请确保在调用该方法前，已调用 createDataStream 创建了数据通道。
    • 该方法仅适用于通信场景以及直播场景下的主播用户。

    Parameters

    • streamId: number

      数据流 ID，createDataStream 的返回值。

    • message: string

      待发送的数据。

    Returns Promise<void>

setAudioEffectParameters

  • setAudioEffectParameters(preset: AudioEffectPreset, param1: number, param2: number): Promise<void>

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

    since

    v3.2.0。

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

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

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

    Note

    • 该方法在加入频道前后都能调用。
    • 为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。
    • 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法会调用失败。
    • 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
    • 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
      • setAudioEffectPreset
      • setVoiceBeautifierPreset
      • setLocalVoiceReverbPreset
      • setLocalVoiceChanger
      • setLocalVoicePitch
      • setLocalVoiceEqualization
      • setLocalVoiceReverb
      • setVoiceConversionPreset

    Parameters

    • preset: AudioEffectPreset

      SDK 预设的音效：

      • 3D 人声音效：RoomAcoustics3DVoice
        • 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicStandardStereo(3) 或 MusicHighQualityStereo(5)，否则该枚举设置无效。
        • 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。
      • 电音音效：PitchCorrection。获取更好的人声效果，Agora 建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality(4) or MusicHighQualityStereo(5)。
    • param1: number
      • 如果 preset 设为 RoomAcoustics3DVoice，则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。
      • 如果 preset 设为 PitchCorrection，则 param1 表示电音音效的基础调式。可设为如下值：
        • 1: （默认）自然大调。
        • 2: 自然小调。
        • 3: 和风小调。
    • param2: number
      • 如果 preset 设为 RoomAcoustics3DVoice，你需要将 param2 设置为 0。
      • 如果 preset 设为 PitchCorrection，则 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 Promise<void>

setAudioEffectPreset

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

    since

    v3.2.0。

    调用该方法可以为本地发流用户设置 SDK 预设的人声音效，且不会改变原声的性别特征。设置音效后，频道 内所有用户都能听到该效果。

    根据不同的场景，你可以为用户设置不同的音效。

    为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。

    Note

    • 该方法在加入频道前后都能调用。
    • 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法会调用失败。
    • 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
    • 如果调用该方法并设置除 RoomAcoustics3DVoice 或 PitchCorrection 外的枚举，请勿再调用 setAudioEffectParameters，否则该方法设置的效果会被覆盖。
    • 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
      • setVoiceBeautifierPreset
      • setLocalVoiceReverbPreset
      • setLocalVoiceChanger
      • setLocalVoicePitch
      • setLocalVoiceEqualization
      • setLocalVoiceReverb
      • setVoiceConversionPreset

    Parameters

    Returns Promise<void>

setAudioMixingPitch

  • setAudioMixingPitch(pitch: number): Promise<void>

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

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

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

    Parameters

    • pitch: number

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

    Returns Promise<void>

setAudioMixingPosition

  • setAudioMixingPosition(pos: number): Promise<void>

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

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

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

    Parameters

    • pos: number

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

    Returns Promise<void>

setAudioProfile

  • 设置音频编码配置。

    Note

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

    Parameters

    • profile: AudioProfile

      设置采样率，码率，编码模式和声道数。

    • scenario: AudioScenario

      设置音频应用场景。不同的音频场景下，设备的系统音量是不同的。

    Returns Promise<void>

setAudioSessionOperationRestriction

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

    该方法限制 Agora SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App 会希望限制 Agora SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。

    该接口可以在任意时候调用，可以在任意时候通过该方法把控制权交还给 SDK。

    Note 一旦调用该方法限制了 Agora SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session 进行相关设置，而需要用户自己或第三方组件进行维护。

    Parameters

    Returns Promise<void>

setBeautyEffectOptions

  • setBeautyEffectOptions(enabled: boolean, options: BeautyOptions): Promise<void>

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

    Note

    • 该方法需要在 enableVideo 之后调用。
    • 在 Android 平台，该方法仅适用于 Android 4.4 及以上版本。

    Parameters

    • enabled: boolean

      是否开启美颜功能：

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

      美颜选项。

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 4(NotSupported)：当前设备版本低于 Android 4.4，不支持该操作。

setCameraAutoFocusFaceModeEnabled

  • setCameraAutoFocusFaceModeEnabled(enabled: boolean): Promise<void>

  • 设置是否开启人脸对焦功能。

    Parameters

    • enabled: boolean

      是否开启人脸对焦：

      • true: 开启人脸对焦功能。
      • false: （默认）关闭人脸对焦功能。

    Returns Promise<void>

setCameraCapturerConfiguration

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

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

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

    Note

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

    Parameters

    Returns Promise<void>

setCameraExposurePosition

  • setCameraExposurePosition(positionXinView: number, positionYinView: number): Promise<void>

  • 设置手动曝光位置。

    成功调用该方法后，本地会触发 CameraExposureAreaChanged 回调。

    Parameters

    • positionXinView: number

      触摸点相对于视图的横坐标。

    • positionYinView: number

      触摸点相对于视图的纵坐标。

    Returns Promise<void>

setCameraFocusPositionInPreview

  • setCameraFocusPositionInPreview(positionX: number, positionY: number): Promise<void>

  • 设置手动对焦位置，并触发对焦。

    成功调用该方法后，本地会触发 CameraFocusAreaChanged 回调。

    Parameters

    • positionX: number

      触摸点相对于视图的横坐标。

    • positionY: number

      触摸点相对于视图的纵坐标。

    Returns Promise<void>

setCameraTorchOn

  • setCameraTorchOn(isOn: boolean): Promise<void>

  • 设置是否打开闪光灯。

    Parameters

    • isOn: boolean

      是否打开闪光灯：

      • true：打开。
      • false：关闭。

    Returns Promise<void>

setCameraZoomFactor

  • setCameraZoomFactor(factor: number): Promise<void>

  • 设置摄像头缩放比例。

    Parameters

    • factor: number

      相机缩放比例，有效范围从 1.0 到最大缩放。

    Returns Promise<void>

setChannelProfile

  • 设置频道场景。

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

    Parameters

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 2(InvalidArgument)：参数无效。
      • 7(NotInitialized): SDK 尚未初始化。

setClientRole

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

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

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

    Note

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

    Parameters

    Returns Promise<void>

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

setCloudProxy

  • 设置 Agora 云代理服务。

    当用户防火墙限制 IP 和端口号时，你需要参考《使用云代理》开放相应 IP 和端口号，然后调用该方法开启云代理， 并将 proxyType 参数设置为 UDP(1)，即 UDP 协议的云代理。

    成功连接云代理后，SDK 会触发 ConnectionStateChanged(Connecting, SettingProxyServer) 回调。

    如果你想关闭已设置的云代理，请调用 setCloudProxy(None)。如果你想更改已设置的云代理类型，请先调用 setCloudProxy(None)，再调用 setCloudProxy 并传入你期望的 proxyType 值。

    note
    • Agora 推荐你在频道外调用该方法。
    • 使用 UDP 协议的云代理时，推流到 CDN 和跨频道媒体流转发功能不可用。

    Parameters

    Returns Promise<void>

    • 0：方法调用成功。
    • 错误码：方法调用失败。
      • -2(ERR_INVALID_ARGUMENT): 传入的参数无效。
      • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

setDefaultAudioRoutetoSpeakerphone

  • setDefaultAudioRoutetoSpeakerphone(defaultToSpeaker: boolean): Promise<void>

  • 设置默认的音频播放路由。

    该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，则语音默认从听筒出声。 如果你想要在加入频道后修改语音路由，可以使用 setEnableSpeakerphone。

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

    • 通信场景：
    • 直播场景：扬声器。

    Note 该方法需要在加入频道前设置，否则不生效。

    Parameters

    • defaultToSpeaker: boolean
      • true：默认从外放（扬声器）出声。如果设备连接了耳机或蓝牙，则无法切换到外放。
      • false：（默认）默认从听筒出声。如果设备连接了耳机，则语音路由走耳机。

    Returns Promise<void>

setDefaultMuteAllRemoteAudioStreams

  • setDefaultMuteAllRemoteAudioStreams(muted: boolean): Promise<void>

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

    deprecated

    该方法自 v3.3.0 起废弃。

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

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

    note

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

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

    Parameters

    • muted: boolean

      是否默认取消订阅远端用户的音频流：

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

    Returns Promise<void>

setDefaultMuteAllRemoteVideoStreams

  • setDefaultMuteAllRemoteVideoStreams(muted: boolean): Promise<void>

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

    deprecated

    该方法自 v3.3.1 起废弃。

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

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

    note

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

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

    Parameters

    • muted: boolean

      是否默认取消订阅远端用户的视频流：

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

    Returns Promise<void>

setEffectPosition

  • setEffectPosition(soundId: number, pos: number): Promise<void>

  • 设置指定音效文件的播放位置。

    since

    v3.4.2

    成功设置后，本地音效文件会在指定位置开始播放。

    note

    该方法需要在 playEffect 后调用。

    Parameters

    • soundId: number

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

    • pos: number

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

    Returns Promise<void>

setEffectsVolume

  • setEffectsVolume(volume: number): Promise<void>

  • 设置所有音效文件的播放音量。

    Parameters

    • volume: number

      所有音效文件的播放音量，取值范围为 [0.0,100.0]。 100.0 为默认值。

    Returns Promise<void>

setEnableSpeakerphone

  • setEnableSpeakerphone(enabled: boolean): Promise<void>

  • 启用/关闭扬声器播放。

    该方法设置是否将语音路由设到扬声器（外放）。 调用该方法后，SDK 将返回 AudioRouteChanged 回调提示状态已更改。

    Note

    • 请确保在调用此方法前已调用过 joinChannel 方法。
    • 直播频道内的观众调用该 API 无效。
    • setAudioProfile 中 scenario 及 setChannelProfile 的设置会影响 setEnableSpeakerphone 的行为。setEnableSpeakerphone 不生效的情况如下：
      • 当 scenario 为 GameStreaming 时，所有用户都无法切换音频播放路由。
      • 当 scenario 为 Default 或 ShowRoom 时，直播场景中的观众无法切换音频播放路由，且当频道中只有一个主播时，该主播也无法切换音频播放路由。
      • 当 scenario 为 Education 时，直播场景中的观众无法切换音频播放路由。

    Parameters

    • enabled: boolean

      是否将音频路由到外放：

      • true: 切换到外放。如果设备连接了耳机或蓝牙，则无法切换到外放。
      • false: 切换到听筒。如果设备连接了耳机，则语音路由走耳机。

    Returns Promise<void>

setEncryptionMode

  • 设置内置的加密方案。

    deprecated

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

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

    Note

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

    Parameters

    Returns Promise<void>

setEncryptionSecret

  • setEncryptionSecret(secret: string): Promise<void>

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

    deprecated

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

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

    Note

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

    Parameters

    • secret: string

      加密密码。

    Returns Promise<void>

setInEarMonitoringVolume

  • setInEarMonitoringVolume(volume: number): Promise<void>

  • 设置耳返音量。

    Parameters

    • volume: number

      设置耳返音量，取值范围在 0 到 100 间。默认值为 100。

    Returns Promise<void>

setLiveTranscoding

  • 设置直播转码。

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

    Note

    • 请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
    • 该方法仅适用于直播场景下的主播用户。
    • 请确保先调用过该方法，再调用 addPublishStreamUrl。
    • Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

    Parameters

    Returns Promise<void>

setLocalPublishFallbackOption

  • 设置弱网条件下发布的音视频流回退选项。

    网络不理想的环境下，直播音视频的质量都会下降。使用该接口并将 option 设置为 AudioOnly(2) 后， SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，从而保证或提高音频质量。 同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当本地推流回退为音频流时，或由音频流恢复为音视频流时， SDK 会触发本地发布的媒体流已回退为音频流 LocalPublishFallbackToAudioOnly 回调。

    Note

    旁路推流场景下，设置本地推流回退为 AudioOnly(2) 可能会导致远端的 CDN 用户听到声音的时间有所延迟。 因此在有旁路推流的场景下，Agora 建议不开启该功能。

    Parameters

    Returns Promise<void>

setLocalVoiceChanger

  • 设置本地语音变声、美音或语聊美声效果。

    deprecated

    该方法从 v3.2.0 起废弃，请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。

    Note

    该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。

    Parameters

    • voiceChanger: AudioVoiceChanger

      本地语音的变声、美音或语聊美声效果选项。

    Returns Promise<void>

setLocalVoiceEqualization

  • 设置本地语音音效均衡。

    Parameters

    • bandFrequency: AudioEqualizationBandFrequency

      频谱子带索引，取值范围是 [0,9]，分别代表 10 个频带，对应的中心频率 是 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。

    • bandGain: number

      每个 band 的增益，单位是 dB，每一个值的范围是 [-15,15]，默认值为 0。

    Returns Promise<void>

setLocalVoicePitch

  • setLocalVoicePitch(pitch: number): Promise<void>

  • 设置本地语音音调。

    该方法改变本地说话人声音的音调。

    Parameters

    • pitch: number

      语音频率。可以在 [0.5,2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。

    Returns Promise<void>

setLocalVoiceReverb

  • setLocalVoiceReverb(reverbKey: AudioReverbType, value: number): Promise<void>

  • 设置本地音效混响。

    Note

    SDK 在 v3.2.1 版本中提供一个使用更为简便的方法 setAudioEffectPreset，直接实现流行、R&B、KTV 等预置的混响效果。

    Parameters

    • reverbKey: AudioReverbType

      混响音效 Key。

    • value: number

      各混响音效 Key 所对应的值。

    Returns Promise<void>

setLocalVoiceReverbPreset

  • 设置本地语音混响（含虚拟立体声效果）。

    deprecated

    该方法从 v3.2.0 起废弃，请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。

    通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后，频道内的所有用户均可听到声音效果。

    Note

    Parameters

    Returns Promise<void>

setLogFile

  • setLogFile(filePath: string): Promise<void>

  • 设置 Agora SDK 输出的日志文件。

    deprecated

    该方法从 v3.3.1 起废弃，请改用 createWithConfig 中的 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

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

    Parameters

    • filePath: string

      日志文件的完整路径。

      • Android 平台: 默认路径为 /storage/emulated/0/Android/data/<package name>/files/agorasdk.log。
      • iOS 平台：默认路径为 App Sandbox/Library/caches/agorasdk.log。

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

    Returns Promise<void>

setLogFileSize

  • setLogFileSize(fileSizeInKBytes: number): Promise<void>

  • 设置日志文件大小。

    deprecated

    该方法从 v3.3.1 起废弃，请改用 createWithConfig 中的 LogConfig 参数设置日志文件路径。

    设置 SDK 输出的单个日志文件大小，单位为 KB。

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

    Parameters

    • fileSizeInKBytes: number

      单个日志文件的大小，单位为 KB。默认值为 1024 KB。如果你将 fileSizeInKByte 设为 1024 KB，SDK 会最多输出 5 MB 的日志文件。如果你将 fileSizeInKByte 设为 小于 1024 KB，单个日志文件最大仍为 1024 KB。

    Returns Promise<void>

setLogFilter

  • setLogFilter(filter: LogFilter): Promise<void>

  • 设置日志输出等级。

    deprecated

    该方法从 v3.3.1 起废弃，请改用 createWithConfig 中的 LogConfig 参数设置日志文件路径。

    该方法设置 SDK 的日志输出等级。不同的等级可以单独或组合使用。

    日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。 例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

    Parameters

    Returns Promise<void>

setMaxMetadataSize

  • setMaxMetadataSize(size: number): Promise<void>

  • 设置 Metadata 的最大数据大小。

    Parameters

    • size: number

      Metadata 的最大数据大小，单位为 Byte，最大值不超过 1024。

    Returns Promise<void>

setRemoteDefaultVideoStreamType

  • setRemoteDefaultVideoStreamType(streamType: VideoStreamType): Promise<void>

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

    Parameters

    Returns Promise<void>

setRemoteSubscribeFallbackOption

  • 设置弱网条件下订阅的音视频流回退选项。

    网络不理想的环境下，直播音视频的质量都会下降。使用该接口并将 option 设置 为 VideoStreamLow(1) 或者 AudioOnly(2) 后， SDK 会在下行弱网且音视频质量严重受影响时， 将视频流切换为小流，或关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。 当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流 RemoteSubscribeFallbackToAudioOnly 回调。

    Parameters

    Returns Promise<void>

setRemoteUserPriority

  • setRemoteUserPriority(uid: number, userPriority: UserPriority): Promise<void>

  • 设置用户媒体流优先级。

    如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。 该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项，弱网下 SDK 会优先保证高优先级用户收到的流的质量。

    Note

    目前 Agora SDK 仅允许将一名远端用户设为高优先级。

    Parameters

    • uid: number

      远端用户的 ID。

    • userPriority: UserPriority

      远端用户的优先级。

    Returns Promise<void>

setRemoteVideoStreamType

  • setRemoteVideoStreamType(uid: number, streamType: VideoStreamType): Promise<void>

  • 设置订阅的视频流类型。

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

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

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

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

    note

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

    Parameters

    Returns Promise<void>

setRemoteVoicePosition

  • setRemoteVoicePosition(uid: number, pan: number, gain: number): Promise<void>

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

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

    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 Promise<void>

setVideoEncoderConfiguration

  • 设置视频编码属性。

    该方法设置视频编码属性。每个属性对应一套视频参数，如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。

    如果用户加入频道后不需要重新设置视频编码属性，则 Agora 建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

    Parameters

    Returns Promise<void>

setVoiceBeautifierParameters

  • setVoiceBeautifierParameters(preset: VoiceBeautifierPreset, param1: number, param2: number): Promise<void>

  • 设置 SDK 预设美声效果的参数。

    since

    3.3.1

    调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。 设置后，频道内所有用户都能听到该效果。

    为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)，并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

    note
    • 该方法在加入频道前后都能调用
    • 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
    • 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
    • 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
      • setAudioEffectPreset
      • setAudioEffectParameters
      • setVoiceBeautifierPreset
      • setLocalVoiceReverbPreset
      • setLocalVoiceChanger
      • setLocalVoicePitch
      • setLocalVoiceEqualization
      • setLocalVoiceReverb
      • setVoiceConversionPreset

    Parameters

    • preset: VoiceBeautifierPreset

      SDK 预设的音效：

      • SingingBeautifier：歌唱美声。
    • param1: number

      歌声的性别特征：

      • 1：男声。
      • 2：女声。
    • param2: number

      歌声的混响效果：

      • 1：歌声在小房间的混响效果。
      • 2：歌声在大房间的混响效果。
      • 3：歌声在大厅的混响效果。

    Returns Promise<void>

setVoiceBeautifierPreset

  • 设置 SDK 预设的美声效果。

    since

    v3.2.0。

    调用该方法可以为本地发流用户设置 SDK 预设的人声美化效果。设置美声效果后，频道内所有用户都能听到该效果。 根据不同的场景，你可以为用户设置不同的美声效果。

    为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)，并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

    Note

    • 该方法在加入频道前后都能调用。
    • 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法会调用失败。
    • 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
    • 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
      • setAudioEffectPreset
      • setAudioEffectParameters
      • setLocalVoiceReverbPreset
      • setLocalVoiceChanger
      • setLocalVoicePitch
      • setLocalVoiceEqualization
      • setLocalVoiceReverb
      • setVoiceConversionPreset

    Parameters

    Returns Promise<void>

setVoiceConversionPreset

  • 设置 SDK 预设的变声效果。

    since

    v3.3.1

    调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后，频道内所有用户都能听到该效果。 根据不同的场景，你可以为用户设置不同的变声效果，各变声效果的适用场景可参考《设置人声效果》。

    为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)，并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

    note
    • 该方法在加入频道前后都能调用。
    • 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
    • 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
    • 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
      • setAudioEffectPreset
      • setAudioEffectParameters
      • setVoiceBeautifierPreset
      • setVoiceBeautifierParameters
      • setLocalVoiceReverbPreset
      • setLocalVoiceChanger
      • setLocalVoicePitch
      • setLocalVoiceEqualization
      • setLocalVoiceReverb

    Parameters

    Returns Promise<void>

setVolumeOfEffect

  • setVolumeOfEffect(soundId: number, volume: number): Promise<void>

  • 设置指定音效文件的播放音量。

    Parameters

    • soundId: number

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

    • volume: number

      指定音效文件的播放音量，取值范围为 [0.0,100.0]。 100.0 为默认值。

    Returns Promise<void>

startAudioMixing

  • startAudioMixing(filePath: string, loopback: boolean, replace: boolean, cycle: number, startPos?: undefined | number): Promise<void>

  • 开始播放音乐文件及混音。

    该方法指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。 该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。 成功调用该方法后，本地会触发 AudioMixingStateChanged 回调且状态码为 Playing。 播放结束后，会收到 AudioMixingStateChanged 回调且状态码为 Stopped。

    Note

    • 如需在 Android 平台调用该方法，请确保使用 Android 4.2 或以上设备，且 API Level ≥ 16。
    • 如果播放的是在线音乐文件，请确保重复调用该 API 的间隔超过 100 ms，否则 SDK 会返回 TooFrequentCall(702) 警告码， 表示音乐文件打开过于频繁。
    • 如果播放的是在线音乐文件，Agora 建议不要使用重定向地址。重定向地址在某些机型上可能会出现无法打开的情况。
    • 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 CanNotOpen(701)。
    • 如果在模拟器上使用该 API，暂时只支持存放在 /sdcard/ 中的 mp3 文件。

    Parameters

    • filePath: string

      文件路径，需精确到文件名及后缀。

      • Android：支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note: 通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：支持文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Best Practices for iOS Audio。
    • loopback: boolean
      • true：只有本地可以听到混音或替换后的音频流。
      • false：本地和对方都可以听到混音或替换后的音频流。
    • replace: boolean
      • true：只推动设置的本地音频文件或者线上音频文件，不传输麦克风收录的音频。
      • false：音频文件内容将会和麦克风采集的音频流进行混音。
    • cycle: number

      音频文件循环播放的次数：

      • 正整数：循环的次数。
      • -1：无限循环。
    • Optional startPos: undefined | number

      @since 3.4.2 音乐文件的播放位置，单位为毫秒。

    Returns Promise<void>

startAudioRecording

  • 开始客户端录音。

    deprecated

    从 v3.4.2 起废弃。请改用 startAudioRecordingWithConfig。

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

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

    Note

    • 请确保你在该方法中指定的路径存在并且可写。
    • 该接口需要在 joinChannel 之后调用。 如果调用 leaveChannel 时还在录音，录音会自动停止。
    • 为保证录音效果，当 sampleRate 设为 44.1 kHz 或 48 kHz 时，建议将 quality 设 为 Medium 或 High。

    Parameters

    • filePath: string

      录音文件在本地保存的绝对路径，由用户自行制定，需精确到文件名及格式，例如：/dir1/dir2/dir3/audio.aac。

    • sampleRate: AudioSampleRateType

      录音采样率 (Hz)。

    • quality: AudioRecordingQuality

      录音音质。

    Returns Promise<void>

startAudioRecordingWithConfig

  • 开始客户端录音。

    since

    v3.4.2

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

    • WAV: 音质保真度较高，文件较大。例如，采样率为 32000 Hz，录音时长为 10 分钟的文件大小约为 73 M。
    • AAC: 音质保真度较低，文件较小。例如，采样率为 32000 Hz，录音音质为 Medium，录音时长为 10 分钟的文件大小约为 2 M。

    一旦用户离开频道，录音会自动停止。

    note

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

    Parameters

    Returns Promise<void>

startChannelMediaRelay

startEchoTest

  • startEchoTest(intervalInSeconds: number): Promise<void>

  • 开始语音通话回路测试。

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

    Note

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

    Parameters

    • intervalInSeconds: number

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

    Returns Promise<void>

startLastmileProbeTest

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

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

    • LastmileQuality：视网络情况约 2 秒内返回。 该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
    • LastmileProbeResult：视网络情况约 30 秒内返回。 该回调通过客观数据反馈上下行网络质量，因此更客观。

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

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

    Note

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

    Parameters

    Returns Promise<void>

startPreview

  • startPreview(): Promise<void>

  • 开启视频预览。

    该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须调用 enableVideo 开启视频功能。

    Note

    • 本地预览默认开启镜像功能。
    • 使用该方法启用了本地视频预览后，如果直接调用 leaveChannel 退出频道， 并不会关闭预览。如需关闭预览，请调用 stopPreview。

    Returns Promise<void>

startRhythmPlayer

  • startRhythmPlayer(sound1: string, sound2: string, config: RhythmPlayerConfig): Promise<void>

  • 开启虚拟节拍器。

    since

    v3.4.2

    在音乐教学、体育教学等场景中，老师通常需要使用节拍器，让学生跟着正确的节拍练习。 节拍由强拍和弱拍组成，每小节的第一拍称为强拍，其余称为弱拍。 你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。

    note

    开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。

    Parameters

    • sound1: string

      强拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。

      • Android：例如：/sdcard/emulated/0/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：例如：/var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Best Practices for iOS Audio。
    • sound2: string

      弱拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。

      • Android：例如：/sdcard/emulated/0/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
      • iOS：例如：/var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Best Practices for iOS Audio。
    • config: RhythmPlayerConfig

      节拍器配置，详见 RhythmPlayerConfig。

    Returns Promise<void>

stopAllEffects

  • stopAllEffects(): Promise<void>

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

    Returns Promise<void>

stopAudioMixing

  • stopAudioMixing(): Promise<void>

  • 停止播放音乐文件及混音。

    该方法停止播放伴奏。请在频道内调用该方法。

    Returns Promise<void>

stopAudioRecording

  • stopAudioRecording(): Promise<void>

  • 停止客户端录音。

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

    Returns Promise<void>

stopChannelMediaRelay

  • stopChannelMediaRelay(): Promise<void>

stopEchoTest

  • stopEchoTest(): Promise<void>

  • 停止语音通话回路测试。

    Returns Promise<void>

stopEffect

  • stopEffect(soundId: number): Promise<void>

  • 停止播放指定音效文件。

    Note

    如果你已通过 preloadEffect 将音效加载至内存，确保这里的 soundID 与 preloadEffect 设置的 soundID 相同。

    Parameters

    • soundId: number

      音效文件的 ID。每个音效均有唯一的 ID。

    Returns Promise<void>

stopLastmileProbeTest

  • stopLastmileProbeTest(): Promise<void>

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

    Returns Promise<void>

stopPreview

  • stopPreview(): Promise<void>

  • 停止视频预览。

    note

    请在 startPreview 后调用该方法。

    Returns Promise<void>

stopRhythmPlayer

  • stopRhythmPlayer(): Promise<void>

  • 关闭虚拟节拍器。

    since

    v3.4.2

    调用 startRhythmPlayer 后，你可以调用该方法关闭虚拟节拍器。

    Returns Promise<void>

switchCamera

  • switchCamera(): Promise<void>

  • 切换前置/后置摄像头。

    Returns Promise<void>

switchChannel

  • switchChannel(token: string | undefined | null, channelName: string, options?: ChannelMediaOptions): Promise<void>

  • 快速切换直播频道。

    当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

    成功调用该方切换频道后，本地会先收到离开原频道的回调 LeaveChannel， 再收到成功加入新频道的回调 JoinChannelSuccess。

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

    Note

    该方法仅适用直播频道中的观众用户。

    Parameters

    • token: string | undefined | null

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

    • channelName: string

      标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）：

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

      @since v3.3.1 频道媒体设置选项。详见 ChannelMediaOptions。

    Returns Promise<void>

    • 0(NoError): 方法调用成功。
    • 错误码: 方法调用失败。
      • 1(Failed): 一般性的错误（未明确归类）。
      • 2(InvalidArgument): 参数无效。
      • 5(Refused): 调用被拒绝。可能因为用户角色不是观众。
      • 7(NotInitialized): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 RtcEngine 对象并完成初始化。
      • 102(InvalidChannelId): 频道名无效。请更换有效的频道名。
      • 113(NotInChannel): 用户不在频道内。

unloadEffect

  • unloadEffect(soundId: number): Promise<void>

  • 从内存释放指定的预加载音效文件。

    Parameters

    • soundId: number

      音效文件的 ID。

    Returns Promise<void>

unregisterMediaMetadataObserver

  • unregisterMediaMetadataObserver(): Promise<void>

  • 注销媒体 Metadata 观测器。

    Returns Promise<void>

updateChannelMediaRelay

  • 更新媒体流转发的频道。

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

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

    Note

    • 请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。
    • 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了，你可以在调用该方法之前， 调用 ChannelMediaRelayConfiguration 类中的 destInfos 方法移除不需要的频道。

    Parameters

    Returns Promise<void>

Static create

  • 创建 RtcEngine 实例。

    RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

    Note

    Parameters

    • appId: string

      Agora 为 app 开发者签发的 App ID，详见获取 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。 如需更换 App ID，必须先调用 destroy 销毁当前 RtcEngine，再调用 create 重新创建 RtcEngine。

    Returns Promise<RtcEngine>

    • 方法调用成功，则返回一个 RtcEngine 对象。
    • 方法调用失败，则返回错误码。
      • 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

Static createWithAreaCode

  • 创建 RtcEngine 实例。

    deprecated

    该方法从 v3.3.1 起废弃，请改用 createWithConfig。

    RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

    Note

    • 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
    • 目前 Agora React Native SDK 只支持每个 app 创建一个 RtcEngine 实例。

    Parameters

    • appId: string

      Agora 为 app 开发者签发的 App ID，详见获取 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。 如需更换 App ID，必须先调用 destroy 销毁当前 RtcEngine，再调用 create 重新创建 RtcEngine。

    • areaCode: AreaCode

      服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。 支持的区域详见 AreaCode。 指定访问区域后，集成了 Agora SDK 的 app 会连接指定区域内的 Agora 服务器。

    Returns Promise<RtcEngine>

    • 方法调用成功，则返回一个 RtcEngine 对象。
    • 方法调用失败，则返回错误码。
      • 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

Static createWithConfig

  • 创建 RtcEngine 实例。

    since

    v3.3.1

    RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

    Note

    • 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
    • 目前 Agora React Native SDK 只支持每个 app 创建一个 RtcEngine 实例。

    Parameters

    Returns Promise<RtcEngine>

    • 方法调用成功，则返回一个 RtcEngine 对象。
    • 方法调用失败，则返回错误码。
      • 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

Static getErrorDescription

  • getErrorDescription(error: number): Promise<string>

  • 获取错误码或警告码描述。

    since

    v3.3.1

    Parameters

    Returns Promise<string>

    错误码或警告码的详细描述。

Static getSdkVersion

  • getSdkVersion(): Promise<string>

  • 查询 SDK 版本号。

    since

    v3.3.1

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

    Returns Promise<string>

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

Static instance

  • 获取已经创建的 RtcEngine 实例。

    Note

    请确保你已经创建 RtcEngine 实例。否则，方法调用会失败并返回错误信息。

    Returns RtcEngine

    • 方法调用成功，则返回一个 RtcEngine 实例。
    • 方法调用失败，则返回错误信息。