Cocos Creator SDK API Reference

addPublishStreamUrl

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

• 增加旁路推流地址。

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

  Note

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

  Parameters

  • url: string

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

  • transcodingEnabled: boolean

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

  Returns number

  • 0: 方法调用成功
  • < 0: 方法调用失败
    • ERR_INVALID_ARGUMENT (2): URL 为空或是长度为 0 的的字符串
    • ERR_NOT_INITIALIZED (7): 推流时未初始化引擎

addVideoWatermark

• addVideoWatermark(watermarkUrl: string, options: WatermarkOptions): number

• 添加本地视频水印。

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

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

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

  Note

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

  Parameters

  • watermarkUrl: string

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

  • options: WatermarkOptions

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

  Returns number

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

adjustAudioMixingPlayoutVolume

• adjustAudioMixingPlayoutVolume(volume: number): number

• 调节音乐文件本端播放音量。 该方法调节混音音乐文件在本端的播放音量大小。请在频道内调用该方法。

  Parameters

  • volume: number

    音乐文件音量范围为 0~100。100 （默认值） 为原始文件音量。

  Returns number

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

adjustAudioMixingPublishVolume

• adjustAudioMixingPublishVolume(volume: number): number

• 调节音乐文件远端播放音量。 该方法调节混音音乐文件在远端的播放音量大小。请在频道内调用该方法。

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

adjustPlaybackSignalVolume

• adjustPlaybackSignalVolume(volume: number): number

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

  Note

  • 该方法调节的是本地播放的所有远端用户混音后的音量。
  • 从 v3.1.2 开始，静音本地音频需同时调用 adjustPlaybackSignalVolume 和 adjustAudioMixingPlayoutVolume 方法，并将 volume 设置为 0。

  Parameters

  • volume: number

    播放音量。为避免回声并提升通话质量，声网建议将 volume 值设为 [0,100]。如果 volume 值需超过 100，联系技术支持:

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

  Returns number

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

adjustRecordingSignalVolume

• adjustRecordingSignalVolume(volume: number): number

• 调节录音音量。

  Parameters

  • volume: number

    录音信号音量。为避免回声并提升通话质量，声网建议将 volume 值设为 [0,100]。如果 volume 值需超过 100，联系技术支持:

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

  Returns number

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

adjustUserPlaybackSignalVolume

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

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

  Note

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

  Parameters

  • uid: number

    远端用户 ID。

  • volume: number

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

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

  Returns number

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

clearVideoWatermarks

• clearVideoWatermarks(): number

• 删除已添加的视频水印。

  Returns number

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

complain

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

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

  Parameters

  • callId: string

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

  • description: string

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

  Returns number

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

createDataStream

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

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

  note

  将 reliable 和 ordered 同时设为 true 或 false。不要一个设为 true 另一个设为 false。

  Parameters

  • streamId: number

    数据流 ID。

  • reliable: boolean

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

  • ordered: boolean

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

  Returns number

  • 0: 创建数据流成功。
  • < 0: 创建数据流失败。

disableAudio

• disableAudio(): number

• 关闭音频模块。

  Note

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

  Returns number

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

disableLastmileTest

• disableLastmileTest(): number

• 关闭网络测试。

  Returns number

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

disableVideo

• disableVideo(): number

• 关闭视频模块。 该方法可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频频模式。 调用 enableVideo 方法可开启视频模式。 成功调用该方法后，远端会触发 onUserEnableVideo(false) 回调

  Note

  • 该方法设置内部引擎为禁用状态，在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制视频模块：
    • enableLocalVideo : 是否启动摄像头采集并创建本地视频流。
    • muteLocalVideoStream : 是否发布本地视频流。
    • muteRemoteVideoStream : 是否接收并播放远端视频流。
    • muteAllRemoteVideoStreams : 是否接收并播放所有远端视频流。

  Returns number

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

enableAudio

• enableAudio(): number

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

  Note

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

  Returns number

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

enableAudioVolumeIndication

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

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

  Parameters

  • interval: number

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

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

  • smooth: number

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

  • report_vad: boolean

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

  Returns number

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

enableDualStreamMode

• enableDualStreamMode(enabled: boolean): number

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

  Parameters

  • enabled: boolean

    • true: 双流。
    • false: 单流。

  Returns number

enableEncryption

• enableEncryption(enabled: boolean, config: EncryptionConfig): number

• 开启或关闭内置加密。

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

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

  Note

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

  Parameters

  • enabled: boolean

    是否开启内置加密：

    • true: 开启
    • false: 关闭

  • config: EncryptionConfig

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

  Returns number

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

enableFaceDetection

• enableFaceDetection(enabled: boolean): number

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

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

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

  Parameters

  • enabled: boolean

  Returns number

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

enableInEarMonitoring

• enableInEarMonitoring(enabled: boolean): number

• 开启耳返功能。

  note

  用户必须使用有线耳机才能听到耳返效果。

  Parameters

  • enabled: boolean

    开启/关闭耳返功能：

    • true：开启耳返功能
    • false：关闭耳返功能(默认)

  Returns number

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

enableLastmileTest

• enableLastmileTest(): number

• 启动网络测试。 该方法启用网络连接质量测试，用于检测用户目前的网络接入质量（上行网络质量）。默认该功能为关闭状态。该方法主要用于以下场景:

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

  启用该方法均会消耗网络流量，影响通话质量。用户必须在收到 onLastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换为主播。

  Note

  • 该方法请勿与 startLastmileProbeTest 同时使用。
  • 调用该方法后，在收到 onLastmileQuality 回调前请勿调用其他方法， 否则可能由于 API 操作过于频繁导致回调无法执行。
  • 在直播场景中，如果本地用户为主播，请勿加入频道后调用该方法。

  Returns number

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

enableLocalAudio

• enableLocalAudio(enabled: boolean): number

• 开关本地音频采集。 当用户加入频道时，语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能，即停止或重新开始本地音频采集。 该方法不影响接收或播放远端音频流， enableLocalAudio (false) 适用于只听不发的用户场景。 语音功能关闭或重新开启后，会收到回调 onLocalAudioStateChanged ， 并报告 LOCAL_AUDIO_STREAM_STATE_STOPPED(0) 或 LOCAL_AUDIO_STREAM_STATE_RECORDING(1)。

  Note

  该方法与 muteLocalAudioStream 的区别在于：

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

  Parameters

  • enabled: boolean

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

  Returns number

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

enableLocalVideo

• enableLocalVideo(enabled: boolean): number

• 开关本地视频采集。 该方法禁用或重新启用本地视频采集，不影响接收远端视频。 调用 enableVideo 后，本地视频即默认开启。你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想要重新开启，则可调用 enableLocalVideo(true) 。 成功禁用或启用本地视频采集后，远端会触发 onUserEnableLocalVideo 回调。

  note

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

  Parameters

  • enabled: boolean

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

  Returns number

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

enableSoundPositionIndication

• enableSoundPositionIndication(enabled: boolean): number

• 开启/关闭远端用户的语音立体声。 如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在加入频道前调用该方法开启 远端用户的语音立体声。

  Parameters

  • enabled: boolean

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

    • true: 开启
    • false: 关闭

  Returns number

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

enableVideo

• enableVideo(): number

• 启用视频模块。 该方法可以在加入频道前或者通话中调用，在加入频道前调用则自动开启视频模块；在通话中调用则由音频模式切换为视频模式。 调用 disableVideo 方法可关闭视频模式。 成功调用该方法后，远端会触发 onUserEnableVideo (true) 回调。

  Note

  • 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制视频模块：
    • enableLocalVideo : 是否启动摄像头采集并创建本地视频流。
    • muteLocalVideoStream : 是否发布本地视频流。
    • muteRemoteVideoStream : 是否接收并播放远端视频流。
    • muteAllRemoteVideoStreams : 是否接收并播放所有远端视频流。

  Returns number

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

enableWebSdkInteroperability

• enableWebSdkInteroperability(enabled: boolean): number

• deprecated

  该方法已废弃。自 Native SDK v3.1.2 及之后，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。 打开直播场景下与声网 Web SDK 的互通。

  Note

  • 该方法仅适用于直播场景。通信场景默认打开与 Web SDK 的互通。
  • 如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。

  Parameters

  • enabled: boolean

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

  Returns number

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

getAudioMixingCurrentPosition

• getAudioMixingCurrentPosition(): number

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

  Returns number

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

getAudioMixingDuration

• getAudioMixingDuration(): number

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

  Returns number

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

getAudioMixingPlayoutVolume

• getAudioMixingPlayoutVolume(): number

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

  note

  请在频道内调用该方法。

  Returns number

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

getAudioMixingPublishVolume

• getAudioMixingPublishVolume(): number

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

  note

  请在频道中调用该方法

  Returns number

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

getCallId

• getCallId(): string

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

  Returns string

  当前的通话 ID。

getConnectionState

• getConnectionState(): CONNECTION_STATE_TYPE

• 获取当前网络连接状态。

  Returns CONNECTION_STATE_TYPE

  agora.CONNECTION_STATE_TYPE。

getEffectsVolume

• getEffectsVolume(): number

• 获取音效文件的播放音量。 音量范围为 0~100。100 （默认值）为原始文件音量。

  Returns number

  • ≥ 0:音效文件的音量。
  • < 0: 方法调用失败

getErrorDescription

• getErrorDescription(code: number): string

• 获取警告或错误描述。

  Parameters

  • code: number

    AgoraRtcEvents.onWarning 或 onError 提供的警告码或错误码。

  Returns string

  agora.WARN_CODE_TYPE 或 ERROR_CODE_TYPE。

getUserInfoByUid

• getUserInfoByUid(uid: number): UserInfo

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

  Parameters

  • uid: number

    用户 UID。该参数为必填

  Returns UserInfo

  标识用户信息的 UserInfo。

getUserInfoByUserAccount

• getUserInfoByUserAccount(userAccount: string): UserInfo

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

  Parameters

  • userAccount: string

    用户 User Account。该参数为必填

  Returns UserInfo

  一个包含了用户 User Account 和 UID 的 UserInfo

getVersion

• getVersion(): string

• 获取 SDK 的版本信息

  Returns string

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

init

• init(appId: string): number

• 初始化声网引擎。

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

  Note

  • 请确保在调用其他 API 前先调用该方法初始化声网引擎。
  • 调用该方法和 initWithAreaCode 均能初始化声网引擎。该方法与 initWithAreaCode 的区别在于， initWithAreaCode 支持在初始化声网引擎时指定访问区域。

  Parameters

  • appId: string

    声网为 app 开发者签发的 App ID，详见获取 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。如需更换 App ID，必须先 调用 release 销毁当前声网引擎，并在 release 成功返回后，再调用 init 重新初始化声网引擎。

  Returns number

  • 方法调用成功，返回一个声网引擎。
  • 方法调用失败，返回错误码。
    • ERR_INVALID_APP_ID(-101): App ID 无效。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

initWithAreaCode

• initWithAreaCode(appId: string, areaCode: AREA_CODE): number

• 初始化声网引擎。

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

  Note

  • 请确保在调用其他 API 前先调用该方法初始化声网引擎。
  • 调用该方法和 initWithAreaCode 均能初始化声网引擎。该方法与 initWithAreaCode 的区别在于， 该方法支持在初始化声网引擎时指定访问区域。

  note

  仅支持指定单个访问区域。

  Parameters

  • appId: string

    声网为 app 开发者签发的 App ID，详见获取 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。如需更换 App ID，必须先 调用 release 销毁当前声网引擎，并在 release 成功返回后，再调用 init 重新初始化声网引擎。

  • areaCode: AREA_CODE

    服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。

    支持的区域详见 AREA_CODE。 指定访问区域后，SDK 会连接指定区域内的声网服务器。

  Returns number

  • 方法调用成功，返回一个声网引擎。
  • 方法调用失败，返回错误码。
    • ERR_INVALID_APP_ID(-101): App ID 无效。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

isSpeakerphoneEnabled

• isSpeakerphoneEnabled(): boolean

• 查询扬声器启用状态

  Returns boolean

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

joinChannel

• joinChannel(token: string, channelId: string, info?: string, uid?: number): number

• 加入频道。

  该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中， 用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。 成功调用该方加入频道后，本地会触发 onJoinChannelSuccess 回调；通信场景下的用户和直播场景下 的主播加入频道后，远端会触发 onUserJoined 回调。 在网络状况不理想的情况下，客户端可能会与声网的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。

  note

  频道内每个用户的用户 ID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 uid。如果想要从不同的设备同时接入同一个频道，请确保 每个设备上使用的 uid 是不同的。

  warning

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

  Parameters

  • token: string

    动态秘钥。

    • 安全要求不高: 你可以使用控制台生成的临时 Token，详见 获取临时 Token。
    • 安全要求高：将值设为你的服务端生成的正式 Token，详见 获取正式 Token。

  • channelId: string

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

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

  • Default value info: string = ""

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

  • Default value uid: number = 0

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

  Returns number

  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。

joinChannelWithUserAccount

• joinChannelWithUserAccount(token: string, channelId: string, userAccount: string): number

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

  • 本地： onLocalUserRegistered 和 onJoinChannelSuccess 回调
  • 远端：通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 onUserJoined 和 onUserInfoUpdated 回调

  note

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

  Parameters

  • token: string

    在 App 服务器端生成的用于鉴权的 Token：

    • 安全要求不高：你可以使用控制台生成的临时 Token，详见 获取临时 Token。
    • 安全要求高：将值设为你的服务端生成的正式 Token，详见 获取正式 Token。

  • channelId: 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
    • 空格
    • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

  Returns number

  • 0: 方法调用成功
  • < 0: 方法调用失败
    • ERR_INVALID_ARGUMENT (-2)
    • ERR_NOT_READY (-3)
    • ERR_REFUSED (-5)

leaveChannel

• leaveChannel(): number

• 离开频道。 离开频道，即挂断或退出通话。 当调用 joinChannel 方法后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。 不管当前是否在通话中， 都可以调用 leaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。 该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。 成功调用该方法离开频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道 后，远端会触发 onUserOffline 回调。

  Note

  • 如果你调用了 leaveChannel 后立即调用 release ，SDK 将无法触发 onLeaveChannel 回调。
  • 如果你在旁路推流时调用 leaveChannel 方法， SDK 将自动调用 removePublishStreamUrl 方法。

  Returns number

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

muteAllRemoteAudioStreams

• muteAllRemoteAudioStreams(mute: boolean): number

• 接收／停止接收所有音频流。

  Parameters

  • mute: boolean

    • true: 停止接收所有音频流；
    • false: 继续接收所有音频流（默认）。

  Returns number

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

muteAllRemoteVideoStreams

• muteAllRemoteVideoStreams(mute: boolean): number

• 接收／停止接收所有远端视频流。

  Parameters

  • mute: boolean

    • true: 停止接收所有远端视频流；
    • false: 允许接收所有远端视频流（默认）。

  Returns number

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

muteLocalAudioStream

• muteLocalAudioStream(mute: boolean): number

• 开关本地音频发送。 该方法用于允许/禁止往网络发送本地音频流。 成功调用该方法后，远端会触发 onUserMuteAudio 回调。

  Note

  • 该方法不影响录音状态，因为并没有禁用录音设备。
  • 如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色， 重新设置是否停止发送本地音频。因此我们建议在 setChannelProfile 后调用该方法。

  Parameters

  • mute: boolean

    • true: 停止发送本地音频流；
    • false: 继续发送本地音频流（默认）。

  Returns number

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

muteLocalVideoStream

• muteLocalVideoStream(mute: boolean): number

• 开关本地视频发送。 成功调用该方法后，远端会触发 onUserMuteVideo 回调。

  Note

  • 调用该方法时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。相比于 enableLocalVideo (false) 用于控制本地视频流发送的方法，该方法响应速度更快。该方法不影响本地视频流获取，没有禁用摄像头。
  • 如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色， 重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。

  Parameters

  • mute: boolean

    • true: 不发送本地视频流
    • false: 发送本地视频流（默认）。

  Returns number

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

muteRemoteAudioStream

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

• 接收／停止接收指定音频流。

  note

  如果之前有调用过 muteAllRemoteAudioStreams (true) 停止订阅所有远端音频， 在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false)。 muteAllRemoteAudioStreams 是全局控制，muteRemoteAudioStream 是精细控制。

  Parameters

  • userId: number

    指定用户的 ID

  • mute: boolean

    • true: 停止接收指定音频流；
    • false: 继续接收指定音频流（默认）。

  Returns number

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

muteRemoteVideoStream

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

• 接收／停止接收指定远端用户的视频流。

  note

  如果之前调用过 muteAllRemoteVideoStreams (true) 停止接收放所有远端视频流，在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (false) 。 muteAllRemoteVideoStreams 是全局控制， muteRemoteVideoStream 是精细控制。

  Parameters

  • userId: number

    指定用户的用户 ID。

  • mute: boolean

    • true: 停止接收指定远端用户的视频流；
    • false: 允许接收指定远端用户的视频流（默认）。

  Returns number

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

off

• off(type: string, callback?: Function, target?: any): void

• 停止在声网引擎运行期间监听事件。

  Parameters

  • type: string

  • Optional callback: Function

  • Optional target: any

  Returns void

pauseAllEffects

• pauseAllEffects(): number

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

  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): number

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

  note

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

  Parameters

  • soundId: number

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

  • filePath: string

    音效文件的绝对路径或 URL 地址，例如：c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名，可不填。 支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 及 wav。 详见 Supported Media Formats in Media Foundation 。

  • loopCount: number

    设置音效循环播放的次数：

    • 0: 播放音效一次；
    • 1: 播放音效两次；
    • -1: 无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。

  • pitch: number

    设置音效的音调 取值范围为 [0.5, 2]。默认值为 1.0，表示不需要修改音调。取值越小，则音调越低。

  • pan: number

    设置是否改变音效的空间位置。取值范围为 [-1.0, 1.0]:

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

  • gain: number

    设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小，则音效的音量越低。

  • publish: Boolean

    设置是否将音效传到远端：

    • true: 音效在本地播放的同时，会发布到声网云端，因此远端用户也能听到该音效；
    • false: 音效不会发布到声网云端，因此只能在本地听到该音效。

  Returns number

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

preloadEffect

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

• 将音效文件加载至内存。 该方法将指定音效文件预加载至内存。

  note

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

  Parameters

  • soundId: number

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

  • filePath: string

    音效文件的绝对路径。

  Returns number

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

rate

• rate(callId: string, rating: number, description?: string): number

• 给通话评分。 该方法能够让用户为通话评分，一般在通话结束后调用。

  Parameters

  • callId: string

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

  • rating: number

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

  • Optional description: 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 方法注册 Account，再调用 joinChannelWithUserAccount 方法加入频道
  • 直接调用 joinChannelWithUserAccount 方法加入频道

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

  Note

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

  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(type: METADATA_TYPE): number

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

  Note

  • 请在 joinChannel 前调用该方法
  • 该方法仅使用于直播场景

  Parameters

  • type: METADATA_TYPE

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

  Returns number

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

registerPacketObserver

• registerPacketObserver(observer: any): number

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

  Note

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

  Parameters

  • observer: any

    IPacketObserver 。

  Returns number

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

release

• release(): void

• 销毁声网引擎。

  该方法释放声网 SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信，不需要时则将资源释放出来用于其他操作，该方法适用于此类情况。 调用 release 方法后，你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能，你必须重新调用 create 方法重新初始化声网引擎。

  Note

  • 该方法为同步调用，需要等待声网引擎资源释放后才能执行其他操作，所以我们建议在子线程中调用该方法，避免主线程阻塞。此外，我们不建议在 SDK 的回调中调用 release，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。
  • 如需在销毁后重新初始化声网引擎，需要等待 release 方法执行结束后再重新初始化。

  Returns void

removePublishStreamUrl

• removePublishStreamUrl(url: string): number

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

  Note

  • 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。
  • URL 不支持中文等特殊字符。
  • 在直播场景中，只有角色为主播的用户才能调用该方法。

  Parameters

  • url: string

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

  Returns number

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

renewToken

• renewToken(token: string): number

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

  • 发生 onTokenPrivilegeWillExpire 回调时，或发生
  • onConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。 App 应重新获取 Token，然后调用该方法更新 Token，否则 SDK 无法和服务器建立连接。

  Parameters

  • token: string

    新的 Token。

  Returns number

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

resumeAllEffects

• resumeAllEffects(): number

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

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

sendCustomReportMessage

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

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

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

  Parameters

  • id: string

  • category: string

  • event: string

  • label: string

  • value: number

  Returns number

sendMetadata

• sendMetadata(__namedParameters: { buffer: Uint8Array; size: number; timeStampMs: number; uid: number }): number

• 发送 Metadata。

  Note

  • 该方法需要在 registerMediaMetadataObserver 之后调用。
  • 请确保在该方法中传入的 Metadata 大小不超过 setMaxMetadataSize 中设定的值。

  Parameters

  • __namedParameters: { buffer: Uint8Array; size: number; timeStampMs: number; uid: number }

    • buffer: Uint8Array

      发送的 Metadata 数据。

    • size: number

      发送的 Metadata 的数据大小。

    • timeStampMs: number

      该 Metadata 的时间戳（毫秒）。

    • uid: number

  Returns number

  • true: 发送
  • false: 不发送

sendStreamMessage

• sendStreamMessage(streamId: number, data: Uint8Array, length: number): number

• 发送数据流。

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

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

  Note

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

  Parameters

  • streamId: number

    由 createDataStream 返回的数据流 ID。

  • data: Uint8Array

    自定义数据。

  • length: number

    数据长度。

  Returns number

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

setAudioMixingPitch

• setAudioMixingPitch(pitch: number): number

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

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

  note

  该方法需在 startAudioMixing 后调用。

  Parameters

  • pitch: number

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

  Returns number

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

setAudioMixingPosition

• setAudioMixingPosition(pos: number): number

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

  Parameters

  • pos: number

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

  Returns number

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

setAudioProfile

• setAudioProfile(profile: AUDIO_PROFILE_TYPE, scenario: AUDIO_SCENARIO_TYPE): number

• 设置音频编码属性。

  Note

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

  Parameters

  • profile: AUDIO_PROFILE_TYPE

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

  • scenario: AUDIO_SCENARIO_TYPE

    设置音频应用场景: #AUDIO_SCENARIO_TYPE 。不同的音频场景下，设备的系统音量是不同的。详见 如何区分媒体音量和通话音量。

  Returns number

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

setBeautyEffectOptions

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

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

  Note

  • 请在调用 enableVideo 方法后，调用该方法。
  • 该方法目前不适用于 macOS 平台。

  Parameters

  • enabled: boolean

    是否开启美颜功能：

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

  • options: BeautyOptions

    美颜选项。详见: BeautyOptions 。

  Returns number

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

setCameraCapturerConfiguration

• setCameraCapturerConfiguration(config: CameraCapturerConfiguration): number

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

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

  note

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

  Parameters

  • config: CameraCapturerConfiguration

    摄像头采集偏好，详见 CameraCapturerConfiguration。

  Returns number

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

setChannelProfile

• setChannelProfile(profile: CHANNEL_PROFILE_TYPE): number

• 设置频道场景。

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

  warning

  • 为保证实时音视频质量，我们建议相同频道内的用户使用同一种频道场景。
  • 该方法必须在 joinChannel 前调用和进行设置，进入频道后无法再设置。
  • 不同的频道场景下，SDK 的默认音频路由是不同的，详见 setDefaultAudioRouteToSpeakerphone 方法中的说明。

  Parameters

  • profile: CHANNEL_PROFILE_TYPE

    频道使用场景: CHANNEL_PROFILE_TYPE。

  Returns number

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

setClientRole

• setClientRole(role: CLIENT_ROLE_TYPE): number

• 设置用户角色。

  在加入频道前，用户需要通过本方法设置观众（默认）或主播。在加入频道后，用户可以通过本方法切换用户角色。

  直播场景下，如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 onClientRoleChanged 回调； 远端会触发 onUserJoined 回调或 onUserOffline(BECOME_AUDIENCE) 回调。

  note

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

  Parameters

  • role: CLIENT_ROLE_TYPE

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

  Returns number

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

setDefaultAudioRouteToSpeakerphone

• setDefaultAudioRouteToSpeakerphone(defaultToSpeaker: boolean): number

• 设置默认的语音路由 该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，语音默认从听筒出声。 各频道场景下默认的语音路由：

  • 语音通话：听筒
  • 直播：扬声器
  • 游戏语音：扬声器

  Note

  • 在 iOS 平台上，该方法只在纯音频模式下工作，在有视频的模式下不工作。
  • 该方法需要在 joinChannel 前设置，否则不生效。如需在加入频道后更改默认语音路由，请调用 setEnableSpeakerphone 方法。

  Parameters

  • defaultToSpeaker: boolean

    设置默认的语音路由

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

  Returns number

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

setDefaultMuteAllRemoteAudioStreams

• setDefaultMuteAllRemoteAudioStreams(mute: boolean): number

• 设置是否默认接收所有音频流。 该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams(true)， 会接收不到后面加入频道的用户的音频流。

  note

  停止接收音频流后，如果想要恢复接收，请调用 muteRemoteAudioStream(false)，并指定你想要接收的远端用户的 ID。 如果想恢复接收多个用户的音频流，则需要多次调用 muteRemoteAudioStream。 setDefaultMuteAllRemoteAudioStreams(false) 只能恢复接收后面加入频道的用户的音频流。

  Parameters

  • mute: boolean

    • true: 默认停止接收所有音频流；
    • false: 默认接收所有音频流（默认）。

  Returns number

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

setDefaultMuteAllRemoteVideoStreams

• setDefaultMuteAllRemoteVideoStreams(mute: boolean): number

• 设置是否默认停止接收视频流。 该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams (true)，会接收不到设置后加入频道的用户的视频流。

  note

  停止接收视频流后，如果想要恢复接收，请调用 muteRemoteVideoStream (false) ， 并指定你想要接收的远端用户 uid；如果想恢复接收多个用户的视频流，则需要多次调用 muteRemoteVideoStream。 setDefaultMuteAllRemoteVideoStreams (false) 只能恢复接收后面加入频道的用户的视频流。

  Parameters

  • mute: boolean

    • true: 默认停止接收所有远端视频；
    • false: 默认接收所有远端视频（默认）。

  Returns number

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

setEffectsVolume

• setEffectsVolume(volume: number): number

• 设置音效文件的播放音量。 音量范围为 0~100。100 （默认值）为原始文件音量。

  Parameters

  • volume: number

    该方法设置音效的音量。

  Returns number

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

setEnableSpeakerphone

• setEnableSpeakerphone(speakerOn: boolean): number

• 启用/关闭扬声器播放

  该方法设置是否将语音路由设到扬声器（外放）。 你可以在 setDefaultAudioRouteToSpeakerphone 方法中查看默认的语音路由。 在 Android 上， setAudioProfile 中 scenario 及 setChannelProfile 的设置 会影响 setEnableSpeakerphone 的行为。setEnableSpeakerphone 不生效的情况如下：

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

  Note

  • 请确保在调用此方法前已调用过 joinChannel 方法。
  • 调用该方法后，SDK 将返回 onAudioRouteChanged 回调提示状态已更改。

  Parameters

  • speakerOn: boolean

    设置是否切换语音路由到扬声器（外放）：

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

  Returns number

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

setEncryptionMode

• setEncryptionMode(encryptionMode: "aes-128-xts" | "aes-128-ecb" | "aes-256-xts"): number

• 启用内置的加密方案。

  deprecated

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

  note

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

  Parameters

  • encryptionMode: "aes-128-xts" | "aes-128-ecb" | "aes-256-xts"

    加密模式：

    • "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.1.2 起废弃。请改用 enableEncryption 方法。

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

  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 采样率）, 不兼容 v1.7.4 以前版本

    • true：启用全频带编解码器
    • false：禁用全频带编解码器

  • stereo: boolean

    立体声编解码器，不兼容 v1.7.4 以前版本

    • true：启用立体声编解码器
    • false：禁用立体声编解码器

  • fullBitrate: boolean

    高码率模式，建议仅在纯音频模式下使用

    • true：启用高码率模式
    • false：禁用高码率模式

  Returns number

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

setInEarMonitoringVolume

• setInEarMonitoringVolume(volume: number): number

• 设置耳返音量

  note

  用户必须使用有线耳机才能听到耳返效果。

  Parameters

  • volume: number

    设置耳返音量，取值范围在 [0,100]。默认值为 100

  Returns number

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

setLiveTranscoding

• setLiveTranscoding(transcoding: LiveTranscoding): number

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

  Note

  • 在直播场景中，只有角色为主播的用户才能调用该方法。
  • 请确保已开通旁路推流的功能。
  • 首次调用该方法更新转码设置时，不会触发 onTranscodingUpdated 回调。

  Parameters

  • transcoding: LiveTranscoding

    详见 LiveTranscoding。

  Returns number

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

setLocalPublishFallbackOption

• setLocalPublishFallbackOption(option: STREAM_FALLBACK_OPTIONS): number

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

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

  note

  视频直播场景下，旁路推流的发流用户（即主播）设置 STREAM_FALLBACK_OPTION_AUDIO_ONLY(2) 可能导致 CDN 观众听到的声音有所延迟。 声网不建议主播使用视频流回退机制。

  Parameters

  • option: STREAM_FALLBACK_OPTIONS

    本地发流回退处理选项，详见 STREAM_FALLBACK_OPTIONS。

  Returns number

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

setLocalVoiceChanger

• setLocalVoiceChanger(voiceChanger: VOICE_CHANGER_PRESET): number

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

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

  • 变声效果：枚举值以 VOICE_CHANGER 为前缀。效果包括老男人、小男孩、小女孩、猪八戒、空灵和绿巨人，通常用于语聊场景。
  • 美音效果：枚举值以 VOICE_BEAUTY 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷，通常用于语聊和唱歌场景。
  • 语聊美声效果：枚举值以 GENERAL_BEAUTY_VOICE 为前缀。效果包括磁性（男）、清新（女）和活力（女），通常用于语聊场景。该功能主要细化了男声和女声各 自的特点。

  Note

  • 为达到更好的声音效果，声网推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。
  • 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含人声和音乐的音频数据。
  • 该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。

  Parameters

  • voiceChanger: VOICE_CHANGER_PRESET

    预设本地语音变声、美音或语聊美声效果选项，默认值为 VOICE_CHANGER_OFF ，即原声。 详见 VOICE_CHANGER_PRESET 。

    设置语聊美声效果时，声网推荐使用 GENERAL_BEAUTY_VOICE_MALE_MAGNETIC 处理男声， 使用 GENERAL_BEAUTY_VOICE_FEMALE_FRESH 或 GENERAL_BEAUTY_VOICE_FEMALE_VITALITY 处理女声，否则音频可能会产生失真。

  Returns number

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

setLocalVoiceEqualization

• setLocalVoiceEqualization(bandFrequency: AUDIO_EQUALIZATION_BAND_FREQUENCY, bandGain: number): number

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

  Parameters

  • bandFrequency: AUDIO_EQUALIZATION_BAND_FREQUENCY

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

  • bandGain: number

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

  Returns number

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

setLocalVoicePitch

• setLocalVoicePitch(pitch: number): number

• 设置本地语音音调。

  Parameters

  • pitch: number

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

  Returns number

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

setLocalVoiceReverb

• setLocalVoiceReverb(reverbKey: AUDIO_REVERB_TYPE, value: number): number

• 设置本地音效混响。 你也可以调用 setLocalVoiceReverbPreset 使用预设的音效混响，例如流行、R&B、摇滚音效。

  Parameters

  • reverbKey: AUDIO_REVERB_TYPE

    混响音效 Key。该方法共有 5 个混响音效 Key: AUDIO_REVERB_TYPE 。

  • value: number

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

  Returns number

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

setLocalVoiceReverbPreset

• setLocalVoiceReverbPreset(reverbPreset: AUDIO_REVERB_PRESET): number

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

  Note

  • 当使用以 AUDIO_REVERB_FX 为前缀的枚举值时，请确保在调用该方法前将 setAudioProfile 的 profile 参数 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)，否则该方法设置无效。
  • 当使用 AUDIO_VIRTUAL_STEREO 时，声网推荐在调用该方法前将 setAudioProfile 的 profile 参数 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。
  • 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含人声和音乐的音频数据。
  • 该方法不能与 setLocalVoiceChanger 方法一同使用，否则先调的方法会不生效。

  Parameters

  • reverbPreset: AUDIO_REVERB_PRESET

    本地语音混响选项，默认值为 AUDIO_REVERB_OFF ，即原声。详见 AUDIO_REVERB_PRESET 。 为达到更好的混响效果，声网推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。

  Returns number

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

setLogFile

• setLogFile(filePath: string): number

• 设置声网 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 写入最新的日志。

  note

  如需调用本方法，请在调用 init 方法初始化声网引擎后立即调用，否则可能造成输出日志不完整。

  see

  setLogFilter

  see

  setLogFileSize

  Parameters

  • filePath: string

    日志文件的完整路径。默认路径为如下：

    • Android: /storage/emulated/0/Android/data/<package name>/files/agorasdk.log
    • iOS: App Sandbox/Library/caches/agorasdk.log

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

  Returns number

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

setLogFileSize

• setLogFileSize(fileSizeInKBytes: number): number

• 设置声网 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 写入最新的日志。

  see

  setLogFile

  see

  setLogFilter

  Parameters

  • fileSizeInKBytes: number

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

  Returns number

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

setLogFilter

• setLogFilter(filter: LOG_FILTER_TYPE): number

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

  see

  setLogFile

  see

  setLogFileSize

  Parameters

  • filter: LOG_FILTER_TYPE

    设置过滤等级: LOG_FILTER_TYPE 。

  Returns number

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

setMaxMetadataSize

• setMaxMetadataSize(size: number): number

• 请求最大的 Metadata 大小。

  Metadata 结构体由如下字段组成：

  • uid: 发送 Metadata 数据的用户 ID
  • size: 发送或收到的 Metadata 的数据大小
  • buffer: 发送或收到的 Metadata 数据
  • timeStampMs: 该 Metadata 的时间戳（毫秒）

  note

  该方法需要在 registerMediaMetadataObserver 之后调用。

  parm

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

  Parameters

  • size: number

  Returns number

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

setParameters

• setParameters(parameters: string): number

• 通过 JSON 配置 SDK 提供技术预览或特别定制功能。 JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

  Parameters

  • parameters: string

    JSON 字符串形式的参数

  Returns number

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

setRemoteDefaultVideoStreamType

• setRemoteDefaultVideoStreamType(streamType: REMOTE_VIDEO_STREAM_TYPE): number

• 设置默认订阅的视频流类型。 在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式， 接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流， 小流则是低分辨率低码率的视频流。 正常情况下，用户默认接收大流。如需默认接收所有用户的视频小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约 带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。 调用本方法的执行结果将在 onApiCallExecuted 中返回。

  Parameters

  • streamType: REMOTE_VIDEO_STREAM_TYPE

    视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

  Returns number

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

setRemoteSubscribeFallbackOption

• setRemoteSubscribeFallbackOption(option: STREAM_FALLBACK_OPTIONS): number

• 设置弱网条件下订阅的音视频流的回退选项。 默认 option 为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1)。 如果你使用本方法并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY(2)， SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高音频质量。 同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。

  当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。

  Parameters

  • option: STREAM_FALLBACK_OPTIONS

    弱网条件下订阅的音视频流的回退选项。详见 STREAM_FALLBACK_OPTIONS。

  Returns number

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

setRemoteUserPriority

• setRemoteUserPriority(uid: number, userPriority: PRIORITY_TYPE): number

• 设置远端用户流的优先级。 设置远端用户的优先级。如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。

  弱网下 SDK 会优先保证高优先级用户收到的流的质量。

  note

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

  Parameters

  • uid: number

    远端用户的 ID。

  • userPriority: PRIORITY_TYPE

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

  Returns number

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

setRemoteVideoStreamType

• setRemoteVideoStreamType(userId: number, streamType: REMOTE_VIDEO_STREAM_TYPE): number

• 设置订阅的视频流类型。 在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式， 接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流， 小流则是低分辨率低码率的视频流。 正常情况下，用户默认接收大流。如需接收小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。 视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。 调用本方法的执行结果将在 onApiCallExecuted 中返回。

  Parameters

  • userId: number

    用户 ID。

  • streamType: REMOTE_VIDEO_STREAM_TYPE

    视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

  Returns number

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

setRemoteVoicePosition