音频基础功能
AdjustCustomAudioPlayoutVolume
调节自定义音频采集轨道在本地播放的音量。
public abstract int AdjustCustomAudioPlayoutVolume(uint trackId, int volume);
详情
调用该方法设置音频在本地播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为 CreateCustomAudioTrack 方法中返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
AdjustCustomAudioPublishVolume
调节自定义音频采集轨道在远端播放的音量。
public abstract int AdjustCustomAudioPublishVolume(uint trackId, int volume);
详情
调用该方法设置音频在远端播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为 CreateCustomAudioTrack 方法中返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
AdjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
public abstract int AdjustUserPlaybackSignalVolume(uint uid, int volume);
详情
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
AdjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
public abstract int AdjustUserPlaybackSignalVolumeEx(uint uid, int volume, RtcConnection connection);
详情
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
DisableAudio
关闭音频模块。
public abstract int DisableAudio();
详情
- 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
- EnableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- MuteLocalAudioStream: 是否发布本地音频流。
- MuteRemoteAudioStream: 是否接收并播放远端音频流。
- MuteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableAudio
启用音频模块。
public abstract int EnableAudio();
详情
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能:
- EnableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- MuteLocalAudioStream: 是否发布本地音频流。
- MuteRemoteAudioStream: 是否接收并播放远端音频流。
- MuteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
- 在频道内调用该方法时,会重置 EnableLocalAudio、MuteRemoteAudioStream 和 MuteAllRemoteAudioStreams 的设置,需谨慎使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableAudioVolumeIndication
启用用户音量提示。
public abstract int EnableAudioVolumeIndication(int interval, int smooth, bool reportVad);
详情
该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 OnAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒,最小取值为 50。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
true
:开启本地人声检测功能。开启后,OnAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,OnAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
EnableAudioVolumeIndicationEx
启用用户音量提示。
public abstract int EnableAudioVolumeIndicationEx(int interval, int smooth, bool reportVad, RtcConnection connection);
详情
该方法允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 OnAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒,最小取值为 50。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
true
:开启本地人声检测功能。开启后,OnAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,OnAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
SetAudioProfile [1/2]
设置音频编码属性和音频场景。
public abstract int SetAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario);
详情
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将 profile 设置为
AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)
,scenario 设置为AUDIO_SCENARIO_GAME_STREAMING(3)
。
参数
- profile
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AUDIO_PROFILE_TYPE。
- scenario
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetAudioProfile [2/2]
设置音频编码属性。
public abstract int SetAudioProfile(AUDIO_PROFILE_TYPE profile);
详情
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将
profile
设置为AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4)
。 - 如果你想设置音频应用场景,可以直接调用 SetAudioScenario 方法进行设置,也可以调用 Initialize 并设置 RtcEngineContext 结构体中的 audioScenario。
参数
- profile
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AUDIO_PROFILE_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetAudioScenario
设置音频场景。
public abstract int SetAudioScenario(AUDIO_SCENARIO_TYPE scenario);
详情
参数
- scenario
- 音频场景,详见 AUDIO_SCENARIO_TYPE。不同的音频场景下,设备的音量类型是不同的。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetHeadphoneEQParameters
设置耳机均衡器的低频和高频参数。
public abstract int SetHeadphoneEQParameters(int lowGain, int highGain);
详情
在空间音效场景下,如果在调用 SetHeadphoneEQPreset 方法使用预设的耳机均衡效果后仍未达到预期,你可以通过调用该方法进一步调节耳机均衡效果。
参数
- lowGain
- 耳机均衡器的低频参数。取值范围为 [-10,10],取值越大,声音越低沉。
- highGain
- 耳机均衡器的高频参数。取值范围为 [-10,10],取值越大,声音越尖锐。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
SetHeadphoneEQPreset
设置预设的耳机均衡效果。
public abstract int SetHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET preset);
详情
该方法主要应用于空间音效场景下,你可以选择预设的耳机均衡器收听音频,以达到预期的音频体验。
参数
- preset
- 预设的耳机均衡效果。详见 HEADPHONE_EQUALIZER_PRESET。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
OnActiveSpeaker
监测到远端最活跃用户回调。
public virtual void OnActiveSpeaker(RtcConnection connection, uint uid) { }
详情
成功调用 EnableAudioVolumeIndication 后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发 OnActiveSpeaker 回调。
- 如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- connection
- Connection 信息。详见 RtcConnection。
- uid
- 远端最活跃用户的 ID。
OnAudioQuality
远端声音质量回调。
public virtual void OnAudioQuality(RtcConnection connection, uint remoteUid, int quality, UInt16 delay, UInt16 lost) {}
详情
该回调描述远端用户在通话中的音频质量,针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID,指定是谁发的音频流。
- quality
- 语音质量。详见 QUALITY_TYPE。
- delay
- 音频包从发送端到接收端的延迟(毫秒),包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
OnAudioVolumeIndication
用户音量提示回调。
public virtual void OnAudioVolumeIndication(RtcConnection connection, AudioVolumeInfo[] speakers, uint speakerNumber, int totalVolume) {}
详情
该回调默认禁用,你可以通过 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
已发布本地音频首帧回调。
public virtual void OnFirstLocalAudioFramePublished(RtcConnection connection, int elapsed) {}
详情
- 开启本地音频的情况下,调用 JoinChannel [2/2] 成功加入频道后。
- 调用 MuteLocalAudioStream(
true)
,再调用 MuteLocalAudioStream(false)
后。 - 调用 DisableAudio,再调用 EnableAudio 后。
- 调用 PushAudioFrame 成功向 SDK 推送音频帧后。
参数
- connection
- Connection 信息。详见 RtcConnection。
- elapsed
- 从调用 JoinChannel [2/2] 方法到触发该回调的时间间隔(毫秒)。
OnFirstRemoteAudioDecoded
已解码远端音频首帧的回调。
public virtual void OnFirstRemoteAudioDecoded(RtcConnection connection, uint uid, int elapsed) { }
详情
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 MuteLocalAudioStream 方法停止发送音频流
- 远端用户调用 DisableAudio 方法关闭音频
参数
- connection
- Connection 信息。详见 RtcConnection。
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 JoinChannel [2/2] 直至该回调触发的延迟,单位为毫秒。
OnFirstRemoteAudioFrame
已接收远端音频首帧回调。
public virtual void OnFirstRemoteAudioFrame(RtcConnection connection, uint userId, int elapsed) { }
详情
参数
- connection
- Connection 信息。详见 RtcConnection。
- userId
- 发送音频帧的远端用户的用户 ID。
- elapsed
- 从本地用户调用 JoinChannel [2/2] 直至该回调触发的延迟,单位为毫秒。
OnFrame
已获取音频帧回调。
public virtual bool OnFrame(AudioPcmFrame frame)
{
return true;
}
详情
注册音频数据观测器后,每次接收到一帧音频帧时,都会触发该回调,报告音频帧信息。
参数
- frame
- 音频帧信息。详见 AudioPcmFrame。
返回值
无实际含义。
所属接口类OnLocalAudioStateChanged
本地音频状态发生改变回调。
public virtual void OnLocalAudioStateChanged(RtcConnection connection, LOCAL_AUDIO_STREAM_STATE state, LOCAL_AUDIO_STREAM_ERROR error) {}
详情
本地音频的状态发生改变时(包括本地麦克风采集状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助你了解当前音频的状态以及出现故障的原因,方便你排查问题。
参数
- connection
- Connection 信息。详见 RtcConnection。
- state
- 当前的本地音频状态。详见 LOCAL_AUDIO_STREAM_STATE。
- error
- 本地音频出错原因。详见 LOCAL_AUDIO_STREAM_ERROR。
OnLocalAudioStats
通话中本地音频流的统计信息回调。
public virtual void OnLocalAudioStats(RtcConnection connection, LocalAudioStats stats) {}
详情
SDK 每 2 秒触发该回调一次。
参数
- connection
- Connection 信息。详见 RtcConnection。
- stats
- 本地音频统计数据。详见 LocalAudioStats。
OnRemoteAudioStateChanged
远端音频流状态发生改变回调。
public virtual void OnRemoteAudioStateChanged(RtcConnection connection, uint remoteUid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) {}
详情
远端用户(通信场景)或主播(直播场景)的音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 发生音频状态改变的远端用户 ID。
- state
- 远端音频流状态,详见 REMOTE_AUDIO_STATE。
- reason
- 远端音频流状态改变的具体原因,详见 REMOTE_AUDIO_STATE_REASON。
- elapsed
- 从本地用户调用 JoinChannel [2/2] 方法到发生本事件经历的时间,单位为毫秒。
OnRemoteAudioStats
通话中远端音频流的统计信息回调。
public virtual void OnRemoteAudioStats(RtcConnection connection, RemoteAudioStats stats) {}
详情
该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流,该回调每 2 秒会被触发多次。
参数
- connection
- Connection 信息。详见 RtcConnection。
- stats
- 接收到的远端音频统计数据,详见 RemoteAudioStats。
OnRemoteAudioTransportStats
通话中远端音频流传输的统计信息回调。
public virtual void OnRemoteAudioTransportStats(RtcConnection connection, uint remoteUid, UInt16 delay, UInt16 lost, UInt16 rxKBitRate) {}
详情
该回调描述远端用户通话中端到端的网络统计信息,通过音频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。通话中,当用户收到远端用户/主播发送的音频数据包后 ,会每 2 秒触发一次该回调。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID,指定是哪个用户/主播的音频包。
- delay
- 音频包从发送端到接收端的延时(毫秒)。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
- rxKBitrate
- 远端音频包的接收码率(Kbps)。
OnUserMuteAudio
远端用户(通信场景)/主播(直播场景)停止或恢复发送音频流回调。
public virtual void OnUserMuteAudio(RtcConnection connection, uint remoteUid, bool muted) { }
详情
该回调是由远端用户调用 MuteLocalAudioStream 方法关闭或开启音频发送触发的。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID。
- muted
- 该用户是否静音:
true
: 该用户已将音频静音。false
: 该用户取消了音频静音。