# 播放音效或音乐文件 (/zh-CN/realtime-media/rtc/build/audio/audio-effect-mixing/react-native)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在游戏或 K 歌等实时音视频场景中,为烘托气氛、增添趣味性,用户通常需要播放音效或音乐文件。
本文介绍如何在你的项目中实现播放音效或音乐文件功能。
## 技术原理 [#技术原理-6]
声网提供了以下 API, 帮助你实现播放音效或音乐文件:
- 音效 API:播放持续时间短的氛围音,例如掌声、欢呼声、打斗声、枪击声等,通常可以同时播放**多个音效文件**。
- 音乐 API:播放比较长的音乐文件,例如,在唱歌时播放伴奏,在聊天时播放背景音乐。同一时间,**只能播放一个音乐文件**。
:::warning[注意]
如果使用 `startAudioMixing` 等音乐 API 播放时长较短的音效文件、或使用 `playEffect` 等音效 API 播放时长较长的音乐文件可能会播放失败。
:::
这些方法主要包括如下功能:
| 功能 | 音效 API | 音乐 API |
| --- | --- | --- |
| 播放或停止播放特定的音频文件 | [audio-effect-mixing-rn-markdown-0-1-1 details](#table-slot-audio-effect-mixing-rn-markdown-0-1-1) | [audio-effect-mixing-rn-markdown-0-1-2 details](#table-slot-audio-effect-mixing-rn-markdown-0-1-2) |
| 暂停或恢复播放音频文件 | [audio-effect-mixing-rn-markdown-0-2-1 details](#table-slot-audio-effect-mixing-rn-markdown-0-2-1) | [audio-effect-mixing-rn-markdown-0-2-2 details](#table-slot-audio-effect-mixing-rn-markdown-0-2-2) |
| 获取和调整音频文件的播放位置和音量 | [audio-effect-mixing-rn-markdown-0-3-1 details](#table-slot-audio-effect-mixing-rn-markdown-0-3-1) | [audio-effect-mixing-rn-markdown-0-3-2 details](#table-slot-audio-effect-mixing-rn-markdown-0-3-2) |
| 报告音频文件的播放状态 | `onAudioEffectFinished` | `onAudioMixingStateChanged` |
**audio-effect-mixing-rn-markdown-0-1-1 details**
- `preloadEffect`
- `unloadEffect`
- `playEffect`
- `stopEffect`
- `stopAllEffects`
**audio-effect-mixing-rn-markdown-0-1-2 details**
- `startAudioMixing`
- `stopAudioMixing`
**audio-effect-mixing-rn-markdown-0-2-1 details**
- `pauseEffect`
- `pauseAllEffects`
- `resumeEffect`
- `resumeAllEffects`
**audio-effect-mixing-rn-markdown-0-2-2 details**
- `pauseAudioMixing`
- `resumeAudioMixing`
**audio-effect-mixing-rn-markdown-0-3-1 details**
- `setEffectPosition`
- `getEffectCurrentPosition`
- `getEffectsVolume`
- `setEffectsVolume`
- `setVolumeOfEffect`
**audio-effect-mixing-rn-markdown-0-3-2 details**
- `getAudioMixingCurrentPosition`
- `setAudioMixingPosition`
- `getAudioMixingPublishVolume`
- `adjustAudioMixingPublishVolume`
- `getAudioMixingPlayoutVolume`
- `adjustAudioMixingPlayoutVolume`
## 前提条件 [#前提条件-6]
在进行操作之前,请确保你已满足以下条件:
- 项目已经实现了[基本的实时音视频功能](/zh-CN/realtime-media/rtc/get-started/quick-start)。
- 如果目标开发平台为 Android,你的设备需要运行 Android 4.2 或以上版本。
- 了解目标开发平台支持的媒体格式:
- Android:[Android 设备支持的媒体文件格式](https://developer.android.com/guide/topics/media/media-formats)
- iOS:[Best Practices for Audio](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/MultimediaPG/UsingAudio/UsingAudio.html#//apple_ref/doc/uid/TP40009767-CH2-SW28)
## 实现方法 [#实现方法-2]
本节介绍如何调用音效 API 和音乐混音 API,在你的项目中播放音效和音乐混音文件。
### 播放音效文件 [#播放音效文件]
加入频道后,调用 `playEffect` 方法播放指定音效文件。多次调用 `playEffect`,设置多个音效 ID,同时播放多个音效文件。音效播放结束后,SDK 触发 `onAudioEffectFinished` 回调。
在你的声网项目中,打开管理音效播放的文件并添加如下代码:
```typescript
// 注册音效播放完成回调
const EventHandles = {
onAudioEffectFinished: (soundId) => {
console.log(`soundId:${soundId}`);
}
}
rtcEngine.registerEventHandler(EventHandles);
// 播放音效文件
rtcEngine.playEffect(
soundId: 0, // 设置音效 ID
filePath: 'your file path', // 设置音效文件路径
loopCount: 1, // 设置音效循环播放的次数。1 表示循环一次
pitch: 1.0, // 设置音效的音调。1.0 表示原始音调
pan: 0, // 设置音效的空间位置。0.0 表示音效出现在正前方
gain: 100, // 设置音效音量。100 表示原始音量
publish: false, // 设置是否将音效发布至远端
startPos: 0, // 设置音效文件的播放位置。0 表示从音效文件的第 0 ms 开始播放
);
```
### 播放音乐文件 [#播放音乐文件-1]
调用 `startAudioMixing` 方法播放音乐文件。成功调用该方法后,音乐混音状态发生变化时,SDK 触发 `onAudioMixingStateChanged` 回调,报告改变后的音乐文件播放状态以及改变的原因。
在你的声网项目中,打开管理音效播放的文件夹添加以下代码:
```typescript
// 注册音乐文件的播放状态已改变回调
const EventHandles = {
onAudioMixingStateChanged: (state, reason) => {
console.log(`state:${state}, reason:${reason}`);
}
}
rtcEngine.registerEventHandler(EventHandles);
// 播放音乐文件
rtcEngine.startAudioMixing(
filePath: 'your file path', // 设置音乐文件路径
loopback: false, // 设置是否只在本地播放音乐文件。false 表示将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐
cycle: -1, // 设置音乐文件的播放次数。-1 表示无限循环播放
startPos: 0, // 设置音乐文件的播放位置。0 表示从音效文件的第 0 ms 开始播放
);
```
## 参考信息 [#参考信息-7]
### 示例项目 [#示例项目-6]
声网提供了开源的播放音效或音乐文件示例项目供你参考,你可以前往下载或查看其中的源代码。
PlayEffect} href="https://gitee.com/agoraio-community/react-native-agora/tree/main/example/src/examples/advanced/PlayEffect/PlayEffect.tsx" />
PlayEffect} href="https://github.com/AgoraIO-Extensions/react-native-agora/blob/main/examples/legacy/src/examples/advanced/PlayEffect/PlayEffect.tsx" />
AudioMixing} href="https://gitee.com/agoraio-community/react-native-agora/tree/main/example/src/examples/advanced/AudioMixing/AudioMixing.tsx" />
AudioMixing} href="https://github.com/AgoraIO-Extensions/react-native-agora/blob/main/examples/legacy/src/examples/advanced/AudioMixing/AudioMixing.tsx" />
### API 参考 [#api-参考-7]
- [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3)
- [`onAudioEffectFinished`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished)
- [`startAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_startaudiomixing2)
- [`onAudioMixingStateChanged`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)
### 相关文档 [#相关文档-6]
- [为什么通过系统音量无法调节背景音乐?](/zh-CN/reference/faq/quality/adjust_music_volume)
- [为什么 Android 设备上挂断系统电话后音乐文件不会自动恢复播放?](/zh-CN/reference/faq/integration/music_pause)