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

音频基础功能

  • C++

更新时间不可用

adjustPlaybackSignalVolume

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

C++
virtual int adjustPlaybackSignalVolume(int volume) = 0;

如果你需要调节某个指定远端用户的本地播放音量，建议调用 adjustUserPlaybackSignalVolume 方法。

调用时机

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

参数

参数名描述
volume

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

  • 0：静音。
  • 100：（默认）原始音量。
  • 400：原始音量的四倍（将音频信号放大四倍）。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

adjustUserPlaybackSignalVolume

调整指定远端用户的播放信号音量。

C++
virtual int adjustUserPlaybackSignalVolume(uid_t uid, int volume) = 0;

你可以调用该方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量，请分别多次调用该方法，每次针对一个远端用户。

调用时机

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

参数

参数名描述
uid

远端用户的用户 ID。

volume

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

  • 0：静音。
  • 100：（默认）原始音量。
  • 400：原始音量的四倍（将音频信号放大四倍）。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

adjustUserPlaybackSignalVolumeEx

调整指定远端用户的播放信号音量。

C++
virtual int adjustUserPlaybackSignalVolumeEx(uid_t uid, int volume, const RtcConnection& connection) = 0;

你可以调用该方法调整指定远端用户的播放音量。若需调整多个远端用户的播放音量，请分别多次调用该方法，每次针对一个远端用户。

适用场景

该方法适用于多频道场景。

调用时机

请在调用 joinChannelEx 后调用该方法。

参数

参数名描述
uid

远端用户的用户 ID。

volume

用户的音量，取值范围为 [0, 400]：

  • 0：静音。
  • 100：（默认）原始音量。
  • 400：原始音量的四倍（将音频信号放大四倍）。
connection

连接信息。详见 RtcConnection。

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

返回值

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

所属接口类

disableAudio

禁用音频模块。

C++
virtual int disableAudio() = 0;

注： 该方法会重置内部引擎，并需要一定时间生效。声网建议使用以下 API 分别控制音频模块：

调用时机

该方法可以在加入频道前或加入频道后调用。离开频道后仍然有效。

返回值

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

所属接口类

enableAudio

启用音频模块。

C++
virtual int enableAudio() = 0;

音频模块默认处于启用状态。调用 disableAudio 方法禁用音频模块后，可以调用该方法重新启用音频模块。

注： 调用该方法会重置整个引擎，可能导致响应时间变慢。你可以根据实际需求，使用以下方法分别控制音频模块的具体功能：

成功调用该方法会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置，请谨慎使用。

调用时机

该方法可以在加入频道前或加入频道后调用，离开频道后仍然有效。

返回值

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

所属接口类

enableAudioVolumeIndication

启用用户音量提示的上报功能。

C++
virtual int enableAudioVolumeIndication(int interval, int smooth, bool reportVad) = 0;

该方法用于启用 SDK 定期向应用上报本地发送音频流的用户和瞬时音量最大的最多三位远端用户的音量信息。

调用时机

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

相关回调

成功调用该方法后，若频道中有用户发布音频流，SDK 会按照设置的时间间隔触发 onAudioVolumeIndication 回调。

参数

参数名描述
interval

设置两次音量提示之间的时间间隔（毫秒）：

  • ≤ 0：关闭音量提示功能。
  • > 0：两次音量提示之间的时间间隔（单位为毫秒）。该值需大于 10，否则无法收到 onAudioVolumeIndication 回调。建议设置为大于 100。
smooth

设置音量提示的灵敏度平滑系数，取值范围为 0 到 10，推荐值为 3。值越大，提示越灵敏。

reportVad

是否启用本地用户的语音活动检测（VAD）：

  • true：启用语音活动检测。启用后，onAudioVolumeIndication 回调中的 vad 参数会报告本地用户的语音活动状态。
  • false：（默认）关闭语音活动检测。关闭后，onAudioVolumeIndication 回调中的 vad 参数不会报告本地用户的语音活动状态，除非引擎自动检测到语音活动。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

enableAudioVolumeIndicationEx

启用用户音量提示的上报功能。

C++
virtual int enableAudioVolumeIndicationEx(int interval, int smooth, bool reportVad, const RtcConnection& connection) = 0;

该方法用于启用 SDK 定期向应用上报本地发送音频流的用户和音量瞬时值最高的最多三位远端用户的音量信息。

适用场景

该方法适用于多频道场景。

调用时机

请在调用 joinChannelEx 后调用该方法。

相关回调

成功调用该方法后，SDK 会根据设置的时间间隔触发 onAudioVolumeIndication 回调，在频道中有用户发布音频流时报告音量信息。

参数

参数名描述
interval

设置两次音量提示之间的时间间隔（毫秒）：

  • ≤ 0：关闭音量提示。
  • > 0：两次音量提示之间的时间间隔（毫秒）。该值需大于 10，否则无法收到 onAudioVolumeIndication 回调。建议设置为大于 100。
smooth

设置音量提示的灵敏度平滑系数，取值范围为 0 到 10，推荐值为 3。值越大，提示越灵敏。

reportVad

是否启用本地用户的语音活动检测（Voice Activity Detection）：

  • true：启用语音活动检测。启用后，onAudioVolumeIndication 回调中的 vad 参数会报告本地用户的语音活动状态。
  • false：（默认）关闭语音活动检测。关闭后，onAudioVolumeIndication 回调中的 vad 参数不会报告本地用户的语音活动状态，除非引擎自动检测到语音活动。
connection

连接信息。详见 RtcConnection。

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

返回值

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

所属接口类

setAudioProfile [1/2]

设置音频配置和音频场景。

C++
virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) __deprecated = 0;

废弃

该方法已废弃。你可以改用 setAudioProfile [2/2] 方法。若需设置音频场景，请调用 initialize 方法，并在 RtcEngineContext 结构体中的 audioScenario 成员中传入值。

注： 由于 iOS 系统限制，在通话音量模式下部分音频路由无法识别。因此，如需使用外置声卡，建议将音频场景设置为 AUDIO_SCENARIO_GAME_STREAMING（3）。在该场景下，SDK 会切换为媒体音量以规避该问题。

适用场景

该方法适用于多种音频场景，你可以根据实际需求进行选择。例如，在对音质要求较高的场景（如音乐教学）中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4），将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING（3）。你可以在加入频道前或加入频道后调用该方法。

参数

参数名描述
profile

音频配置，包括采样率、码率、编码模式和声道数。详见 AUDIO_PROFILE_TYPE。

scenario

音频场景，在不同的音频场景下设备使用不同的音量类型。详见 AUDIO_SCENARIO_TYPE。

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

返回值

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

所属接口类

setAudioProfile [2/2]

设置音频配置文件。

C++
virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile) = 0;

适用场景

你可以根据实际需求选择合适的音频配置文件。例如，在音乐教学等对音质要求较高的场景中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY（4）。如果你需要设置音频场景，可以调用 setAudioScenario，或者调用 initialize 并在 RtcEngineContext 中设置 audioScenario。

调用时机

你可以在加入频道前或后调用该方法。

参数

参数名描述
profile

音频配置文件，包括采样率、码率、编码模式和声道数。详见 AUDIO_PROFILE_TYPE。

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

返回值

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

所属接口类

setAudioScenario

设置音频场景。

C++
virtual int setAudioScenario(AUDIO_SCENARIO_TYPE scenario) = 0;

注： 由于 iOS 系统限制，在通话音量模式下，部分音频路由可能无法识别。如果你需要使用外置声卡，建议将音频场景设置为 AUDIO_SCENARIO_GAME_STREAMING（3）。在该场景下，SDK 会切换为媒体音量，以避免该问题。

适用场景

该方法适用于多种音频场景。例如，在对音质要求较高的音乐教学场景中，建议将 scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING（3）。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

参数名描述
scenario

音频场景。不同音频场景下，设备使用不同的音量类型。详见 AUDIO_SCENARIO_TYPE。

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

返回值

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

所属接口类

setAudioSessionOperationRestriction

设置 SDK 对音频会话的操作权限。

C++
virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0;

默认情况下，SDK 和 App 都可以配置音频会话。如果你只希望由 App 配置音频会话，可以通过该方法限制 SDK 的操作权限。你可以在加入频道前或后调用该方法。一旦调用该方法进行限制，当 SDK 需要更改音频会话时，该限制将生效。

注：

  • 该方法仅适用于 iOS。
  • 该方法不会限制 App 对音频会话的操作权限。

参数

参数名描述
restriction

SDK 对音频会话的操作权限。该参数为位掩码格式，每一位对应一个权限。详见 AUDIO_SESSION_OPERATION_RESTRICTION。

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

返回值

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

所属接口类

onActiveSpeaker

最活跃远端说话人回调。

C++
virtual void onActiveSpeaker(uid_t uid)

调用 enableAudioVolumeIndication 方法成功后，SDK 会持续检测哪位远端用户的音量最大。在当前周期内，音量被检测为最大次数最多的远端用户即为最活跃用户。当频道中用户数不少于两人且存在活跃的远端说话人时，SDK 会触发该回调并报告最活跃远端说话人的用户 ID。

  • 如果最活跃的远端说话人始终是同一用户，SDK 只会触发一次该回调。
  • 如果最活跃的远端说话人变更为其他用户，SDK 会再次触发该回调并报告新的最活跃远端说话人的用户 ID。

参数

参数名描述
uid

最活跃远端说话人的用户 ID。

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

所属接口类

onAudioQuality

报告每个远端用户发送的音频流的统计信息。

C++
virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost) __deprecated

废弃

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

SDK 每两秒触发一次该回调，用于报告每个正在发送音频流的远端用户的音频质量。如果频道中有多个用户发送音频流，SDK 会触发多次该回调。

参数

参数名描述
uid

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

quality

该用户的音频质量，详见 QUALITY_TYPE。

delay

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

lost

从远端用户到接收端的音频数据包丢包率（%）。

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

所属接口类

onAudioVolumeIndication

onAudioVolumeIndication 回调。

C++
virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume)

默认情况下，该回调处于关闭状态。你可以通过调用 enableAudioVolumeIndication 方法开启该回调。开启后，当频道中有用户发送音频流时，SDK 会按照 enableAudioVolumeIndication 中设置的时间间隔触发该回调。SDK 会同时触发两个独立的 onAudioVolumeIndication 回调，分别报告发送音频流的本地用户和瞬时音量最高的最多三位远端用户的音量信息。

注： 开启该回调后，即使本地用户调用 muteLocalAudioStream 方法将音频静音，SDK 仍会继续报告本地用户的音量信息。如果某位远端用户的音量为频道中前三高之一，但停止发布音频流超过 20 秒，该回调将不再包含该用户的信息；如果所有远端用户都停止发布音频流超过 20 秒，SDK 将不再触发远端用户的音量回调。

触发时机

当启用音量提示并有用户发送音频流时触发。

参数

参数名描述
speakers

用户的音量信息。详见 AudioVolumeInfo。当该回调中的 speakers 数组为空时，表示频道中没有远端用户或没有用户发送音频流。

speakerNumber

用户总数。

  • 本地用户的回调中，如果本地用户正在发送音频流，speakerNumber 的值为 1。
  • 远端用户的回调中，speakerNumber 的取值范围为 [0, 3]。如果发送音频流的远端用户数量大于或等于 3，speakerNumber 的值为 3。
totalVolume

说话者的音量，取值范围为 [0, 255]。

  • 本地用户的回调中，totalVolume 表示本地用户的音量。
  • 远端用户的回调中，totalVolume 表示瞬时音量最高的最多三位远端用户的音量总和。如果调用了 startAudioMixing，则该值为混音后的音量。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onFirstLocalAudioFramePublished

本地用户发布首帧音频时触发的回调。

C++
virtual void onFirstLocalAudioFramePublished(int elapsed)

触发时机

该回调在以下任一情况下由 SDK 触发：

  • 本地客户端启用音频模块并成功调用 joinChannel。
  • 本地客户端依次调用 muteLocalAudioStream(true) 和 muteLocalAudioStream(false)。
  • 本地客户端依次调用 disableAudio 和 enableAudio。
  • 本地客户端调用 pushAudioFrame 成功将音频帧推送至 SDK。

参数

参数名描述
elapsed

从本地用户调用 joinChannel 到 SDK 触发该回调的时间间隔（毫秒）。

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

所属接口类

onFirstRemoteAudioDecoded

首帧远端音频解码完成回调。

C++
virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) __deprecated

废弃

该方法已废弃，请改用 onRemoteAudioStateChanged。

触发时机

当远端用户首次发送音频流，或音频从离线恢复为在线重新发送音频时触发。

参数

参数名描述
uid

远端用户 ID。

elapsed

从本地用户调用 joinChannel 加入频道到 SDK 触发该回调的时间，单位为毫秒。

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

所属接口类

onFirstRemoteAudioFrame

远端用户音频首帧到达回调。

C++
virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) __deprecated

废弃

该方法已废弃，请改用 onRemoteAudioStateChanged。

参数

参数名描述
uid

远端用户 ID。

elapsed

从本地用户调用 joinChannel 加入频道到 SDK 触发该回调的时间，单位为毫秒。

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

所属接口类

onLocalAudioStateChanged

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

C++
virtual void onLocalAudioStateChanged(LOCAL_AUDIO_STREAM_STATE state, LOCAL_AUDIO_STREAM_REASON reason)

当本地音频流的状态（包括音频采集和编码状态）发生变化时，SDK 会触发该回调报告当前状态，帮助你排查音频异常问题。

注： 当状态为 LOCAL_AUDIO_STREAM_STATE_FAILED（3）时，可以在 reason 参数中查看错误信息。

参数

参数名描述
state

本地音频流的状态，详见 LOCAL_AUDIO_STREAM_STATE。

reason

本地音频流状态变化的原因，详见 LOCAL_AUDIO_STREAM_REASON。

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

所属接口类

onLocalAudioStats

本地音频统计信息回调。

C++
virtual void onLocalAudioStats(const LocalAudioStats& stats)

触发时机

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

参数

参数名描述
stats

本地音频统计信息。详见 LocalAudioStats。

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

所属接口类

onRemoteAudioStateChanged

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

C++
virtual void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed)

注： 当通信场景下的用户或直播场景下的主播数量超过 32 时，该回调无法正常工作。

触发时机

当远端用户的音频状态发生变化时触发。

参数

参数名描述
uid

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

state

远端音频状态。详见 REMOTE_AUDIO_STATE。

reason

远端音频状态变化的原因。详见 REMOTE_AUDIO_STATE_REASON。

elapsed

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

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

所属接口类

onRemoteAudioStats

远端音频流统计信息回调。

C++
virtual void onRemoteAudioStats(const RemoteAudioStats& stats)

该回调每两秒触发一次，用于报告每个正在发送音频流的远端用户的传输层统计信息。如果频道中有多个远端用户，SDK 会分别为每个用户触发该回调。

参数

参数名描述
stats

远端音频流的统计信息。详见 RemoteAudioStats。

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

所属接口类

onRemoteAudioTransportStats

报告每个远端音频流的传输层统计信息回调。

C++
virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) __deprecated

废弃

该方法已废弃，请改用 onRemoteAudioStats。

该回调报告传输层的统计信息，例如在本地用户接收到远端用户的音频数据包后，数据包的丢失率和网络时延。该回调在通话过程中每 2 秒触发一次。

触发时机

在通话过程中，每当本地用户接收到远端用户发送的音频数据包时，每 2 秒触发一次。

参数

参数名描述
uid

远端用户 ID，即发送音频流的用户。

delay

从远端用户到本地接收端的网络时延（毫秒）。

lost

从远端用户到本地接收端的音频数据包丢失率（%）。

rxKBitRate

接收到的音频码率（Kbps）。

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

所属接口类

onUserMuteAudio

远端用户或主播停止或恢复发送音频流回调。

C++
virtual void onUserMuteAudio(uid_t uid, bool muted)

当远端用户调用 muteLocalAudioStream 停止或恢复发送音频流时，SDK 会触发该回调。

注： 当通信场景中的用户数量或直播场景中的主播数量超过 32 时，该回调可能无法正常工作。

参数

参数名描述
uid

远端用户 ID。

muted

远端用户的音频流是否被静音：

  • true：音频流被静音。
  • false：音频流未被静音。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利