# 音乐文件播放 (/zh-CN/api-reference/rtc/macos/play/audio-mixing)

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

<a id="toc_audio_mixing"></a>

<a id="api_irtcengine_adjustaudiomixingplayoutvolume"></a>

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

## adjustAudioMixingPlayoutVolume: [#adjustaudiomixingplayoutvolume]

调整本地播放的混音音量。

<a id="api_irtcengine_adjustaudiomixingplayoutvolume__prototype"></a>

```objc
- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume NS_SWIFT_NAME(adjustAudioMixingPlayoutVolume(_:));
```

<a id="api_irtcengine_adjustaudiomixingplayoutvolume__detailed_desc"></a>

你需要在调用 `startAudioMixing` 方法，并收到 `audioMixingStateChanged` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用该方法。

<a id="api_irtcengine_adjustaudiomixingplayoutvolume__timing"></a>

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

你需要在调用 `startAudioMixing` 方法，并收到 `audioMixingStateChanged` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用该方法。

<a id="api_irtcengine_adjustaudiomixingplayoutvolume__parameters"></a>

### 参数 [#参数]

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

本地播放的混音音量。取值范围为 0 到 100，默认值为 100，表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_adjustaudiomixingplayoutvolume__return_values"></a>

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

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_adjustaudiomixingpublishvolume"></a>

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

## adjustAudioMixingPublishVolume: [#adjustaudiomixingpublishvolume]

调节用于发布的混音音量。

<a id="api_irtcengine_adjustaudiomixingpublishvolume__prototype"></a>

```objc
- (int)adjustAudioMixingPublishVolume:(NSInteger)volume NS_SWIFT_NAME(adjustAudioMixingPublishVolume(_:));
```

<a id="api_irtcengine_adjustaudiomixingpublishvolume__detailed_desc"></a>

你可以调用该方法调节用于发布（发送给其他用户）的混音音量。

<a id="api_irtcengine_adjustaudiomixingpublishvolume__timing"></a>

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

在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged:reasonCode:` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用。

<a id="api_irtcengine_adjustaudiomixingpublishvolume__parameters"></a>

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

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

用于本地播放的混音音量。取值范围为 0 到 100，默认值为 100，表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_adjustaudiomixingpublishvolume__return_values"></a>

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

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_adjustaudiomixingvolume"></a>

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

## adjustAudioMixingVolume: [#adjustaudiomixingvolume]

调节混音时的音量。

<a id="api_irtcengine_adjustaudiomixingvolume__prototype"></a>

```objc
- (int)adjustAudioMixingVolume:(NSInteger)volume NS_SWIFT_NAME(adjustAudioMixingVolume(_:));
```

<a id="api_irtcengine_adjustaudiomixingvolume__detailed_desc"></a>

你可以通过该方法在本地客户端和远端客户端调节混音音量。

:::note
注： 该方法不会影响通过 [playEffect\:filePath\:loopCount\:pitch\:pan\:gain\:publish\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengine_playeffect3) 方法设置的音效文件的音量。
:::

<a id="api_irtcengine_adjustaudiomixingvolume__timing"></a>

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

请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法之后调用该方法。

<a id="api_irtcengine_adjustaudiomixingvolume__parameters"></a>

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

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

混音音量。取值范围为 0 到 100。默认值为 100，表示原始音量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_adjustaudiomixingvolume__return_values"></a>

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

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getaudiomixingcurrentposition"></a>

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

## getAudioMixingCurrentPosition [#getaudiomixingcurrentposition]

获取当前混音的播放位置（毫秒）。

<a id="api_irtcengine_getaudiomixingcurrentposition__prototype"></a>

```objc
- (int)getAudioMixingCurrentPosition NS_SWIFT_NAME(getAudioMixingCurrentPosition());
```

<a id="api_irtcengine_getaudiomixingcurrentposition__detailed_desc"></a>

获取音频混音的播放位置（毫秒）。

:::note
注：

- 你需要在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 `audioMixingStateChanged` 回调（`AgoraAudioMixingStateTypePlaying`）后调用此方法。
- 如果你需要多次调用 [getAudioMixingCurrentPosition](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_getaudiomixingcurrentposition)，请确保两次调用之间的时间间隔大于 500 毫秒。
:::

<a id="api_irtcengine_getaudiomixingcurrentposition__return_values"></a>

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

- ≥ 0：方法调用成功，返回当前混音的播放位置（毫秒）。返回 0 表示当前音乐文件尚未开始播放。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getaudiomixingduration"></a>

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

## getAudioMixingDuration [#getaudiomixingduration]

获取音频文件的混音时长（毫秒）。

<a id="api_irtcengine_getaudiomixingduration__prototype"></a>

```objc
- (int)getAudioMixingDuration NS_SWIFT_NAME(getAudioMixingDuration());
```

<a id="api_irtcengine_getaudiomixingduration__detailed_desc"></a>

<a id="api_irtcengine_getaudiomixingduration__timing"></a>

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

在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用该方法。

<a id="api_irtcengine_getaudiomixingduration__return_values"></a>

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

- ≥ 0：方法调用成功，返回音频混音的时长（毫秒）。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getaudiomixingplayoutvolume"></a>

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

## getAudioMixingPlayoutVolume [#getaudiomixingplayoutvolume]

获取本地播放的混音音量。

<a id="api_irtcengine_getaudiomixingplayoutvolume__prototype"></a>

```objc
- (int)getAudioMixingPlayoutVolume NS_SWIFT_NAME(getAudioMixingPlayoutVolume());
```

<a id="api_irtcengine_getaudiomixingplayoutvolume__detailed_desc"></a>

你可以调用此方法获取混音音频文件的本地播放音量，有助于排查与音量相关的问题。

<a id="api_irtcengine_getaudiomixingplayoutvolume__timing"></a>

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

请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用此方法。

<a id="api_irtcengine_getaudiomixingplayoutvolume__return_values"></a>

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

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getaudiomixingpublishvolume"></a>

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

## getAudioMixingPublishVolume [#getaudiomixingpublishvolume]

获取用于发布的混音音量。

<a id="api_irtcengine_getaudiomixingpublishvolume__prototype"></a>

```objc
- (int)getAudioMixingPublishVolume NS_SWIFT_NAME(getAudioMixingPublishVolume());
```

<a id="api_irtcengine_getaudiomixingpublishvolume__detailed_desc"></a>

该方法有助于你排查与音频音量相关的问题。

:::note
注： 你需要在调用 `startAudioMixing` 并收到 `audioMixingStateChanged` 回调（`AgoraAudioMixingStateTypePlaying`）后调用此方法。
:::

<a id="api_irtcengine_getaudiomixingpublishvolume__return_values"></a>

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

- ≥ 0：方法调用成功，返回混音音量，取值范围为 [0,100]。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getaudiotrackcount"></a>

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

## getAudioTrackCount [#getaudiotrackcount]

获取当前音乐文件的音轨索引。

<a id="api_irtcengine_getaudiotrackcount__prototype"></a>

```objc
- (int)getAudioTrackCount NS_SWIFT_NAME(getAudioTrackCount());
```

<a id="api_irtcengine_getaudiotrackcount__detailed_desc"></a>

:::note
注： 你需要在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 [rtcEngine\:audioMixingStateChanged\:reasonCode:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged) 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用此方法。
:::

<a id="api_irtcengine_getaudiotrackcount__return_values"></a>

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

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_pauseaudiomixing"></a>

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

## pauseAudioMixing [#pauseaudiomixing]

暂停播放和混音音乐文件。

<a id="api_irtcengine_pauseaudiomixing__prototype"></a>

```objc
- (int)pauseAudioMixing NS_SWIFT_NAME(pauseAudioMixing());
```

<a id="api_irtcengine_pauseaudiomixing__detailed_desc"></a>

调用 `startAudioMixing` 播放音乐文件后，你可以调用该方法暂停播放。若需停止播放，请调用 [stopAudioMixing](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_stopaudiomixing)。

<a id="api_irtcengine_pauseaudiomixing__timing"></a>

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

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

<a id="api_irtcengine_pauseaudiomixing__return_values"></a>

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

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_resumeaudiomixing"></a>

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

## resumeAudioMixing [#resumeaudiomixing]

恢复播放并混音音乐文件。

<a id="api_irtcengine_resumeaudiomixing__prototype"></a>

```objc
- (int)resumeAudioMixing NS_SWIFT_NAME(resumeAudioMixing());
```

<a id="api_irtcengine_resumeaudiomixing__detailed_desc"></a>

调用 [pauseAudioMixing](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_pauseaudiomixing) 后，你可以调用此方法恢复播放。

<a id="api_irtcengine_resumeaudiomixing__timing"></a>

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

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

<a id="api_irtcengine_resumeaudiomixing__return_values"></a>

### 返回值 [#返回值-9]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_selectaudiotrack"></a>

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

## selectAudioTrack: [#selectaudiotrack]

选择用于播放的音轨。

<a id="api_irtcengine_selectaudiotrack__prototype"></a>

```objc
- (int)selectAudioTrack:(NSInteger)index NS_SWIFT_NAME(selectAudioTrack(_:));
```

<a id="api_irtcengine_selectaudiotrack__detailed_desc"></a>

获取音频文件的音轨索引后，可以调用该方法指定任意音轨进行播放。例如，如果多音轨文件的不同音轨存储了不同语言的歌曲，可以调用该方法设置播放语言。

:::note
注：

- 支持的音频文件格式，详见[声网 RTC SDK 支持哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。
- 需要在调用 `startAudioMixing` 并收到 `audioMixingStateChanged` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用该方法。
:::

<a id="api_irtcengine_selectaudiotrack__parameters"></a>

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

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

你想要指定的音轨索引。该值应大于等于 0 且小于 [getAudioTrackCount](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_getaudiotrackcount) 返回的值。

</Parameter>
</ParameterList>

<a id="api_irtcengine_selectaudiotrack__return_values"></a>

### 返回值 [#返回值-10]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_imediaplayer_selectmultiaudiotrack"></a>

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

## selectMultiAudioTrack\:publishTrackIndex: [#selectmultiaudiotrackpublishtrackindex]

分别选择要在本地设备播放和发布到频道的音轨。

<a id="api_imediaplayer_selectmultiaudiotrack__prototype"></a>

```objc
- (int)selectMultiAudioTrack:(NSInteger)playoutTrackIndex publishTrackIndex:(NSInteger)publishTrackIndex NS_SWIFT_NAME(selectMultiAudioTrack(_:publishTrackIndex:));
```

<a id="api_imediaplayer_selectmultiaudiotrack__detailed_desc"></a>

调用该方法可分别设置要在本地设备上播放和发布到频道的音轨。在调用该方法前，需要先调用 [openWithMediaSource:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并在 [AgoraMediaSource](/zh-CN/api-reference/rtc/macos/class-mediasource) 中将 `enableMultiAudioTrack` 设置为 YES。

<a id="api_imediaplayer_selectmultiaudiotrack__scenario"></a>

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

该方法适用于例如 KTV 场景：主持人可以选择在本地播放原唱音轨，同时将伴奏音轨发布到频道。

<a id="api_imediaplayer_selectmultiaudiotrack__parameters"></a>

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

<ParameterList>
<a id="playouttrackindex"></a>
<Parameter name="playoutTrackIndex">

用于本地播放的音轨索引。你可以通过 [getStreamByIndex:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-info#api_imediaplayer_getstreaminfo) 获取该索引。

</Parameter>
<a id="publishtrackindex"></a>
<Parameter name="publishTrackIndex">

要发布到频道中的音轨索引。你可以通过 [getStreamByIndex:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-info#api_imediaplayer_getstreaminfo) 获取该索引。

</Parameter>
</ParameterList>

<a id="api_imediaplayer_selectmultiaudiotrack__return_values"></a>

### 返回值 [#返回值-11]

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

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

- [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)

<a id="api_irtcengine_setaudiomixingdualmonomode"></a>

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

## setAudioMixingDualMonoMode: [#setaudiomixingdualmonomode]

设置当前音频文件的声道模式。

<a id="api_irtcengine_setaudiomixingdualmonomode__prototype"></a>

```objc
- (int)setAudioMixingDualMonoMode:(AgoraAudioMixingDualMonoMode)mode NS_SWIFT_NAME(setAudioMixingDualMonoMode(_:));
```

<a id="api_irtcengine_setaudiomixingdualmonomode__detailed_desc"></a>

在立体声音乐文件中，左声道和右声道可以存储不同的音频数据。你可以根据需要将声道模式设置为原始模式、左声道模式、右声道模式或混合声道模式。例如，在 KTV 场景中，音乐文件的左声道存储伴奏，右声道存储原唱人声：

- 如果你只想听伴奏，可以将声道模式设置为左声道模式。
- 如果你想同时听到伴奏和原唱人声，可以将声道模式设置为混合模式。

:::note
注： 该方法仅适用于立体声音频文件。
:::

<a id="api_irtcengine_setaudiomixingdualmonomode__scenario"></a>

### 适用场景 [#适用场景-1]

在 KTV 场景中，音乐文件的左声道存储伴奏，右声道存储原唱人声。你可以根据实际需求进行设置：

- 如果你只想听到伴奏，调用该方法将声道模式设置为左声道模式。
- 如果你需要同时听到伴奏和原唱人声，调用该方法将声道模式设置为混合模式。

<a id="api_irtcengine_setaudiomixingdualmonomode__timing"></a>

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

在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged:reasonCode:`（`AgoraAudioMixingStateTypePlaying`）回调后调用该方法。

<a id="api_irtcengine_setaudiomixingdualmonomode__parameters"></a>

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

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

声道模式。详见 [AgoraAudioMixingDualMonoMode](/zh-CN/api-reference/rtc/macos/enum-audiomixingdualmonomode)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setaudiomixingdualmonomode__return_values"></a>

### 返回值 [#返回值-12]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setaudiomixingpitch"></a>

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

## setAudioMixingPitch: [#setaudiomixingpitch]

设置本地音乐文件的音调。

<a id="api_irtcengine_setaudiomixingpitch__prototype"></a>

```objc
- (int)setAudioMixingPitch:(NSInteger)pitch NS_SWIFT_NAME(setAudioMixingPitch(_:));
```

<a id="api_irtcengine_setaudiomixingpitch__detailed_desc"></a>

调用该方法可在本地音乐文件与本地人声混音时，仅调整本地音乐文件的音调。

<a id="api_irtcengine_setaudiomixingpitch__timing"></a>

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

你需要在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 `audioMixingStateChanged:reasonCode:` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用该方法。

<a id="api_irtcengine_setaudiomixingpitch__parameters"></a>

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

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

按半音阶设置本地音乐文件的音调（默认值为 0，表示保持原始音调）。取值范围为 -12 到 12，相邻两个值之间的音调差为一个半音。该参数的绝对值越大，本地音乐文件的音调越高或越低。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setaudiomixingpitch__return_values"></a>

### 返回值 [#返回值-13]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setaudiomixingplaybackspeed"></a>

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

## setAudioMixingPlaybackSpeed: [#setaudiomixingplaybackspeed]

设置当前音频文件的播放速度。

<a id="api_irtcengine_setaudiomixingplaybackspeed__prototype"></a>

```objc
- (int)setAudioMixingPlaybackSpeed:(NSInteger)speed NS_SWIFT_NAME(setAudioMixingPlaybackSpeed(_:));
```

<a id="api_irtcengine_setaudiomixingplaybackspeed__detailed_desc"></a>

请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 `audioMixingStateChanged:reasonCode:` 回调报告状态为 `AgoraAudioMixingStateTypePlaying` 后调用此方法。

<a id="api_irtcengine_setaudiomixingplaybackspeed__parameters"></a>

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

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

播放速度。声网建议设置为 50 到 400 之间的值，定义如下：

- 50：原始速度的一半。
- 100：原始速度。
- 400：原始速度的 4 倍。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setaudiomixingplaybackspeed__return_values"></a>

### 返回值 [#返回值-14]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setaudiomixingposition"></a>

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

## setAudioMixingPosition: [#setaudiomixingposition]

设置混音的播放位置。

<a id="api_irtcengine_setaudiomixingposition__prototype"></a>

```objc
- (int)setAudioMixingPosition:(NSInteger)pos NS_SWIFT_NAME(setAudioMixingPosition(_:));
```

<a id="api_irtcengine_setaudiomixingposition__detailed_desc"></a>

你可以调用该方法将音乐文件的播放位置设置为指定的起始位置。

<a id="api_irtcengine_setaudiomixingposition__timing"></a>

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

请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged:reasonCode:` 回调（状态为 `AgoraAudioMixingStateTypePlaying`）后调用该方法。

<a id="api_irtcengine_setaudiomixingposition__parameters"></a>

### 参数 [#参数-8]

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

播放位置（单位为毫秒）。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setaudiomixingposition__return_values"></a>

### 返回值 [#返回值-15]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startaudiomixing"></a>

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

## startAudioMixing\:loopback\:cycle: [#startaudiomixingloopbackcycle]

开始播放音乐文件。

<a id="api_irtcengine_startaudiomixing__prototype"></a>

```objc
- (int)startAudioMixing:(NSString *  _Nonnull)filePath
               loopback:(BOOL)loopback
                  cycle:(NSInteger)cycle NS_SWIFT_NAME(startAudioMixing(_:loopback:cycle:));
```

<a id="api_irtcengine_startaudiomixing__detailed_desc"></a>

关于该方法支持的音频文件格式，详见[声网 RTC SDK 支持哪些音频文件格式](/zh-CN/reference/faq/product/audio_format)。如果本地音乐文件不存在、SDK 不支持该文件格式，或 SDK 无法访问音乐文件的 URL，SDK 会返回 `AgoraAudioMixingReasonCanNotOpen`。

:::note
注：

- 如果你调用该方法播放短音效文件，可能会导致播放失败。声网建议使用 [playEffect\:filePath\:loopCount\:pitch\:pan\:gain\:publish\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengine_playeffect3) 方法播放此类文件。
- 如果你需要多次调用该方法，请确保两次调用之间的时间间隔大于 500 毫秒。
:::

<a id="api_irtcengine_startaudiomixing__timing"></a>

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

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

<a id="api_irtcengine_startaudiomixing__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="filepath"></a>
<Parameter name="filePath">

文件路径：

- iOS 或 macOS：音频文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。

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

是否只在本地客户端播放音乐文件：

- YES：只在本地客户端播放音乐文件，只有本地用户可以听到音乐。
- NO：将音乐文件发布到远端客户端，本地用户和远端用户都可以听到音乐。

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

音乐文件的播放次数：

- &gt; 0：播放的次数。例如，1 表示播放 1 次。
- -1：无限循环播放该音频文件。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startaudiomixing__return_values"></a>

### 返回值 [#返回值-16]

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

  - -1：发生通用错误（无明确原因）。
  - -2：参数无效。
  - -3：SDK 尚未就绪。

    - 音频模块未启用。
    - 程序未完成。
    - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 初始化失败。请重新初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startaudiomixing2"></a>

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

## startAudioMixing\:loopback\:cycle\:startPos: [#startaudiomixingloopbackcyclestartpos]

开始播放音乐文件。

<a id="api_irtcengine_startaudiomixing2__prototype"></a>

```objc
- (int)startAudioMixing:(NSString *  _Nonnull)filePath
               loopback:(BOOL)loopback
                  cycle:(NSInteger)cycle
               startPos:(NSInteger)startPos NS_SWIFT_NAME(startAudioMixing(_:loopback:cycle:startPos:));
```

<a id="api_irtcengine_startaudiomixing2__detailed_desc"></a>

关于该方法支持的音频文件格式，详见[声网 RTC SDK 支持哪些音频文件格式](/zh-CN/reference/faq/product/audio_format)。如果本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会返回 `AgoraAudioMixingReasonCanNotOpen`。

:::note
注：

- 如果你调用该方法播放短音效文件，可能会遇到播放失败的情况。声网建议使用 [playEffect\:filePath\:loopCount\:pitch\:pan\:gain\:publish\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengine_playeffect3) 方法播放此类文件。
- 如果需要多次调用该方法，确保两次调用之间的时间间隔大于 500 毫秒。
:::

<a id="api_irtcengine_startaudiomixing2__timing"></a>

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

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

<a id="api_irtcengine_startaudiomixing2__related"></a>

### 相关回调 [#相关回调]

成功调用该方法后，SDK 会触发 [rtcEngine\:audioMixingStateChanged\:reasonCode:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)（`AgoraAudioMixingStateTypePlaying`）回调。当音频混音文件播放结束时，SDK 会在本地客户端触发 [rtcEngine\:audioMixingStateChanged\:reasonCode:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)（`AgoraAudioMixingStateTypeStopped`）回调。

<a id="api_irtcengine_startaudiomixing2__parameters"></a>

### 参数 [#参数-10]

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

文件路径：

- iOS 或 macOS：音频文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。

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

是否只在本地客户端播放音乐文件：

- YES：只在本地客户端播放音乐文件，只有本地用户可以听到音乐。
- NO：将音乐文件发布到远端客户端，本地用户和远端用户都可以听到音乐。

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

音乐文件的播放次数。

- &gt; 0：播放的次数。例如，1 表示播放 1 次。
- -1：无限循环播放音频文件。

</Parameter>
<a id="startpos"></a>
<Parameter name="startPos">

音乐文件的播放起始位置（单位为毫秒）。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startaudiomixing2__return_values"></a>

### 返回值 [#返回值-17]

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

  - -1：发生通用错误（无明确原因）。
  - -2：参数无效。
  - -3：SDK 尚未就绪。

    - 音频模块未启用。
    - 程序未完整。
    - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 初始化失败。请重新初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_stopaudiomixing"></a>

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

## stopAudioMixing [#stopaudiomixing]

停止播放音乐文件。

<a id="api_irtcengine_stopaudiomixing__prototype"></a>

```objc
- (int)stopAudioMixing NS_SWIFT_NAME(stopAudioMixing());
```

<a id="api_irtcengine_stopaudiomixing__detailed_desc"></a>

调用 `startAudioMixing` 播放音乐文件后，可以调用该方法停止播放。如果只需要暂停播放，请调用 [pauseAudioMixing](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_pauseaudiomixing)。

<a id="api_irtcengine_stopaudiomixing__timing"></a>

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

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

<a id="api_irtcengine_stopaudiomixing__return_values"></a>

### 返回值 [#返回值-18]

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

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="callback_irtcengineeventhandler_onaudiomixingfinished"></a>

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

## rtcEngineLocalAudioMixingDidFinish: [#rtcenginelocalaudiomixingdidfinish]

本地音乐文件播放结束时的回调。

<a id="callback_irtcengineeventhandler_onaudiomixingfinished__prototype"></a>

```objc
- (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine NS_SWIFT_NAME(rtcEngineLocalAudioMixingDidFinish(_:)) __deprecated_msg("Use rtcEngine:audioMixingStateChanged:reasonCode: instead");
```

<a id="callback_irtcengineeventhandler_onaudiomixingfinished__detailed_desc"></a>

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

:::error[废弃]
自 v4.5.0 版本废弃，请改用 `audioMixingStateChanged`。
:::

调用 `startAudioMixing` 播放本地音乐文件后，当播放结束时会触发该回调。如果调用失败，会返回错误码 `WARN_AUDIO_MIXING_OPEN_ERROR`。

<a id="callback_irtcengineeventhandler_onaudiomixingfinished__timing"></a>

### 触发时机 [#触发时机]

调用 `startAudioMixing` 播放本地音乐文件后，当播放结束时触发。

<a id="callback_irtcengineeventhandler_onaudiomixingfinished__parameters"></a>

### 参数 [#参数-11]

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

[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象，详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。

</Parameter>
</ParameterList>

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

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onaudiomixingpositionchanged"></a>

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

## rtcEngine\:audioMixingPositionChanged: [#rtcengineaudiomixingpositionchanged]

报告音乐文件的播放进度。

<a id="callback_irtcengineeventhandler_onaudiomixingpositionchanged__prototype"></a>

```objc
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingPositionChanged:(NSInteger)position NS_SWIFT_NAME(rtcEngine(_:audioMixingPositionChanged:));
```

<a id="callback_irtcengineeventhandler_onaudiomixingpositionchanged__detailed_desc"></a>

你调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法播放音乐文件后，SDK 每两秒触发一次该回调，报告音乐文件的播放进度。

<a id="callback_irtcengineeventhandler_onaudiomixingpositionchanged__timing"></a>

### 触发时机 [#触发时机-1]

你调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法播放音乐文件后，SDK 每两秒触发一次该回调。

<a id="callback_irtcengineeventhandler_onaudiomixingpositionchanged__parameters"></a>

### 参数 [#参数-12]

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

[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 实例，详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。

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

播放进度，单位为毫秒。

</Parameter>
</ParameterList>

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

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onaudiomixingstatechanged"></a>

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

## rtcEngine\:audioMixingStateChanged\:reasonCode: [#rtcengineaudiomixingstatechangedreasoncode]

音乐文件播放状态发生变化回调。

<a id="callback_irtcengineeventhandler_onaudiomixingstatechanged__prototype"></a>

```objc
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingStateChanged:(AgoraAudioMixingStateType)state
                                                                    reasonCode:(AgoraAudioMixingReasonCode)reasonCode NS_SWIFT_NAME(rtcEngine(_:audioMixingStateChanged:reasonCode:));
```

<a id="callback_irtcengineeventhandler_onaudiomixingstatechanged__detailed_desc"></a>

该回调在音乐文件的播放状态发生变化时触发，并报告当前的状态和错误码。

<a id="callback_irtcengineeventhandler_onaudiomixingstatechanged__timing"></a>

### 触发时机 [#触发时机-2]

该回调在音乐文件的播放状态发生变化时被触发。

<a id="callback_irtcengineeventhandler_onaudiomixingstatechanged__parameters"></a>

### 参数 [#参数-13]

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

[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象，详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。

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

音乐文件的播放状态，详见 [AgoraAudioMixingStateType](/zh-CN/api-reference/rtc/macos/enum-audiomixingstatetype)。

</Parameter>
<a id="reasoncode"></a>
<Parameter name="reasonCode">

错误码，详见 [AgoraAudioMixingReasonCode](/zh-CN/api-reference/rtc/macos/enum-audiomixingreasontype)。

</Parameter>
</ParameterList>

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

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)