音频基础功能

adjustUserPlaybackSignalVolume

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

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

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

调用时机

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

调用限制

无。

参数

uid

远端用户 ID。

volume

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

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

返回值

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

所属接口类

IRtcEngine

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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngineEx

disableAudio

关闭音频模块。

TypeScript
abstract disableAudio(): number;

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

调用时机

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

调用限制

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

enableLocalAudio：是否启动麦克风采集并创建本地音频流。
muteLocalAudioStream：是否发布本地音频流。
muteRemoteAudioStream：是否接收并播放远端音频流。
muteAllRemoteAudioStreams：是否接收并播放所有远端音频流。

返回值

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

所属接口类

IRtcEngine

enableAudio

启用音频模块。

TypeScript
abstract enableAudio(): number;

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

调用时机

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

调用限制

调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能：
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
在频道内调用该方法时，会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置，需谨慎使用。

返回值

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

所属接口类

IRtcEngine

enableAudioVolumeIndication

启用用户音量提示。

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

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

调用时机

加入频道前后均可调用。

调用限制

无。

参数

interval

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

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

smooth

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

reportVad

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

返回值

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

所属接口类

IRtcEngine

enableAudioVolumeIndicationEx

启用用户音量提示。

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

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

调用时机

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

调用限制

无。

参数

interval

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

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

smooth

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

reportVad

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

connection

Connection 信息。详见 RtcConnection。

返回值

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

所属接口类

IRtcEngineEx

setAudioProfile

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

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

适用场景

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

调用时机

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

调用限制

由于 iOS 系统限制，部分音频路由在通话音量模式下无法识别。因此，如需使用外接声卡，建议将音频应用场景设置为高音质场景 AudioScenarioGameStreaming(3)。在这种场景下，SDK 会切换到媒体音量规避该问题。

参数

profile: 音频编码属性，包含采样率、码率、编码模式和声道数。详见 AudioProfileType。
scenario: 音频场景。不同的音频场景下，设备的音量类型是不同的。详见 AudioScenarioType 。

返回值

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

所属接口类

IRtcEngine

setAudioScenario

设置音频场景。

TypeScript
abstract setAudioScenario(scenario: AudioScenarioType): number;

适用场景

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

调用时机

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

调用限制

参数

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

返回值

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

所属接口类

IRtcEngine

setAudioSessionOperationRestriction

设置 SDK 对 Audio Session 的操作权限。

TypeScript
abstract setAudioSessionOperationRestriction(
    restriction: AudioSessionOperationRestriction
  ): number;

详情

默认情况下，SDK 和 App 对 Audio Session 都有操作权限。如果你只需使用 App 对 Audio Session 进行操作，你可以调用该方法限制 SDK 对 Audio Session 的操作权限。

该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限，该限制会在 SDK 需要更改 Audio Session 时生效。

注意

该方法仅适用于 iOS 平台。
该方法不会限制 App 对 Audio Session 的操作权限。

参数

restriction: SDK 对 Audio Session 的操作权限，详见 AudioSessionOperationRestriction。该参数为 Bit Mask，每个 Bit 对应一个权限。

返回值

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

所属接口类

IRtcEngine

onActiveSpeaker

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

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

详情

成功调用 enableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。

当频道内用户数量大于或等于 2 且有远端活跃用户时，SDK 会触发该回调并报告远端最活跃用户的 uid。

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

参数

connection: Connection 信息。详见 RtcConnection。
uid: 远端最活跃用户的 ID。

所属接口类

IRtcEngineEventHandler

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: 音频包从发送端到接收端的丢包率 (%)。

所属接口类

IRtcEngineEventHandler

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 位）混音后的总音量。

所属接口类

IRtcEngineEventHandler

onFirstLocalAudioFramePublished

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

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

详情

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

开启本地音频的情况下，调用 joinChannel 成功加入频道后。
调用 muteLocalAudioStream(true)，再调用 muteLocalAudioStream(false) 后。
调用 disableAudio，再调用 enableAudio 后。

参数

connection: Connection 信息。详见 RtcConnection。
elapsed: 从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

所属接口类

IRtcEngineEventHandler

onFirstRemoteAudioDecoded

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

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

详情

废弃

请改用 onRemoteAudioStateChanged 。

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

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

参数

connection: Connection 信息。详见 RtcConnection。
uid: 远端用户 ID。
elapsed: 从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。

所属接口类

IRtcEngineEventHandler

onFirstRemoteAudioFrame

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

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

详情

废弃

请改用 onRemoteAudioStateChanged 。

参数

connection: Connection 信息。详见 RtcConnection。
userId: 发送音频帧的远端用户的用户 ID。
elapsed: 从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。

所属接口类

IRtcEngineEventHandler

onLocalAudioStateChanged

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

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

详情

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

注意

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

参数

connection: Connection 信息。详见 RtcConnection。
state: 当前的本地音频状态。详见 LocalAudioStreamState。
reason: 本地音频状态改变原因。详见 LocalAudioStreamReason。

所属接口类

IRtcEngineEventHandler

onLocalAudioStats

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

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

详情

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

参数

connection: Connection 信息。详见 RtcConnection。
stats: 本地音频统计数据。详见 LocalAudioStats。

所属接口类

IRtcEngineEventHandler

onRemoteAudioStateChanged

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

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

详情

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

注意

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

参数

connection: Connection 信息。详见 RtcConnection。
remoteUid: 发生音频状态改变的远端用户 ID。
state: 远端音频流状态，详见 RemoteAudioState。
reason: 远端音频流状态改变的具体原因，详见 RemoteAudioStateReason。
elapsed: 从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为毫秒。

所属接口类

IRtcEngineEventHandler

onRemoteAudioStats

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

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

详情

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

参数

connection: Connection 信息。详见 RtcConnection。
stats: 接收到的远端音频统计数据，详见 RemoteAudioStats。

所属接口类

IRtcEngineEventHandler

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）。

所属接口类

IRtcEngineEventHandler

onUserMuteAudio

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

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

详情

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

注意

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

参数

connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID。

muted

该用户是否静音：

true: 该用户已将音频静音。
false: 该用户取消了音频静音。

所属接口类

IRtcEngineEventHandler

adjustUserPlaybackSignalVolume

调用时机

调用限制

参数​

返回值​

adjustUserPlaybackSignalVolumeEx

调用时机

调用限制

参数​

返回值​

disableAudio

调用时机

调用限制

返回值​

enableAudio

调用时机

调用限制

返回值​

enableAudioVolumeIndication

调用时机

调用限制

相关回调

参数​

返回值​

enableAudioVolumeIndicationEx

调用时机

调用限制

相关回调

参数​

返回值​

setAudioProfile

适用场景

调用时机

调用限制

参数​

返回值​

setAudioScenario

适用场景

调用时机

调用限制

参数​

返回值​

setAudioSessionOperationRestriction

详情​

参数​

返回值​

onActiveSpeaker

详情​

参数​

onAudioQuality

详情​

参数​

onAudioVolumeIndication

详情​

参数​

onFirstLocalAudioFramePublished

详情​

参数​

onFirstRemoteAudioDecoded

详情​

参数​

onFirstRemoteAudioFrame

详情​

参数​

onLocalAudioStateChanged

详情​

参数​

onLocalAudioStats

详情​

参数​

onRemoteAudioStateChanged

详情​

参数​

onRemoteAudioStats

详情​

参数​

onRemoteAudioTransportStats

详情​

参数​

onUserMuteAudio

参数

返回值

参数

返回值

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

详情

参数

返回值

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数

详情

参数