# 播放音效或音乐文件 (/zh-CN/realtime-media/rtc/build/audio/audio-effect-mixing/windows)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在游戏或 K 歌等实时音视频场景中,为烘托气氛、增添趣味性,用户通常需要播放音效或音乐文件。
本文介绍如何在你的项目中实现播放音效或音乐文件功能。
## 技术原理 [#技术原理-3]
声网提供了以下 API,帮助你实现播放音效或音乐文件:
- 音效 API:播放持续时间短的氛围音,例如掌声、欢呼声、打斗声、枪击声等,通常可以同时播放**多个音效文件**。
- 音乐 API:播放比较长的音乐文件,例如,在唱歌时播放伴奏,在聊天时播放背景音乐。同一时间,**只能播放一个音乐文件**。
:::warning[注意]
如果使用 `startAudioMixing` 等音乐 API 播放时长较短的音效文件,或使用 `playEffect` 等音效 API 播放时长较长的音乐文件,可能会播放失败。
:::
这些方法主要包括如下功能:
| 功能 | 音效 API | 音乐 API |
| --- | --- | --- |
| 播放或停止播放特定的音频文件 | [audio-effect-mixing-windows-markdown-0-1-1 details](#table-slot-audio-effect-mixing-windows-markdown-0-1-1) | [audio-effect-mixing-windows-markdown-0-1-2 details](#table-slot-audio-effect-mixing-windows-markdown-0-1-2) |
| 暂停或恢复播放音频文件 | [audio-effect-mixing-windows-markdown-0-2-1 details](#table-slot-audio-effect-mixing-windows-markdown-0-2-1) | [audio-effect-mixing-windows-markdown-0-2-2 details](#table-slot-audio-effect-mixing-windows-markdown-0-2-2) |
| 获取和调整音频文件的播放位置和音量 | [audio-effect-mixing-windows-markdown-0-3-1 details](#table-slot-audio-effect-mixing-windows-markdown-0-3-1) | [audio-effect-mixing-windows-markdown-0-3-2 details](#table-slot-audio-effect-mixing-windows-markdown-0-3-2) |
| 报告音频文件的播放状态 | `onAudioEffectFinished` | `onAudioMixingStateChanged` |
**audio-effect-mixing-windows-markdown-0-1-1 details**
- `preloadEffect`
- `unloadEffect`
- `playEffect`
- `stopEffect`
- `stopAllEffects`
**audio-effect-mixing-windows-markdown-0-1-2 details**
- `startAudioMixing`
- `stopAudioMixing`
**audio-effect-mixing-windows-markdown-0-2-1 details**
- `pauseEffect`
- `pauseAllEffects`
- `resumeEffect`
- `resumeAllEffects`
**audio-effect-mixing-windows-markdown-0-2-2 details**
- `pauseAudioMixing`
- `resumeAudioMixing`
**audio-effect-mixing-windows-markdown-0-3-1 details**
- `setEffectPosition`
- `getEffectCurrentPosition`
- `getEffectsVolume`
- `setEffectsVolume`
- `setVolumeOfEffect`
**audio-effect-mixing-windows-markdown-0-3-2 details**
- `getAudioMixingCurrentPosition`
- `setAudioMixingPosition`
- `getAudioMixingPublishVolume`
- `adjustAudioMixingPublishVolume`
- `getAudioMixingPlayoutVolume`
- `adjustAudioMixingPlayoutVolume`
## 前提条件 [#前提条件-3]
在进行操作之前,请确保你已满足以下条件:
- 项目已经实现了基本的[实时音视频功能](/zh-CN/realtime-media/rtc/get-started/quick-start)。
- 了解 [Media Foundation 中支持的媒体格式](https://docs.microsoft.com/zh-cn/windows/desktop/medfound/supported-media-formats-in-media-foundation)。
## 实现播放音频文件 [#实现播放音频文件-3]
本节介绍如何调用音效 API 和音乐混音 API,在你的项目中播放音效和音乐混音文件。
### 播放音效 [#播放音效-3]
加入频道前,调用 `preloadEffect` 方法预加载音效文件。加入频道后,调用 `playEffect` 方法播放指定音效文件。多次调用 `playEffect`,设置多个音效 ID,同时播放多个音效文件。音效播放结束后,SDK 触发 `onAudioEffectFinished` 回调。
在你的声网项目中,打开管理音效播放的文件并添加如下代码:
```cpp
void CAgoraEffectDlg::OnBnClickedButtonPreload()
{
if (m_cmbEffect.GetCurSel() < 0)
{
return;
}
CString strEffect;
m_cmbEffect.GetWindowText(strEffect);
std::string strPath = cs2utf8(strEffect);
// 预加载音效文件
m_rtcEngine->preloadEffect(m_mapEffect[strEffect], strPath.c_str());
CString strInfo;
strInfo.Format(_T("preload effect :path:%s"), strEffect);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraEffectDlg::OnBnClickedButtonUnloadEffect()
{
if (m_cmbEffect.GetCurSel() < 0)
{
return;
}
CString strEffect;
m_cmbEffect.GetWindowText(strEffect);
// 释放预加载的音效文件
m_rtcEngine->unloadEffect(m_mapEffect[strEffect]);
CString strInfo;
strInfo.Format(_T("unload effect :path:%s"), strEffect);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraEffectDlg::OnBnClickedButtonPauseEffect()
{
if (m_cmbEffect.GetCurSel() < 0)
{
return;
}
CString strEffect;
m_cmbEffect.GetWindowText(strEffect);
// 暂停播放指定音效文件
m_rtcEngine->pauseEffect(m_mapEffect[strEffect]);
CString strInfo;
strInfo.Format(_T("pause effect :path:%s"), strEffect);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraEffectDlg::OnBnClickedButtonResumeEffect()
{
if (m_cmbEffect.GetCurSel() < 0)
{
return;
}
CString strEffect;
m_cmbEffect.GetWindowText(strEffect);
// 恢复播放指定音效文件
int ret = m_rtcEngine->resumeEffect(m_mapEffect[strEffect]);
CString strInfo;
strInfo.Format(_T("resume effect ret:%d :path:%s"),ret, strEffect);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraEffectDlg::OnBnClickedButtonPlayEffect()
{
if (m_cmbEffect.GetCurSel() < 0)
{
return;
}
CString strEffect;
m_cmbEffect.GetWindowText(strEffect);
std::string strFile = cs2utf8(strEffect);
CString strLoops;
m_edtLoops.GetWindowText(strLoops);
int loops = _ttol(strLoops);
if (loops == 0) {
m_edtLoops.SetWindowText(_T("1"));
loops = 1;
}
CString strPitch;
m_edtPitch.GetWindowText(strPitch);
double pitch = _ttof(strPitch);
CString strGain;
m_edtGain.GetWindowText(strGain);
int gain = _ttol(strGain);
CString strPan;
m_cmbPan.GetWindowText(strPan);
double pan = _ttof(strPan);
BOOL publish = m_chkPublish.GetCheck();
// 播放音效文件
int ret = m_rtcEngine->playEffect(m_mapEffect[strEffect], strFile.c_str(), loops, pitch, pan, gain, publish);
CString strInfo;
strInfo.Format(_T("play effect :path:%s, ret:%d"), strEffect, ret);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
strInfo.Format(_T("loops:%d,pitch:%.1f,pan:%.0f,gain:%d,publish:%d"),
loops, pitch, pan, gain, publish);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraEffectDlg::OnBnClickedButtonStopEffect()
{
if (m_cmbEffect.GetCurSel() < 0)
{
return;
}
CString strEffect;
m_cmbEffect.GetWindowText(strEffect);
// 停止播放指定音效文件
m_rtcEngine->stopEffect(m_mapEffect[strEffect]);
CString strInfo;
strInfo.Format(_T("stop effect :path:%s"), strEffect);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraEffectDlg::OnBnClickedButtonPauseAllEffect()
{
if (!m_pauseAll)
{
// 暂停播放所有音效文件
m_rtcEngine->pauseAllEffects();
CString strInfo;
strInfo.Format(_T("pause All Effects"));
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
m_btnPauseAll.SetWindowText(AudioEffectCtrlResumeEffect);
}
else {
// 恢复播放所有音效文件
m_rtcEngine->resumeAllEffects();
CString strInfo;
strInfo.Format(_T("resume All Effects"));
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
m_btnPauseAll.SetWindowText(AudioEffectCtrlPauseAllEffect);
}
m_pauseAll = !m_pauseAll;
}
void CAgoraEffectDlg::OnBnClickedButtonStopAllEffect2()
{
// 停止播放所有音效文件
m_rtcEngine->stopAllEffects();
CString strInfo;
strInfo.Format(_T("stop All Effects"));
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
```
### 播放音乐 [#播放音乐-3]
加入频道之前或之后,调用 `startAudioMixing` 方法播放音乐文件。成功调用该方法后,音乐混音状态发生变化时,SDK 触发 `onAudioMixingStateChanged` 回调。该回调也报告音乐混音状态变化的原因。
你还可以通过下列方法实现播放控制:
- `pauseAudioMixing`:暂停播放。
- `resumeAudioMixing`:恢复播放。
- `stopAudioMixing`:停止播放。
- `adjustAudioMixingPlayoutVolume`:调节当前音乐文件在本地的播放音量。
- `adjustAudioMixingPublishVolume`:调节当前音乐文件在远端的播放音量。
在你的声网项目中,打开管理音乐播放的文件,并添加以下代码:
```cpp
void CAgoraAudioMixingDlg::OnBnClickedButtonMixingStart()
{
CString audioUrl = GetExePath() + _T("\\ID_MUSIC_01.m4a");
// 开始播放音乐文件
int ret = m_rtcEngine->startAudioMixing(cs2utf8(audioUrl).c_str(), false, -1);
CString strInfo;
strInfo.Format(_T("startAudioMixing path:%s, ret:%d"), audioUrl.AllocSysString(), ret);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
// 监听 onAudioMixingStateChanged 回调
void CAudioMixingEventHandler::onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE reason)
{
if (m_hMsgHanlder) {
PAudioMixingState stateChanged = new AudioMixingState;
stateChanged->error = reason;
stateChanged->state = state;
::PostMessage(m_hMsgHanlder, WM_MSGID(EID_REMOTE_AUDIO_MIXING_STATE_CHANED), (WPARAM)stateChanged, 0);
}
}
void CAgoraAudioMixingDlg::OnBnClickedButtonMixingPause()
{ // 暂停播放
int ret = m_rtcEngine->pauseAudioMixing();
CString strInfo;
strInfo.Format(_T("pauseAudioMixing ret:%d"), ret);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraAudioMixingDlg::OnBnClickedButtonMixingResume()
{ // 恢复播放
int ret = m_rtcEngine->resumeAudioMixing();
CString strInfo;
strInfo.Format(_T("resumeAudioMixing ret:%d"), ret);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraAudioMixingDlg::OnBnClickedButtonMixingStop()
{ // 停止播放
int ret = m_rtcEngine->stopAudioMixing();
CString strInfo;
strInfo.Format(_T("stopAudioMixing ret:%d"), ret);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}
void CAgoraAudioMixingDlg::OnNMCustomdrawSliderMixingPlayoutVolume(NMHDR* pNMHDR, LRESULT* pResult)
{
LPNMCUSTOMDRAW pNMCD = reinterpret_cast(pNMHDR);
int pos = m_sldMixingPlayoutVolume.GetPos();
// 调节当前音乐文件在本地的播放音量
int ret = m_rtcEngine->adjustAudioMixingPlayoutVolume(pos);
*pResult = 0;
}
void CAgoraAudioMixingDlg::OnNMCustomdrawSliderMixingPublishVolume(NMHDR* pNMHDR, LRESULT* pResult)
{
LPNMCUSTOMDRAW pNMCD = reinterpret_cast(pNMHDR);
int pos = m_sldMixingPublishVolume.GetPos();
// 调节当前音乐文件在远端的播放音量
int ret = m_rtcEngine->adjustAudioMixingPublishVolume(pos);
*pResult = 0;
}
```
## 参考信息 [#参考信息-4]
### 示例项目 [#示例项目-3]
声网提供如下开源的示例项目。你可以前往下载或查看其中的源代码。
### API 参考 [#api-参考-4]
- [`preloadEffect`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_preloadeffect)
- [`playEffect`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3)
- [`onAudioEffectFinished`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#callback_irtcengineeventhandler_onaudioeffectfinished)
- [`startAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_startaudiomixing2)
- [`onAudioMixingStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)
- [`pauseAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_pauseaudiomixing)
- [`resumeAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_resumeaudiomixing)
- [`stopAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_stopaudiomixing)
- [`adjustAudioMixingPlayoutVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_adjustaudiomixingplayoutvolume)
- [`adjustAudioMixingPublishVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_adjustaudiomixingpublishvolume)
### 相关文档 [#相关文档-3]
[为什么通过系统音量无法调节背景音乐?](/zh-CN/reference/faq/quality/adjust_music_volume)