需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

音频基础功能

  • Electron

更新时间不可用

adjustPlaybackSignalVolume

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

TypeScript
abstract adjustPlaybackSignalVolume(volume: number): number;

该方法用于调节所有远端用户混音后在本地播放的信号音量，如果你需要调节指定远端用户在本地播放的信号音量，建议你调用 adjustUserPlaybackSignalVolume。

调用时机

加入频道前后均可调用。

参数

参数名描述
volume

音量，取值范围为 [0,400]。

  • 0: 静音。
  • 100: （默认）原始音量。
  • 400: 原始音量的 4 倍，自带溢出保护。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

adjustUserPlaybackSignalVolume

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

TypeScript
abstract adjustUserPlaybackSignalVolume(uid: number, volume: number): number;

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

调用时机

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

参数

参数名描述
uid

远端用户 ID。

volume

音量，取值范围为 [0,400]。

  • 0: 静音。
  • 100: （默认）原始音量。
  • 400: 原始音量的 4 倍，自带溢出保护。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

adjustUserPlaybackSignalVolumeEx

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

TypeScript
abstract adjustUserPlaybackSignalVolumeEx(
    uid: number,
    volume: number,
    connection: RtcConnection
  ): number;

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

调用时机

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

参数

参数名描述
uid

远端用户 ID。

volume

音量，取值范围为 [0,400]。

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

Connection 信息。详见 RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

disableAudio

关闭音频模块。

TypeScript
abstract disableAudio(): number;

音频模块默认开启，你可以调用该方法关闭音频模块。

注： 该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制音频模块：

调用时机

加入频道前后均可调用。离开频道后仍然有效。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

enableAudio

启用音频模块。

TypeScript
abstract enableAudio(): number;

音频模块默认开启。如果你调用 disableAudio 关闭了音频模块，可调用该方法重新开启。

注：

调用时机

加入频道前后均可调用。离开频道后仍然有效。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

enableAudioVolumeIndication

启用用户音量提示。

TypeScript
abstract enableAudioVolumeIndication(
    interval: number,
    smooth: number,
    reportVad: boolean
  ): number;

该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

调用时机

加入频道前后均可调用。

相关回调

成功调用该方法、且频道内存在发流用户时，SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调。

参数

参数名描述
interval

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

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

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

reportVad
  • true：开启本地人声检测功能。开启后，onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
  • false：（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

enableAudioVolumeIndicationEx

启用用户音量提示。

TypeScript
abstract enableAudioVolumeIndicationEx(
    interval: number,
    smooth: number,
    reportVad: boolean,
    connection: RtcConnection
  ): number;

该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

调用时机

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

相关回调

成功调用该方法、且频道内存在发流用户时，SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调。

参数

参数名描述
interval

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

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

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

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

Connection 信息。详见 RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setAudioProfile

设置音频编码属性和音频场景。

TypeScript
abstract setAudioProfile(
    profile: AudioProfileType,
    scenario?: AudioScenarioType
  ): number;

适用场景

该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 profile 设置为 AudioProfileMusicHighQuality(4)，scenario 设置为 AudioScenarioGameStreaming(3)。

调用时机

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

参数

参数名描述
profile

音频编码属性，包含采样率、码率、编码模式和声道数。详见 AudioProfileType。

scenario

音频场景。不同的音频场景下，设备的音量类型是不同的。 详见 AudioScenarioType 。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setAudioScenario

设置音频场景。

TypeScript
abstract setAudioScenario(scenario: AudioScenarioType): number;

适用场景

该方法适用于各种音频场景，你可以按需选择。例如，在音乐教学等高音质需求的场景中，建议将 scenario 设置为 AudioScenarioGameStreaming(3)。

调用时机

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

参数

参数名描述
scenario

音频场景。不同的音频场景下，设备的音量类型是不同的。 详见 AudioScenarioType 。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

onActiveSpeaker

监测到远端最活跃用户回调。

TypeScript
onActiveSpeaker?(connection: RtcConnection, uid: number): void;

成功调用 enableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。 当频道内用户数量大于或等于 2 且有远端活跃用户时，SDK 会触发该回调并报告远端最活跃用户的 uid。

  • 如果远端最活跃用户一直是同一位用户，则 SDK 不会再次触发 onActiveSpeaker 回调。
  • 如果远端最活跃用户有变化，则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

uid

远端最活跃用户的 ID。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onAudioQuality

远端声音质量回调。

TypeScript
onAudioQuality?(
    connection: RtcConnection,
    remoteUid: number,
    quality: QualityType,
    delay: number,
    lost: number
  ): void;

废弃

弃用： 请改用 onRemoteAudioStats。

该回调描述远端用户在通话中的音频质量，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID，指定是谁发的音频流。

quality

语音质量。详见 QualityType。

delay

音频包从发送端到接收端的延迟（毫秒），包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。

lost

音频包从发送端到接收端的丢包率 (%)。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onAudioVolumeIndication

用户音量提示回调。

TypeScript
onAudioVolumeIndication?(connection: RtcConnection, speakers: AudioVolumeInfo[], speakerNumber: number, totalVolume: number): void;

该回调默认禁用，你可以通过 enableAudioVolumeIndication 开启。 开启后，只要频道内有发流用户，SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 onAudioVolumeIndication 回调。每次会触发两个 onAudioVolumeIndication 回调，一个报告本地发流用户的音量相关信息，另一个报告瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

注： 启用该功能后，如果有用户将自己静音（调用了 muteLocalAudioStream），SDK 会继续报告本地用户的音量提示回调。 瞬时音量最高的远端用户静音后 20 秒，远端的音量提示回调中将不再包含该用户；如果远端所有用户都将自己静音，20 秒后 SDK 停止报告远端用户的音量提示回调。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

speakers

用户音量信息，详见 AudioVolumeInfo 数组。如果 speakers 为空，则表示远端用户不发流或没有远端用户。

speakerNumber

用户数量。

  • 在本地用户的回调中，只要本地用户在发流，speakerNumber 始终为 1。
  • 在远端用户的回调中，speakerNumber 取值范围为 [0,3]。如果远端发流用户数量大于 3，则此回调中 speakerNumber 值为 3。
totalVolume

混音后的总音量，取值范围为 [0,255]。

  • 在本地用户的回调中，totalVolume 为本地发流用户的音量。
  • 在远端用户的回调中，totalVolume 为瞬时音量最高的远端用户（最多 3 位）混音后的总音量。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onFirstLocalAudioFramePublished

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

TypeScript
onFirstLocalAudioFramePublished?(
    connection: RtcConnection,
    elapsed: number
  ): void;

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

elapsed

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onFirstRemoteAudioDecoded

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

TypeScript
onFirstRemoteAudioDecoded?(
    connection: RtcConnection,
    uid: number,
    elapsed: number
  ): void;

废弃

弃用： 请改用 onRemoteAudioStateChanged 。

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

  • 远端用户首次上线后发送音频。

  • 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：

    • 远端用户离开频道
    • 远端用户掉线
    • 远端用户调用 muteLocalAudioStream 方法停止发送音频流
    • 远端用户调用 disableAudio 方法关闭音频

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

uid

远端用户 ID。

elapsed

从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onFirstRemoteAudioFrame

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

TypeScript
onFirstRemoteAudioFrame?(
    connection: RtcConnection,
    userId: number,
    elapsed: number
  ): void;

废弃

弃用： 请改用 onRemoteAudioStateChanged 。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

userId

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

elapsed

从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onLocalAudioStateChanged

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

TypeScript
onLocalAudioStateChanged?(
    connection: RtcConnection,
    state: LocalAudioStreamState,
    reason: LocalAudioStreamReason
  ): void;

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

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

state

当前的本地音频状态。详见 LocalAudioStreamState。

reason

本地音频状态改变原因。详见 LocalAudioStreamReason。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onLocalAudioStats

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

TypeScript
onLocalAudioStats?(connection: RtcConnection, stats: LocalAudioStats): void;

SDK 每 2 秒触发该回调一次。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

stats

本地音频统计数据。详见 LocalAudioStats。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onRemoteAudioStateChanged

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

TypeScript
onRemoteAudioStateChanged?(
    connection: RtcConnection,
    remoteUid: number,
    state: RemoteAudioState,
    reason: RemoteAudioStateReason,
    elapsed: number
  ): void;

远端用户（通信场景）或主播（直播场景）的音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

注： 频道内的用户（通信场景）或主播（直播场景）人数超过 32 人时，该回调可能不准确。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

发生音频状态改变的远端用户 ID。

state

远端音频流状态，详见 RemoteAudioState。

reason

远端音频流状态改变的具体原因，详见 RemoteAudioStateReason。

elapsed

从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为毫秒。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onRemoteAudioStats

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

TypeScript
onRemoteAudioStats?(connection: RtcConnection, stats: RemoteAudioStats): void;

该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流，该回调每 2 秒会被触发多次。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

stats

接收到的远端音频统计数据，详见 RemoteAudioStats。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onRemoteAudioTransportStats

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

TypeScript
onRemoteAudioTransportStats?(
    connection: RtcConnection,
    remoteUid: number,
    delay: number,
    lost: number,
    rxKBitRate: number
  ): void;

弃用： 请改用 onRemoteAudioStats。 该回调描述远端用户通话中端到端的网络统计信息，通过音频包计算，用客观的数据，如丢包、 网络延迟等，展示当前网络状态。通话中，当用户收到远端用户/主播发送的音频数据包后，会每 2 秒触发一次该回调。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID，指定是哪个用户/主播的音频包。

delay

音频包从发送端到接收端的延时（毫秒）。

lost

音频包从发送端到接收端的丢包率 (%)。

rxKBitrate

远端音频包的接收码率（Kbps）。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onUserMuteAudio

远端用户（通信场景）/主播（直播场景）停止或恢复发送音频流回调。

TypeScript
onUserMuteAudio?(
    connection: RtcConnection,
    remoteUid: number,
    muted: boolean
  ): void;

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

注： 频道内的用户（通信场景）或主播（直播场景）人数超过 32 人时，该回调可能不准确。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID。

muted

该用户是否静音：

  • true: 该用户已将音频静音。
  • false: 该用户取消了音频静音。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利