# 播放音效或音乐文件 (/zh-CN/realtime-media/rtc/build/audio/audio-effect-mixing/unity)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在游戏或 K 歌等实时音视频场景中,为烘托气氛、增添趣味性,用户通常需要播放音效或音乐文件。
本文介绍如何在你的项目中实现播放音效或音乐文件功能。
## 技术原理 [#技术原理-5]
声网提供了以下 API,帮助你实现播放音效或音乐文件:
- 音效 API:播放持续时间短的音效文件,例如掌声、欢呼声、打斗声、枪击声等,通常可以同时播放**多个音效文件**。
- 音乐 API:播放比较长的音乐文件,例如,在唱歌时播放伴奏,在聊天时播放背景音乐。同一时间,**只能播放一个音乐文件**。
:::warning[注意]
如果使用 `StartAudioMixing` 等音乐 API 播放时长较短的音效文件,或使用 `PlayEffect` 等音效 API 播放时长较长的音乐文件,可能会播放失败。
:::
这些方法主要包括如下功能:
| 功能 | 音效 API | 音乐 API |
| --- | --- | --- |
| 播放或停止播放特定的音频文件 | [audio-effect-mixing-unity-markdown-0-1-1 details](#table-slot-audio-effect-mixing-unity-markdown-0-1-1) | [audio-effect-mixing-unity-markdown-0-1-2 details](#table-slot-audio-effect-mixing-unity-markdown-0-1-2) |
| 暂停或恢复播放音频文件 | [audio-effect-mixing-unity-markdown-0-2-1 details](#table-slot-audio-effect-mixing-unity-markdown-0-2-1) | [audio-effect-mixing-unity-markdown-0-2-2 details](#table-slot-audio-effect-mixing-unity-markdown-0-2-2) |
| 获取和调整音频文件的播放位置和音量 | [audio-effect-mixing-unity-markdown-0-3-1 details](#table-slot-audio-effect-mixing-unity-markdown-0-3-1) | [audio-effect-mixing-unity-markdown-0-3-2 details](#table-slot-audio-effect-mixing-unity-markdown-0-3-2) |
| 报告音频文件的播放状态 | `OnAudioEffectFinished` | `OnAudioMixingStateChanged` |
**audio-effect-mixing-unity-markdown-0-1-1 details**
- `PreloadEffect`
- `UnloadEffect`
- `PlayEffect`
- `StopEffect`
- `StopAllEffects`
**audio-effect-mixing-unity-markdown-0-1-2 details**
- `StartAudioMixing`
- `StopAudioMixing`
**audio-effect-mixing-unity-markdown-0-2-1 details**
- `PauseEffect`
- `PauseAllEffects`
- `ResumeEffect`
- `ResumeAllEffects`
**audio-effect-mixing-unity-markdown-0-2-2 details**
- `PauseAudioMixing`
- `ResumeAudioMixing`
**audio-effect-mixing-unity-markdown-0-3-1 details**
- `SetEffectPosition`
- `GetEffectCurrentPosition`
- `GetEffectsVolume`
- `SetEffectsVolume`
- `SetVolumeOfEffect`
**audio-effect-mixing-unity-markdown-0-3-2 details**
- `GetAudioMixingCurrentPosition`
- `SetAudioMixingPosition`
- `GetAudioMixingPublishVolume`
- `AdjustAudioMixingPublishVolume`
- `GetAudioMixingPlayoutVolume`
- `AdjustAudioMixingPlayoutVolume`
## 前提条件 [#前提条件-5]
在进行操作之前,请确保你已满足以下条件:
- 项目已经实现了基本的[实时音视频功能](/zh-CN/realtime-media/rtc/get-started/quick-start)。
- 需播放的音乐或音效文件的路径有效。
## 实现播放音频文件 [#实现播放音频文件-4]
本节介绍如何调用音效 API 和音乐混音 API,在你的项目中播放音效和音乐文件。
### 实现播放音效 [#实现播放音效]
加入频道前,调用 `PreloadEffect` 方法预加载音效文件。加入频道后,调用 `PlayEffect` 方法播放指定音效文件。多次调用 `PlayEffect`,设置多个音效 ID,同时播放多个音效文件。音效播放结束后,SDK 触发 `OnAudioEffectFinished` 回调。
在你的声网项目中,打开管理音效播放的文件并添加如下代码:
```csharp
// 加入频道前预加载音效文件
RtcEngine.PreloadEffect(1, "File Path 1", 0);
RtcEngine.PreloadEffect(2, "File Path 2", 0);
RtcEngine.PreloadEffect(3, "File Path 3", 0);
// 加入频道后播放预加载的音效文件
RtcEngine.PlayEffect(1, "File Path 1", 1, 0, 0, 0, true, 0);
RtcEngine.PlayEffect(2, "File Path 2", 1, 0, 0, 0, true, 0);
RtcEngine.PlayEffect(3, "File Path 3", 1, 0, 0, 0, true, 0);
// 当本地音效文件播放结束时触发
public override void OnAudioEffectFinished(int soundId)
{
Debug.Log("effect play finish :" + soundId);
}
```
### 播放音乐 [#播放音乐-4]
加入频道之前或之后,调用 `StartAudioMixing` 方法播放音乐文件。成功调用该方法后,音乐混音状态发生变化时,SDK 触发 `OnAudioMixingStateChanged` 回调。该回调也报告音乐混音状态变化的原因。
在你的声网项目中,打开管理音乐播放的文件,并添加以下代码:
```csharp
RtcEngine.StartAudioMixing("File Path", false, -1);
public override void OnAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE errorCode)
{
Debug.Log(string.Format("AUDIO_MIXING_STATE_TYPE: ${0}, AUDIO_MIXING_REASON_TYPE: ${1}",
state, errorCode));
}
```
你还可以通过下列方法实现播放控制:
- `PauseAudioMixing`:暂停播放。
- `ResumeAudioMixing`:恢复播放。
- `StopAudioMixing`:停止播放。
- `AdjustAudioMixingPlayoutVolume`:调节当前音乐文件在本地的播放音量。
- `AdjustAudioMixingPublishVolume`:调节当前音乐文件在远端的播放音量。
## 参考信息 [#参考信息-6]
### 示例项目 [#示例项目-5]
声网提供播放音效、音乐文件的示例项目供你参考。你可以前往下载或查看其中的源代码。
AudioMixing} href="https://gitee.com/agoraio-community/Agora-Unity-Quickstart/tree/main/API-Example-Unity/Assets/API-Example/Examples/Advanced/AudioMixing" />
AudioMixing} href="https://github.com/AgoraIO-Extensions/Agora-Unity-Quickstart/blob/main/API-Example-Unity/Assets/API-Example/Examples/Advanced/AudioMixing/AudioMixing.cs" />
### API 参考 [#api-参考-6]
- [`PreloadEffect`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengine_preloadeffect)
- [`PlayEffect`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengine_playeffect3)
- [`OnAudioEffectFinished`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished)
- [`StartAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_startaudiomixing2)
- [`OnAudioMixingStateChanged`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)
- [`PauseAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_pauseaudiomixing)
- [`ResumeAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_resumeaudiomixing)
- [`StopAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_stopaudiomixing)
- [`AdjustAudioMixingPlayoutVolume`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_adjustaudiomixingplayoutvolume)
- [`AdjustAudioMixingPublishVolume`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_adjustaudiomixingpublishvolume)
### 相关文档 [#相关文档-5]
[为什么用 Unity 组件播放背景音乐会无声?](/zh-CN/reference/faq/integration/no_music_unity_objects)