# 音乐文件播放 (/zh-CN/api-reference/rtc/ios/play/audio-mixing)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## adjustAudioMixingPlayoutVolume: [#adjustaudiomixingplayoutvolume]
调整本地播放的混音音量。
```objc
- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume NS_SWIFT_NAME(adjustAudioMixingPlayoutVolume(_:));
```
你需要在调用 `startAudioMixing` 方法,并收到 `audioMixingStateChanged` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用该方法。
### 调用时机 [#调用时机]
你需要在调用 `startAudioMixing` 方法,并收到 `audioMixingStateChanged` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用该方法。
### 参数 [#参数]
本地播放的混音音量。取值范围为 0 到 100,默认值为 100,表示原始音量。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## adjustAudioMixingPublishVolume: [#adjustaudiomixingpublishvolume]
调节用于发布的混音音量。
```objc
- (int)adjustAudioMixingPublishVolume:(NSInteger)volume NS_SWIFT_NAME(adjustAudioMixingPublishVolume(_:));
```
你可以调用该方法调节用于发布(发送给其他用户)的混音音量。
### 调用时机 [#调用时机-1]
在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged:reasonCode:` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用。
### 参数 [#参数-1]
用于本地播放的混音音量。取值范围为 0 到 100,默认值为 100,表示原始音量。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## adjustAudioMixingVolume: [#adjustaudiomixingvolume]
调节混音时的音量。
```objc
- (int)adjustAudioMixingVolume:(NSInteger)volume NS_SWIFT_NAME(adjustAudioMixingVolume(_:));
```
你可以通过该方法在本地客户端和远端客户端调节混音音量。
:::note
注: 该方法不会影响通过 [playEffect\:filePath\:loopCount\:pitch\:pan\:gain\:publish\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-effect-file#api_irtcengine_playeffect3) 方法设置的音效文件的音量。
:::
### 调用时机 [#调用时机-2]
请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法之后调用该方法。
### 参数 [#参数-2]
混音音量。取值范围为 0 到 100。默认值为 100,表示原始音量。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## getAudioMixingCurrentPosition [#getaudiomixingcurrentposition]
获取当前混音的播放位置(毫秒)。
```objc
- (int)getAudioMixingCurrentPosition NS_SWIFT_NAME(getAudioMixingCurrentPosition());
```
获取音频混音的播放位置(毫秒)。
:::note
注:
- 你需要在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 `audioMixingStateChanged` 回调(`AgoraAudioMixingStateTypePlaying`)后调用此方法。
- 如果你需要多次调用 [getAudioMixingCurrentPosition](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_getaudiomixingcurrentposition),请确保两次调用之间的时间间隔大于 500 毫秒。
:::
### 返回值 [#返回值-3]
- ≥ 0:方法调用成功,返回当前混音的播放位置(毫秒)。返回 0 表示当前音乐文件尚未开始播放。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## getAudioMixingDuration [#getaudiomixingduration]
获取音频文件的混音时长(毫秒)。
```objc
- (int)getAudioMixingDuration NS_SWIFT_NAME(getAudioMixingDuration());
```
### 调用时机 [#调用时机-3]
在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用该方法。
### 返回值 [#返回值-4]
- ≥ 0:方法调用成功,返回音频混音的时长(毫秒)。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## getAudioMixingPlayoutVolume [#getaudiomixingplayoutvolume]
获取本地播放的混音音量。
```objc
- (int)getAudioMixingPlayoutVolume NS_SWIFT_NAME(getAudioMixingPlayoutVolume());
```
你可以调用此方法获取混音音频文件的本地播放音量,有助于排查与音量相关的问题。
### 调用时机 [#调用时机-4]
请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用此方法。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## getAudioMixingPublishVolume [#getaudiomixingpublishvolume]
获取用于发布的混音音量。
```objc
- (int)getAudioMixingPublishVolume NS_SWIFT_NAME(getAudioMixingPublishVolume());
```
该方法有助于你排查与音频音量相关的问题。
:::note
注: 你需要在调用 `startAudioMixing` 并收到 `audioMixingStateChanged` 回调(`AgoraAudioMixingStateTypePlaying`)后调用此方法。
:::
### 返回值 [#返回值-6]
- ≥ 0:方法调用成功,返回混音音量,取值范围为 [0,100]。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## getAudioTrackCount [#getaudiotrackcount]
获取当前音乐文件的音轨索引。
```objc
- (int)getAudioTrackCount NS_SWIFT_NAME(getAudioTrackCount());
```
:::note
注: 你需要在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 [rtcEngine\:audioMixingStateChanged\:reasonCode:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged) 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用此方法。
:::
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## pauseAudioMixing [#pauseaudiomixing]
暂停播放和混音音乐文件。
```objc
- (int)pauseAudioMixing NS_SWIFT_NAME(pauseAudioMixing());
```
调用 `startAudioMixing` 播放音乐文件后,你可以调用该方法暂停播放。若需停止播放,请调用 [stopAudioMixing](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_stopaudiomixing)。
### 调用时机 [#调用时机-5]
请在加入频道后调用该方法。
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## resumeAudioMixing [#resumeaudiomixing]
恢复播放并混音音乐文件。
```objc
- (int)resumeAudioMixing NS_SWIFT_NAME(resumeAudioMixing());
```
调用 [pauseAudioMixing](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_pauseaudiomixing) 后,你可以调用此方法恢复播放。
### 调用时机 [#调用时机-6]
请在加入频道后调用此方法。
### 返回值 [#返回值-9]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## selectAudioTrack: [#selectaudiotrack]
选择用于播放的音轨。
```objc
- (int)selectAudioTrack:(NSInteger)index NS_SWIFT_NAME(selectAudioTrack(_:));
```
获取音频文件的音轨索引后,可以调用该方法指定任意音轨进行播放。例如,如果多音轨文件的不同音轨存储了不同语言的歌曲,可以调用该方法设置播放语言。
:::note
注:
- 支持的音频文件格式,详见[声网 RTC SDK 支持哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。
- 需要在调用 `startAudioMixing` 并收到 `audioMixingStateChanged` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用该方法。
:::
### 参数 [#参数-3]
你想要指定的音轨索引。该值应大于等于 0 且小于 [getAudioTrackCount](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_getaudiotrackcount) 返回的值。
### 返回值 [#返回值-10]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## selectMultiAudioTrack\:publishTrackIndex: [#selectmultiaudiotrackpublishtrackindex]
分别选择要在本地设备播放和发布到频道的音轨。
```objc
- (int)selectMultiAudioTrack:(NSInteger)playoutTrackIndex publishTrackIndex:(NSInteger)publishTrackIndex NS_SWIFT_NAME(selectMultiAudioTrack(_:publishTrackIndex:));
```
调用该方法可分别设置要在本地设备上播放和发布到频道的音轨。在调用该方法前,需要先调用 [openWithMediaSource:](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件,并在 [AgoraMediaSource](/zh-CN/api-reference/rtc/ios/class-mediasource) 中将 `enableMultiAudioTrack` 设置为 YES。
### 适用场景 [#适用场景]
该方法适用于例如 KTV 场景:主持人可以选择在本地播放原唱音轨,同时将伴奏音轨发布到频道。
### 参数 [#参数-4]
用于本地播放的音轨索引。你可以通过 [getStreamByIndex:](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#api_imediaplayer_getstreaminfo) 获取该索引。
要发布到频道中的音轨索引。你可以通过 [getStreamByIndex:](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#api_imediaplayer_getstreaminfo) 获取该索引。
### 返回值 [#返回值-11]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-11]
- [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imediaplayer)
## setAudioMixingDualMonoMode: [#setaudiomixingdualmonomode]
设置当前音频文件的声道模式。
```objc
- (int)setAudioMixingDualMonoMode:(AgoraAudioMixingDualMonoMode)mode NS_SWIFT_NAME(setAudioMixingDualMonoMode(_:));
```
在立体声音乐文件中,左声道和右声道可以存储不同的音频数据。你可以根据需要将声道模式设置为原始模式、左声道模式、右声道模式或混合声道模式。例如,在 KTV 场景中,音乐文件的左声道存储伴奏,右声道存储原唱人声:
- 如果你只想听伴奏,可以将声道模式设置为左声道模式。
- 如果你想同时听到伴奏和原唱人声,可以将声道模式设置为混合模式。
:::note
注: 该方法仅适用于立体声音频文件。
:::
### 适用场景 [#适用场景-1]
在 KTV 场景中,音乐文件的左声道存储伴奏,右声道存储原唱人声。你可以根据实际需求进行设置:
- 如果你只想听到伴奏,调用该方法将声道模式设置为左声道模式。
- 如果你需要同时听到伴奏和原唱人声,调用该方法将声道模式设置为混合模式。
### 调用时机 [#调用时机-7]
在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged:reasonCode:`(`AgoraAudioMixingStateTypePlaying`)回调后调用该方法。
### 参数 [#参数-5]
声道模式。详见 [AgoraAudioMixingDualMonoMode](/zh-CN/api-reference/rtc/ios/enum-audiomixingdualmonomode)。
### 返回值 [#返回值-12]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-12]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setAudioMixingPitch: [#setaudiomixingpitch]
设置本地音乐文件的音调。
```objc
- (int)setAudioMixingPitch:(NSInteger)pitch NS_SWIFT_NAME(setAudioMixingPitch(_:));
```
调用该方法可在本地音乐文件与本地人声混音时,仅调整本地音乐文件的音调。
### 调用时机 [#调用时机-8]
你需要在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 `audioMixingStateChanged:reasonCode:` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用该方法。
### 参数 [#参数-6]
按半音阶设置本地音乐文件的音调(默认值为 0,表示保持原始音调)。取值范围为 -12 到 12,相邻两个值之间的音调差为一个半音。该参数的绝对值越大,本地音乐文件的音调越高或越低。
### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setAudioMixingPlaybackSpeed: [#setaudiomixingplaybackspeed]
设置当前音频文件的播放速度。
```objc
- (int)setAudioMixingPlaybackSpeed:(NSInteger)speed NS_SWIFT_NAME(setAudioMixingPlaybackSpeed(_:));
```
请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 并收到 `audioMixingStateChanged:reasonCode:` 回调报告状态为 `AgoraAudioMixingStateTypePlaying` 后调用此方法。
### 参数 [#参数-7]
播放速度。声网建议设置为 50 到 400 之间的值,定义如下:
- 50:原始速度的一半。
- 100:原始速度。
- 400:原始速度的 4 倍。
### 返回值 [#返回值-14]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-14]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setAudioMixingPosition: [#setaudiomixingposition]
设置混音的播放位置。
```objc
- (int)setAudioMixingPosition:(NSInteger)pos NS_SWIFT_NAME(setAudioMixingPosition(_:));
```
你可以调用该方法将音乐文件的播放位置设置为指定的起始位置。
### 调用时机 [#调用时机-9]
请在调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法并收到 `audioMixingStateChanged:reasonCode:` 回调(状态为 `AgoraAudioMixingStateTypePlaying`)后调用该方法。
### 参数 [#参数-8]
播放位置(单位为毫秒)。
### 返回值 [#返回值-15]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## startAudioMixing\:loopback\:cycle: [#startaudiomixingloopbackcycle]
开始播放音乐文件。
```objc
- (int)startAudioMixing:(NSString * _Nonnull)filePath
loopback:(BOOL)loopback
cycle:(NSInteger)cycle NS_SWIFT_NAME(startAudioMixing(_:loopback:cycle:));
```
关于该方法支持的音频文件格式,详见[声网 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/ios/play/audio-effect-file#api_irtcengine_playeffect3) 方法播放此类文件。
- 如果你需要多次调用该方法,请确保两次调用之间的时间间隔大于 500 毫秒。
:::
### 调用时机 [#调用时机-10]
你可以在加入频道前或加入频道后调用该方法。
### 参数 [#参数-9]
文件路径:
- iOS 或 macOS:音频文件的绝对路径或 URL 地址(包括文件名后缀)。例如:/var/mobile/Containers/Data/audio.mp4。
是否只在本地客户端播放音乐文件:
- YES:只在本地客户端播放音乐文件,只有本地用户可以听到音乐。
- NO:将音乐文件发布到远端客户端,本地用户和远端用户都可以听到音乐。
音乐文件的播放次数:
- > 0:播放的次数。例如,1 表示播放 1 次。
- -1:无限循环播放该音频文件。
### 返回值 [#返回值-16]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -1:发生通用错误(无明确原因)。
- -2:参数无效。
- -3:SDK 尚未就绪。
- 音频模块未启用。
- 程序未完成。
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 初始化失败。请重新初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
### 所属接口类 [#所属接口类-16]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## startAudioMixing\:loopback\:cycle\:startPos: [#startaudiomixingloopbackcyclestartpos]
开始播放音乐文件。
```objc
- (int)startAudioMixing:(NSString * _Nonnull)filePath
loopback:(BOOL)loopback
cycle:(NSInteger)cycle
startPos:(NSInteger)startPos NS_SWIFT_NAME(startAudioMixing(_:loopback:cycle:startPos:));
```
关于该方法支持的音频文件格式,详见[声网 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/ios/play/audio-effect-file#api_irtcengine_playeffect3) 方法播放此类文件。
- 如果需要多次调用该方法,确保两次调用之间的时间间隔大于 500 毫秒。
:::
### 调用时机 [#调用时机-11]
你可以在加入频道前或加入频道后调用该方法。
### 相关回调 [#相关回调]
成功调用该方法后,SDK 会触发 [rtcEngine\:audioMixingStateChanged\:reasonCode:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)(`AgoraAudioMixingStateTypePlaying`)回调。当音频混音文件播放结束时,SDK 会在本地客户端触发 [rtcEngine\:audioMixingStateChanged\:reasonCode:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)(`AgoraAudioMixingStateTypeStopped`)回调。
### 参数 [#参数-10]
文件路径:
- iOS 或 macOS:音频文件的绝对路径或 URL 地址(包括文件名后缀)。例如:/var/mobile/Containers/Data/audio.mp4。
是否只在本地客户端播放音乐文件:
- YES:只在本地客户端播放音乐文件,只有本地用户可以听到音乐。
- NO:将音乐文件发布到远端客户端,本地用户和远端用户都可以听到音乐。
音乐文件的播放次数。
- > 0:播放的次数。例如,1 表示播放 1 次。
- -1:无限循环播放音频文件。
音乐文件的播放起始位置(单位为毫秒)。
### 返回值 [#返回值-17]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -1:发生通用错误(无明确原因)。
- -2:参数无效。
- -3:SDK 尚未就绪。
- 音频模块未启用。
- 程序未完整。
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 初始化失败。请重新初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
### 所属接口类 [#所属接口类-17]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## stopAudioMixing [#stopaudiomixing]
停止播放音乐文件。
```objc
- (int)stopAudioMixing NS_SWIFT_NAME(stopAudioMixing());
```
调用 `startAudioMixing` 播放音乐文件后,可以调用该方法停止播放。如果只需要暂停播放,请调用 [pauseAudioMixing](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_pauseaudiomixing)。
### 调用时机 [#调用时机-12]
请在加入频道后调用该方法。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## rtcEngineLocalAudioMixingDidFinish: [#rtcenginelocalaudiomixingdidfinish]
本地音乐文件播放结束时的回调。
```objc
- (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine NS_SWIFT_NAME(rtcEngineLocalAudioMixingDidFinish(_:)) __deprecated_msg("Use rtcEngine:audioMixingStateChanged:reasonCode: instead");
```
:::error[废弃]
自 v4.5.0 版本废弃,请改用 `audioMixingStateChanged`。
:::
调用 `startAudioMixing` 播放本地音乐文件后,当播放结束时会触发该回调。如果调用失败,会返回错误码 `WARN_AUDIO_MIXING_OPEN_ERROR`。
### 触发时机 [#触发时机]
调用 `startAudioMixing` 播放本地音乐文件后,当播放结束时触发。
### 参数 [#参数-11]
[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
### 所属接口类 [#所属接口类-19]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineeventhandler)
## rtcEngine\:audioMixingPositionChanged: [#rtcengineaudiomixingpositionchanged]
报告音乐文件的播放进度。
```objc
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingPositionChanged:(NSInteger)position NS_SWIFT_NAME(rtcEngine(_:audioMixingPositionChanged:));
```
你调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法播放音乐文件后,SDK 每两秒触发一次该回调,报告音乐文件的播放进度。
### 触发时机 [#触发时机-1]
你调用 [startAudioMixing\:loopback\:cycle\:startPos:](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法播放音乐文件后,SDK 每两秒触发一次该回调。
### 参数 [#参数-12]
[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 实例,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
播放进度,单位为毫秒。
### 所属接口类 [#所属接口类-20]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineeventhandler)
## rtcEngine\:audioMixingStateChanged\:reasonCode: [#rtcengineaudiomixingstatechangedreasoncode]
音乐文件播放状态发生变化回调。
```objc
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingStateChanged:(AgoraAudioMixingStateType)state
reasonCode:(AgoraAudioMixingReasonCode)reasonCode NS_SWIFT_NAME(rtcEngine(_:audioMixingStateChanged:reasonCode:));
```
该回调在音乐文件的播放状态发生变化时触发,并报告当前的状态和错误码。
### 触发时机 [#触发时机-2]
该回调在音乐文件的播放状态发生变化时被触发。
### 参数 [#参数-13]
[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
音乐文件的播放状态,详见 [AgoraAudioMixingStateType](/zh-CN/api-reference/rtc/ios/enum-audiomixingstatetype)。
错误码,详见 [AgoraAudioMixingReasonCode](/zh-CN/api-reference/rtc/ios/enum-audiomixingreasontype)。
### 所属接口类 [#所属接口类-21]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineeventhandler)