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

自定义音频采集和渲染

  • Android

更新时间不可用

adjustCustomAudioPlayoutVolume

调节本地播放的自定义音频轨道的音量。

Java
public abstract int adjustCustomAudioPlayoutVolume(int trackId, int volume);

如果你希望更改本地播放的音频音量，需要再次调用该方法。

注： 请确保在调用该方法前，已调用 createCustomAudioTrack 创建自定义音频轨道。

参数

参数名描述
trackId

音频轨道 ID。设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

volume

音频源的音量，取值范围为 0 到 100。

  • 0：静音。
  • 100：原始音量。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

adjustCustomAudioPublishVolume

调节远端播放的自定义音频轨道的音量。

Java
public abstract int adjustCustomAudioPublishVolume(int trackId, int volume);

如果你想更改远端播放的音频音量，需要再次调用该方法。

注： 请确保在调用该方法前已调用 createCustomAudioTrack 创建自定义音频轨道。

参数

参数名描述
trackId

音频轨道 ID。设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

volume

音频源的音量，取值范围为 0 到 100。

  • 0：静音。
  • 100：原始音量。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

createCustomAudioTrack

创建一个自定义音频轨道。

Java
public abstract int createCustomAudioTrack(Constants.AudioTrackType trackType, AudioTrackConfig config)

你可以通过以下步骤发布自定义音频源：

  1. 调用该方法创建一个自定义音频轨道，并获取音频轨道 ID。
  2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为步骤 1 中获取的音频轨道 ID，并将 publishCustomAudioTrack 设置为 true。
  3. 调用 pushExternalAudioFrame，并将 trackId 设置为步骤 2 中的音频轨道 ID，即可在频道中发布对应的自定义音频源。

注： 该方法需要在加入频道前调用。

参数

参数名描述
trackType

自定义音频轨道的类型，详见 AudioTrackType。

注： 如果该参数设置为 AUDIO_TRACK_DIRECT，则在调用 joinChannel 加入频道时，必须将 ChannelMediaOptions 中的 publishMicrophoneTrack 设置为 false，否则加入频道会失败并返回错误码 -2。

config

自定义音频轨道的配置，详见 AudioTrackConfig。

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

返回值

  • 方法调用成功，返回音频轨道 ID，作为该音频轨道的唯一标识。
  • 方法调用失败，返回 0xffffffff。

所属接口类

destroyCustomAudioTrack

销毁指定的音频轨道。

Java
public abstract int destroyCustomAudioTrack(int trackId);

参数

参数名描述
trackId

在 createCustomAudioTrack 中返回的自定义音频轨道 ID。

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

返回值

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

所属接口类

enableCustomAudioLocalPlayback

设置是否启用外部音频源的本地播放。

Java
public abstract int enableCustomAudioLocalPlayback(int trackId, boolean enabled);

你可以调用 adjustCustomAudioPlayoutVolume 方法调整自定义音频轨道的本地播放音量。

注： 请确保在调用该方法前，已通过调用 createCustomAudioTrack 创建自定义音频轨道。

参数

参数名描述
trackId

音频轨道 ID，需设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

enabled

是否播放外部音频源：

  • true：播放外部音频源。
  • false：（默认）不播放外部音频源。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

pullPlaybackAudioFrame [1/2]

拉取远端混音后的音频数据用于播放。

Java
public abstract int pullPlaybackAudioFrame(byte[] data, int lengthInByte);

调用该方法前，请先调用 setExternalAudioSink 并设置 enabled 为 true，以启用外部音频渲染。

注： pullPlaybackAudioFrame 方法和 onPlaybackAudioFrame 回调都可用于获取远端混音后的音频数据。启用外部音频渲染（调用 setExternalAudioSink）后，无法再通过 onPlaybackAudioFrame 回调获取数据。请根据实际业务需求选择使用 pullPlaybackAudioFrame 方法或 onPlaybackAudioFrame 回调。两者区别如下：

  • 调用 pullPlaybackAudioFrame 方法后，App 会自动从 SDK 拉取音频数据。通过设置音频数据参数，SDK 会调整帧缓冲区以帮助 App 处理延迟，有效避免音频播放抖动。
  • 注册 onPlaybackAudioFrame 回调后，SDK 会通过回调将音频数据发送给 App。若处理音频帧存在延迟，可能会导致音频抖动。

该方法仅用于获取远端混音后的音频数据。如需获取采集、播放等其他音频处理阶段的数据，可通过调用 registerAudioFrameObserver 注册相应的回调。

调用时机

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

参数

参数名描述
data

输出参数，要拉取的远端音频数据。

lengthInByte

数据长度（字节）。该值与音频时长，以及在 setExternalAudioSink 中设置的 sampleRate 和 channels 参数有关。计算公式为：lengthInByte = sampleRate / 1000 × 2 × channels × 音频时长（毫秒）。

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

返回值

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

所属接口类

pullPlaybackAudioFrame [2/2]

拉取远端音频数据。

Java
public abstract int pullPlaybackAudioFrame(ByteBuffer data, int lengthInByte);

在调用该方法之前，你需要调用 setExternalAudioSink 方法，并将 enabled 设置为 true，以启用并设置外部音频播放。调用该方法成功后，App 会拉取解码并混音后的音频数据用于播放。

注：

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

  • 该方法与 onPlaybackAudioFrame 回调的区别如下：

    • onPlaybackAudioFrame：SDK 通过该回调将音频数据发送给 App。若 App 处理音频帧存在延迟，可能会导致音频抖动。
    • pullPlaybackAudioFrame：App 主动拉取远端音频数据。设置音频参数后，SDK 会调整帧缓冲区，避免外部音频播放中因抖动引发的问题。

参数

参数名描述
data

用于接收拉取的远端音频数据。详见 ByteBuffer。

lengthInByte

远端音频数据的字节长度。该值与音频时长，以及在 setExternalAudioSink 中设置的 sampleRate 和 channels 参数有关。

lengthInByte = sampleRate / 1000 × 2 × channels × 音频时长（毫秒）。

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

返回值

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

所属接口类

pushExternalAudioFrame

将外部音频帧推送到 SDK。

Java
public abstract int pushExternalAudioFrame(byte[] data, long timestamp, int sampleRate, int channels, Constants.BytesPerSample bytesPerSample, int trackId);

调用该方法前，请按以下顺序操作：

  1. 调用 createCustomAudioTrack 创建自定义音频轨道，并获取音频轨道 ID。
  2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 true。

调用时机

在调用该方法推送外部音频数据前，请先完成以下步骤：

  1. 调用 createCustomAudioTrack 创建自定义音频轨道并获取音频轨道 ID。
  2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 true。

参数

参数名描述
data

外部音频数据。

timestamp

外部音频帧的时间戳（毫秒）。该参数为必填项，可用于还原采集音频帧的顺序，或在涉及视频的场景中（包括使用外部视频源的场景）实现音视频同步。

sampleRate

外部音频源的采样率（Hz），可设置为以下值：

  • 8000
  • 16000
  • 32000
  • 44100
  • 48000。
channels

外部音频源的声道数，可设置为以下值：

  • 1：单声道。
  • 2：立体声。
bytesPerSample

每个采样点的字节数。

trackId

音频轨道 ID。请设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

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

返回值

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

所属接口类

setExternalAudioSink

设置外部音频渲染器。

Java
public abstract int setExternalAudioSink(boolean enabled, int sampleRate, int channels);

启用外部音频渲染器后，你可以调用 pullPlaybackAudioFrame 拉取远端音频帧，应用可以处理远端音频，并使用你希望的音效进行播放。

注： 启用外部音频渲染器后，应用将无法从 onPlaybackAudioFrame 回调中获取任何音频数据。

适用场景

适用于需要使用外部音频数据进行播放的场景。

调用时机

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

参数

参数名描述
enabled

是否启用外部音频渲染器：

  • true：启用外部音频渲染器。
  • false：（默认）关闭外部音频渲染器。
sampleRate

外部音频渲染器的采样率（Hz），可设置为以下值：

  • 16000
  • 32000
  • 44100
  • 48000
channels

外部音频渲染器的声道数：

  • 1：单声道。
  • 2：立体声。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setExternalAudioSource [1/2]

设置外部音频源。

Java
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);

废弃

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

在调用 joinChannel 和 startPreview 之前调用该方法。

参数

参数名描述
enabled

是否启用外部音频源：

  • true：启用外部音频源。
  • false：（默认）禁用外部音频源。
sampleRate

外部音频源的采样率（Hz），可设置为以下值：

  • 8000
  • 16000
  • 32000
  • 44100
  • 48000。
channels

外部音频源的声道数：

  • 1：单声道。
  • 2：立体声。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setExternalAudioSource [2/2]

设置外部音频源参数。

Java
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels, boolean localPlayback, boolean publish);

废弃

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

调用时机

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

参数

参数名描述
enabled

是否启用外部音频源：

  • true：启用外部音频源。
  • false：（默认）不启用外部音频源。
sampleRate

外部音频源的采样率（Hz），可设置为以下值：

  • 8000
  • 16000
  • 32000
  • 44100
  • 48000。
channels

外部音频源的声道数，可设置为以下值：

  • 1：单声道。
  • 2：立体声。
localPlayback

是否播放外部音频源：

  • true：播放外部音频源。
  • false：（默认）不播放外部音频源。
publish

是否向远端用户发布音频：

  • true：（默认）发布音频到远端用户。
  • false：不发布音频到远端用户。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利