# 自定义音频采集和渲染 (/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## adjustCustomAudioPlayoutVolume\:volume: [#adjustcustomaudioplayoutvolumevolume] 调节本地播放的自定义音频轨道的音量。 ```objc - (int)adjustCustomAudioPlayoutVolume:(NSInteger)trackId volume:(NSInteger)volume NS_SWIFT_NAME(adjustCustomAudioPlayoutVolume(_:volume:)); ``` 如果你想更改本地播放的音频音量,需要再次调用该方法。 :::note 注: 请确保在调用该方法前已调用 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 创建自定义音频轨道。 ::: ### 参数 [#参数] 音频轨道 ID。请设置为 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 返回的自定义音频轨道 ID。 音频源的音量。取值范围为 0 到 100。 - 0:静音。 - 100:原始音量。 ### 返回值 [#返回值] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## adjustCustomAudioPublishVolume\:volume: [#adjustcustomaudiopublishvolumevolume] 调节远端播放的自定义音频轨道的音量。 ```objc - (int)adjustCustomAudioPublishVolume:(NSInteger)trackId volume:(NSInteger)volume NS_SWIFT_NAME(adjustCustomAudioPublishVolume(_:volume:)); ``` 如果你想更改远端播放的音频音量,需要再次调用此方法。 :::note 注: 请确保在调用此方法前已调用 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 方法创建自定义音频轨道。 ::: ### 参数 [#参数-1] 音频轨道 ID。请设置为 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 方法返回的自定义音频轨道 ID。 音频源的音量。取值范围为 0 到 100。 - 0:静音。 - 100:原始音量。 ### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## createCustomAudioTrack\:config: [#createcustomaudiotrackconfig] 创建一个自定义音频轨道。 ```objc - (int)createCustomAudioTrack:(AgoraAudioTrackType)trackType config:(AgoraAudioTrackConfig* _Nonnull)config; ``` 要发布自定义音频源,请按照以下步骤操作: 1. 调用该方法创建一个自定义音频轨道并获取音频轨道 ID。 2. 调用 `joinChannelByToken` 加入频道。在 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中,将 `publishCustomAudioTrackId` 设置为你想要发布的音频轨道 ID,并将 `publishCustomAudioTrack` 设置为 YES。 3. 调用 `pushExternalAudioFrameRawData`,并将 `trackId` 设置为第 2 步中设置的音频轨道 ID,即可在频道中发布相应的自定义音频源。 :::note 注: 请在加入频道前调用此方法。 ::: ### 参数 [#参数-2] 自定义音频轨道的类型,详见 [AgoraAudioTrackType](/zh-CN/api-reference/rtc/macos/enum-audiotracktype)。 - 如果该参数设置为 `AgoraAudioTrackTypeDirect`,你必须在调用 `joinChannelByToken` 加入频道时,将 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的 `publishMicrophoneTrack` 设置为 NO,否则加入频道会失败并返回错误码 -2。 自定义音频轨道的配置,详见 [AgoraAudioTrackConfig](/zh-CN/api-reference/rtc/macos/class-audiotrackconfig)。 ### 返回值 [#返回值-2] - 方法调用成功,返回音频轨道 ID,作为该音频轨道的唯一标识符。 - 方法调用失败,返回 0xffffffff。 ### 所属接口类 [#所属接口类-2] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## destroyCustomAudioTrack: [#destroycustomaudiotrack] 销毁指定的音频轨道。 ```objc - (int)destroyCustomAudioTrack:(NSInteger)trackId; ``` ### 参数 [#参数-3] 调用 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 时返回的自定义音频轨道 ID。 ### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## enableCustomAudioLocalPlayback\:enabled: [#enablecustomaudiolocalplaybackenabled] 设置是否启用外部音频源的本地播放。 ```objc - (int)enableCustomAudioLocalPlayback:(NSInteger)trackId enabled:(BOOL)enabled NS_SWIFT_NAME(enableCustomAudioLocalPlayback(_:enabled:)); ``` 调用该方法启用外部音频源的本地播放后,如需停止本地播放,可再次调用该方法并将 `enabled` 设置为 NO。你可以调用 [adjustCustomAudioPlayoutVolume\:volume:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_adjustcustomaudioplayoutvolume) 方法调整自定义音频轨道的本地播放音量。 :::note 注: 请确保在调用该方法前已通过 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 方法创建自定义音频轨道。 ::: ### 参数 [#参数-4] 音频轨道 ID。该参数需设置为 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 方法返回的自定义音频轨道 ID。 是否播放外部音频源: - YES:播放外部音频源。 - NO:(默认)不播放外部音频源。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-4] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## pullPlaybackAudioFrameRawData\:lengthInByte: [#pullplaybackaudioframerawdatalengthinbyte] 拉取远端音频数据。 ```objc - (BOOL)pullPlaybackAudioFrameRawData:(void * _Nonnull)data lengthInByte:(NSUInteger)lengthInByte NS_SWIFT_NAME(pullPlaybackAudioFrameRawData(_:lengthInByte:)); ``` 调用该方法成功后,你可以拉取解码并混音后的远端音频数据用于播放。调用该方法前,请先调用 [enableExternalAudioSink\:sampleRate\:channels:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_setexternalaudiosink)(`enabled: YES`)以开启并设置外部音频渲染。 :::note 注: [pullPlaybackAudioFrameRawData\:lengthInByte:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pullaudioframe) 方法和 `onPlaybackAudioFrame:` 回调都可用于获取远端混音后的音频数据。调用 [enableExternalAudioSink\:sampleRate\:channels:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_setexternalaudiosink) 开启外部音频渲染后,将无法再通过 `onPlaybackAudioFrame:` 回调获取数据。请根据实际业务需求选择使用该方法或 `onPlaybackAudioFrame:` 回调。两者的具体区别如下: - 调用 [pullPlaybackAudioFrameRawData\:lengthInByte:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pullaudioframe) 方法后,你会自动从 SDK 拉取音频数据。通过设置音频数据参数,SDK 会调整帧缓冲区以帮助你处理延迟,有效避免音频播放卡顿。 - 注册 `onPlaybackAudioFrame:` 回调后,SDK 会通过回调将音频数据发送给你。若处理音频帧存在延迟,可能会导致音频卡顿。 该方法仅用于获取远端混音后的音频数据。如需获取采集、播放等其他音频处理阶段的数据,可通过调用 [setAudioFrameDelegate:](/zh-CN/api-reference/rtc/macos/audio/audio-raw#api_irtcengine_registeraudioframeobserver) 注册相应的回调。 ::: ### 调用时机 [#调用时机] 在加入频道后调用该方法。 ### 参数 [#参数-5] 输出参数,要拉取的远端音频数据。数据类型为 `byte[]`。 数据长度(字节)。该参数的值与音频时长,以及在 [enableExternalAudioSink\:sampleRate\:channels:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_setexternalaudiosink) 中设置的 `sampleRate` 和 `channels` 参数有关。`lengthInByte` = `sampleRate` / 1000 × 2 × `channels` × 音频时长(毫秒)。 ### 返回值 [#返回值-5] - YES:调用成功。 - NO:调用失败。 ### 所属接口类 [#所属接口类-5] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## pullPlaybackAudioFrameSampleBufferByLengthInByte: [#pullplaybackaudioframesamplebufferbylengthinbyte] 拉取 `SampleBuffer` 格式的远端音频数据。 ```objc - (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte NS_SWIFT_NAME(pullPlaybackAudioFrameSampleBufferBy(lengthInByte:)); ``` 调用该方法后,你可以拉取解码并混音后的音频数据用于播放。 ### 参数 [#参数-6] 数据长度(字节)。该参数的值与你设置的音频时长、`sampleRate` 和 `channels` 参数有关。`lengthInByte = sampleRate / 1000 × 2 × channels × 音频时长(毫秒)`。 ### 返回值 [#返回值-6] 方法调用成功,返回 `CMSampleBufferRef` 对象;失败时返回 nil。 ### 所属接口类 [#所属接口类-6] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## pushExternalAudioFrameRawData\:samples\:sampleRate\:channels\:trackId\:timestamp: [#pushexternalaudioframerawdatasamplessampleratechannelstrackidtimestamp] 将外部音频帧推送到 SDK。 ```objc - (int)pushExternalAudioFrameRawData:(void* _Nonnull)data samples:(NSInteger)samples sampleRate:(NSInteger)sampleRate channels:(NSInteger)channels trackId:(NSInteger)trackId timestamp:(NSTimeInterval)timestamp NS_SWIFT_NAME(pushExternalAudioFrameRawData(_:samples:sampleRate:channels:trackId:timestamp:)); ``` 你可以调用该方法通过音频轨道向 SDK 推送外部音频帧。 调用该方法前,请先完成以下操作: 1. 调用 `createCustomAudioTrack` 创建自定义音频轨道,并获取音频轨道 ID。 2. 调用 `joinChannelByToken` 加入频道。在 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中,将 `publishCustomAudioTrackId` 设置为要发布的音频轨道 ID,并将 `publishCustomAudioTrack` 设置为 YES。 ### 参数 [#参数-7] 外部音频数据。 采样点数量。 外部音频源的采样率(Hz),可设置为 8000、16000、32000、44100 或 48000。 外部音频源的声道数,可设置为 1(单声道)或 2(立体声)。 音频轨道 ID,需设置为调用 `createCustomAudioTrack` 返回的自定义音频轨道 ID。 外部音频帧的时间戳(毫秒)。该参数为必填项,可用于还原采集音频帧的顺序,或在涉及视频的场景中(包括使用自定义视频源的场景)实现音视频同步。 ### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-7] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## pushExternalAudioFrameSampleBuffer: [#pushexternalaudioframesamplebuffer] 推送外部 `CMSampleBuffer` 音频帧。 ```objc - (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer NS_SWIFT_NAME(pushExternalAudioFrameSampleBuffer(_:)) __deprecated_msg("use pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId: instead."); ``` :::error[废弃] 该方法已废弃,请改用 [pushExternalAudioFrameSampleBuffer\:sampleRate\:channels\:trackId:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pushexternalaudioframesamplebuffer2)。 ::: ### 参数 [#参数-8] 音频帧的 sample buffer,类型为 `CMSampleBufferRef`。详见 `CMSampleBufferRef`。 ### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-8] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## pushExternalAudioFrameSampleBuffer\:sampleRate\:channels\:trackId: [#pushexternalaudioframesamplebuffersampleratechannelstrackid] 通过自定义音频轨道将外部 `CMSampleBuffer` 音频帧推送到频道中。 ```objc - (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer sampleRate:(NSInteger)sampleRate channels:(NSInteger)channels trackId:(NSInteger)trackId NS_SWIFT_NAME(pushExternalAudioFrameSampleBuffer(_:sampleRate:channels:trackId:)); ``` 在调用该方法推送外部音频数据之前,你需要完成以下操作: 1. 调用 `createCustomAudioTrack` 创建自定义音频轨道,并获取音频轨道 ID。 2. 调用 `joinChannelByToken` 加入频道。在 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中,将 `publishCustomAudioTrackId` 设置为你要发布的音频轨道 ID,并将 `publishCustomAudioTrack` 设置为 YES。 ### 参数 [#参数-9] 采样缓冲区。详见 `CMSampleBufferRef`。 外部音频源的采样率(Hz),可设置为 8000、16000、32000、44100 或 48000。 外部音频源的声道数,可设置为 1(单声道)或 2(立体声)。 音频轨道 ID。你需要将该参数设置为 `createCustomAudioTrack` 返回的自定义音频轨道 ID。 ### 返回值 [#返回值-9] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-9] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## enableExternalAudioSink\:sampleRate\:channels: [#enableexternalaudiosinksampleratechannels] 设置外部音频渲染。 ```objc - (void)enableExternalAudioSink:(BOOL)enabled sampleRate:(NSUInteger)sampleRate channels:(NSUInteger)channels NS_SWIFT_NAME(enableExternalAudioSink(_:sampleRate:channels:)); ``` 启用外部音频渲染后,你可以调用 [pullPlaybackAudioFrameRawData\:lengthInByte:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pullaudioframe) 方法拉取远端音频帧,应用程序可以处理远端音频,并使用期望的音效进行播放。 :::note 注: 启用外部音频渲染后,应用程序将无法从 `onPlaybackAudioFrame:` 回调中获取任何音频数据。 ::: ### 适用场景 [#适用场景] 适用于需要使用外部音频数据进行播放的场景。 ### 调用时机 [#调用时机-1] 该方法需要在加入频道前调用。 ### 参数 [#参数-10] 是否启用外部音频渲染: - YES:启用外部音频渲染。 - NO:(默认)不启用外部音频渲染。 外部音频渲染的采样率(Hz),可设置为 16000、32000、44100 或 48000。 外部音频渲染的声道数: - 1:单声道。 - 2:双声道。 ### 所属接口类 [#所属接口类-10] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## setExternalAudioSource\:sampleRate\:channels: [#setexternalaudiosourcesampleratechannels] 设置外部音频源。 ```objc - (int)setExternalAudioSource:(BOOL)enabled sampleRate:(NSInteger)sampleRate channels:(NSInteger)channels NS_SWIFT_NAME(setExternalAudioSource(_:sampleRate:channels:)) __deprecated_msg("use createCustomAudioTrack:config: instead."); ``` :::error[废弃] 该方法已废弃,请改用 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack)。 ::: 在调用 `joinChannelByToken` 和 [startPreview](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview) 之前调用该方法。 ### 参数 [#参数-11] - YES:启用外部音频源。 - NO:(默认)禁用外部音频源。 外部音频源的采样率(Hz),可设置为 8000、16000、32000、44100 或 48000。 外部音频源的声道数: - 1:单声道。 - 2:立体声。 ### 返回值 [#返回值-10] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-11] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## setExternalAudioSource\:sampleRate\:channels\:localPlayback\:publish: [#setexternalaudiosourcesampleratechannelslocalplaybackpublish] 设置外部音频源参数。 ```objc - (int)setExternalAudioSource:(BOOL)enabled sampleRate:(NSInteger)sampleRate channels:(NSInteger)channels localPlayback:(BOOL)localPlayback publish:(BOOL)publish NS_SWIFT_NAME(setExternalAudioSource(_:sampleRate:channels:localPlayback:publish:)) __deprecated_msg("use createCustomAudioTrack:config: instead."); ``` :::error[废弃] 该方法已废弃,请改用 [createCustomAudioTrack\:config:](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack)。 ::: ### 调用时机 [#调用时机-2] 请你在加入频道前调用该方法。 ### 参数 [#参数-12] 是否启用外部音频源: - YES:启用外部音频源。 - NO:(默认)不启用外部音频源。 外部音频源的采样率(Hz),可设置为 8000、16000、32000、44100 或 48000。 外部音频源的声道数,可设置为 1(单声道)或 2(立体声)。 是否播放外部音频源: - YES:播放外部音频源。 - NO:(默认)不播放外部音频源。 是否向远端用户发布音频: - YES:(默认)发布音频到远端用户。 - NO:不发布音频到远端用户。 ### 返回值 [#返回值-11] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-12] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)