# 自定义音频采集和渲染 (/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_audio_custom_capturenrendering"></a>

<a id="api_irtcengine_adjustcustomaudioplayoutvolume"></a>

<a id="ariaid-title2"></a>

## adjustCustomAudioPlayoutVolume [#adjustcustomaudioplayoutvolume]

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

<a id="api_irtcengine_adjustcustomaudioplayoutvolume__prototype"></a>

```ts
abstract adjustCustomAudioPlayoutVolume(
    trackId: number,
    volume: number
  ): number;
```

<a id="api_irtcengine_adjustcustomaudioplayoutvolume__detailed_desc"></a>

调用该方法设置音频在本地播放的音量后，如果你想重新调整音量，你可以再次调用该方法。

:::note
注： 在调用该方法前，请确保你已经调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法创建自定义音频采集轨道。
:::

<a id="api_irtcengine_adjustcustomaudioplayoutvolume__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="trackid"></a>
<Parameter name="trackId">

音频轨道 ID。将该参数设置为调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法返回的自定义音频轨道 ID。

</Parameter>
<a id="volume"></a>
<Parameter name="volume">

自定义采集音频的播放音量，取值范围为 [0,100]。0 表示静音，100 表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_adjustcustomaudioplayoutvolume__return_values"></a>

### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_adjustcustomaudiopublishvolume"></a>

<a id="ariaid-title3"></a>

## adjustCustomAudioPublishVolume [#adjustcustomaudiopublishvolume]

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

<a id="api_irtcengine_adjustcustomaudiopublishvolume__prototype"></a>

```ts
abstract adjustCustomAudioPublishVolume(
    trackId: number,
    volume: number
  ): number;
```

<a id="api_irtcengine_adjustcustomaudiopublishvolume__detailed_desc"></a>

调用该方法设置音频在远端播放的音量后，如果你想重新调整音量，你可以再次调用该方法。

:::note
注： 在调用该方法前，请确保你已经调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法创建自定义音频采集轨道。
:::

<a id="api_irtcengine_adjustcustomaudiopublishvolume__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="trackid-1"></a>
<Parameter name="trackId">

音频轨道 ID。将该参数设置为调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法返回的自定义音频轨道 ID。

</Parameter>
<a id="volume-1"></a>
<Parameter name="volume">

自定义采集音频的播放音量，取值范围为 [0,100]。0 表示静音，100 表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_adjustcustomaudiopublishvolume__return_values"></a>

### 返回值 [#返回值-1]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)

<a id="api_imediaengine_createcustomaudiotrack"></a>

<a id="ariaid-title4"></a>

## createCustomAudioTrack [#createcustomaudiotrack]

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

<a id="api_imediaengine_createcustomaudiotrack__prototype"></a>

```ts
abstract createCustomAudioTrack(
    trackType: AudioTrackType,
    config: AudioTrackConfig
  ): number;
```

<a id="api_imediaengine_createcustomaudiotrack__detailed_desc"></a>

如需在频道中发布自定义采集音频，可参考以下步骤：

1. 调用该方法创建音频轨道并获得音频轨道 ID。
2. 调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道时，将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `publishCustomAudioTrackId` 设置为你想要发布的音频轨道 ID，并将 `publishCustomAudioTrack` 设置为 true。
3. 调用 [pushAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 将 `trackId` 指定为步骤 2 中指定的音频轨道 ID，即可实现在频道内发布对应的自定义音频源。

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

<a id="api_imediaengine_createcustomaudiotrack__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="tracktype"></a>
<Parameter name="trackType">

自定义音频轨道类型。详见 [AudioTrackType](/zh-CN/api-reference/rtc/electron/enum-audiotracktype)。

:::note
注： 如指定 `AudioTrackDirect`，则必须在调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道时，将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `publishMicrophoneTrack` 设为 false，否则加入频道失败并返回错误码 -2。
:::

</Parameter>
<a id="config"></a>
<Parameter name="config">

自定义音频轨道配置。详见 [AudioTrackConfig](/zh-CN/api-reference/rtc/electron/class-audiotrackconfig)。

</Parameter>
</ParameterList>

<a id="api_imediaengine_createcustomaudiotrack__return_values"></a>

### 返回值 [#返回值-2]

- 方法调用成功，返回音频轨道 ID 作为该音频轨道的唯一标识。
- 方法调用失败，返回 0xffffffff。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [IMediaEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaengine)

<a id="api_imediaengine_destroycustomaudiotrack"></a>

<a id="ariaid-title5"></a>

## destroyCustomAudioTrack [#destroycustomaudiotrack]

销毁指定的音频轨道。

<a id="api_imediaengine_destroycustomaudiotrack__prototype"></a>

```ts
abstract destroyCustomAudioTrack(trackId: number): number;
```

<a id="api_imediaengine_destroycustomaudiotrack__detailed_desc"></a>

<a id="api_imediaengine_destroycustomaudiotrack__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="trackid-2"></a>
<Parameter name="trackId">

调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法返回的自定义音频轨道 ID。

</Parameter>
</ParameterList>

<a id="api_imediaengine_destroycustomaudiotrack__return_values"></a>

### 返回值 [#返回值-3]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [IMediaEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaengine)

<a id="api_irtcengine_enablecustomaudiolocalplayback"></a>

<a id="ariaid-title6"></a>

## enableCustomAudioLocalPlayback [#enablecustomaudiolocalplayback]

设置是否在本地播放外部音频源。

<a id="api_irtcengine_enablecustomaudiolocalplayback__prototype"></a>

```ts
abstract enableCustomAudioLocalPlayback(
    trackId: number,
    enabled: boolean
  ): number;
```

<a id="api_irtcengine_enablecustomaudiolocalplayback__detailed_desc"></a>

调用该方法设置在本地播放外部采集的音频源后，如需停止本地播放，可以再次调用该方法并设置 `enabled` 为 false。
你可以调用 [adjustCustomAudioPlayoutVolume](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_irtcengine_adjustcustomaudioplayoutvolume) 调节自定义音频采集轨道在本地播放的音量。

:::note
注： 在调用该方法前，请确保你已经调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法创建自定义音频采集轨道。
:::

<a id="api_irtcengine_enablecustomaudiolocalplayback__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="trackid-3"></a>
<Parameter name="trackId">

音频轨道 ID。将该参数设置为调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 方法返回的自定义音频轨道 ID。

</Parameter>
<a id="enabled"></a>
<Parameter name="enabled">

是否在本地播放外部音频源：

- true：在本地播放。
- false：（默认）不在本地播放。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enablecustomaudiolocalplayback__return_values"></a>

### 返回值 [#返回值-4]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-4]

- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)

<a id="api_imediaengine_pullaudioframe"></a>

<a id="ariaid-title7"></a>

## pullAudioFrame [#pullaudioframe]

拉取远端音频数据。

<a id="api_imediaengine_pullaudioframe__prototype"></a>

```ts
abstract pullAudioFrame(): AudioFrame;
```

<a id="api_imediaengine_pullaudioframe__detailed_desc"></a>

调用该方法后，App 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

:::note
注： 该方法和 [onPlaybackAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 回调均可用于获取远端混音后的音频播放数据。在调用 [setExternalAudioSink](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_setexternalaudiosink) 开启外部音频渲染后，App 将无法从 [onPlaybackAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 回调中获得数据。因此，请根据实际的业务需求在该方法和 [onPlaybackAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 回调之间进行选择。二者的处理机制不同，具体区别如下：

- 调用该方法后，App 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 App 处理延时，从而有效避免音频播放抖动。
- 注册 [onPlaybackAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 回调后，SDK 通过该回调将音频数据传输给 App。App 在处理音频帧的延迟时，可能会导致音频播放抖动。

该方法仅用于拉取远端混音后的音频播放数据，如需获取采集的原始音频数据、混音前每条拉流单独的原始音频播放数据等，可以通过调用 [registerAudioFrameObserver](/zh-CN/api-reference/rtc/electron/audio/audio-raw#api_imediaengine_registeraudioframeobserver) 注册相应的回调。
:::

<a id="api_imediaengine_pullaudioframe__timing"></a>

### 调用时机 [#调用时机]

该方法需要在加入频道后调用。
调用该方法前，你需要调用 `setExternalAudioSink(enabled: true)` 开启并设置外部渲染。

<a id="api_imediaengine_pullaudioframe__return_values"></a>

### 返回值 [#返回值-5]

- 方法调用成功，返回一个 [AudioFrame](/zh-CN/api-reference/rtc/electron/class-audioframe) 对象。
- 方法调用失败，返回错误码。

### 所属接口类 [#所属接口类-5]

- [IMediaEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaengine)

<a id="api_imediaengine_pushaudioframe"></a>

<a id="ariaid-title8"></a>

## pushAudioFrame [#pushaudioframe]

推送外部音频帧。

<a id="api_imediaengine_pushaudioframe__prototype"></a>

```ts
abstract pushAudioFrame(frame: AudioFrame, trackId?: number): number;
```

<a id="api_imediaengine_pushaudioframe__detailed_desc"></a>

调用该方法通过音频轨道推送外部音频帧。

<a id="api_imediaengine_pushaudioframe__timing"></a>

### 调用时机 [#调用时机-1]

调用该方法推送外部音频数据前，请先进行以下操作：

1. 调用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 创建音频轨道并获得音频轨道 ID。
2. 调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道时，将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `publishCustomAudioTrackId` 设置为你想要发布的音频轨道 ID，并将 `publishCustomAudioTrack` 设置为 true。

<a id="api_imediaengine_pushaudioframe__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="frame"></a>
<Parameter name="frame">

外部音频帧。详见 [AudioFrame](/zh-CN/api-reference/rtc/electron/class-audioframe)。

</Parameter>
<a id="trackid-4"></a>
<Parameter name="trackId">

音频轨道 ID。如果你要发布自定义的外部音频源，则将该参数设置为你想要发布的自定义音频轨道 ID。

</Parameter>
</ParameterList>

<a id="api_imediaengine_pushaudioframe__return_values"></a>

### 返回值 [#返回值-6]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-6]

- [IMediaEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaengine)

<a id="api_imediaengine_setexternalaudiosink"></a>

<a id="ariaid-title9"></a>

## setExternalAudioSink [#setexternalaudiosink]

设置外部音频渲染。

<a id="api_imediaengine_setexternalaudiosink__prototype"></a>

```ts
abstract setExternalAudioSink(
    enabled: boolean,
    sampleRate: number,
    channels: number
  ): number;
```

<a id="api_imediaengine_setexternalaudiosink__detailed_desc"></a>

调用该方法开启外部音频渲染后，你可以调用 [pullAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_pullaudioframe) 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

:::note
注： 调用该方法开启外部音频渲染后，App 将无法从 [onPlaybackAudioFrame](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 回调中获得数据。
:::

<a id="api_imediaengine_setexternalaudiosink__scenario"></a>

### 适用场景 [#适用场景]

该方法适用于需要自行渲染音频的场景。

<a id="api_imediaengine_setexternalaudiosink__timing"></a>

### 调用时机 [#调用时机-2]

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

<a id="api_imediaengine_setexternalaudiosink__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="enabled-1"></a>
<Parameter name="enabled">

设置是否开启外部音频渲染：

- true：开启外部音频渲染。
- false：（默认）关闭外部音频渲染。

</Parameter>
<a id="samplerate"></a>
<Parameter name="sampleRate">

外部音频渲染的采样率 (Hz)，可设置为 16000，32000，44100 或 48000。

</Parameter>
<a id="channels"></a>
<Parameter name="channels">

外部音频渲染的声道数:

- 1: 单声道
- 2: 双声道

</Parameter>
</ParameterList>

<a id="api_imediaengine_setexternalaudiosink__return_values"></a>

### 返回值 [#返回值-7]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-7]

- [IMediaEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaengine)

<a id="api_imediaengine_setexternalaudiosource2"></a>

<a id="ariaid-title10"></a>

## setExternalAudioSource [#setexternalaudiosource]

设置外部音频采集参数。

<a id="api_imediaengine_setexternalaudiosource2__prototype"></a>

```ts
abstract setExternalAudioSource(
    enabled: boolean,
    sampleRate: number,
    channels: number,
    localPlayback?: boolean,
    publish?: boolean
  ): number;
```

<a id="api_imediaengine_setexternalaudiosource2__detailed_desc"></a>

<a id="废弃"></a>

:::error[废弃]
弃用： 该方法已废弃，请改用 [createCustomAudioTrack](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack)。
:::

<a id="api_imediaengine_setexternalaudiosource2__timing"></a>

### 调用时机 [#调用时机-3]

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

<a id="api_imediaengine_setexternalaudiosource2__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="enabled-2"></a>
<Parameter name="enabled">

是否开启使用外部音频源的功能：

- true：开启外部音频源。
- false：（默认）关闭外部音频源。

</Parameter>
<a id="samplerate-1"></a>
<Parameter name="sampleRate">

外部音频源的采样率 (Hz)，可设置为 `8000`，`16000`，`32000`，`44100` 或 `48000`。

</Parameter>
<a id="channels-1"></a>
<Parameter name="channels">

外部音频源的声道数，可设置为 `1`（单声道）或 `2`（双声道）。

</Parameter>
<a id="localplayback"></a>
<Parameter name="localPlayback">

是否在本地播放外部音频源：

- true：在本地播放。
- false：（默认）不在本地播放。

</Parameter>
<a id="publish"></a>
<Parameter name="publish">

是否将音频发布到远端：

- true：（默认）发布到远端。
- false：不发布到远端。

</Parameter>
</ParameterList>

<a id="api_imediaengine_setexternalaudiosource2__return_values"></a>

### 返回值 [#返回值-8]

- 0：方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-8]

- [IMediaEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaengine)