Cocos2d-x 音頻引擎 SimpleAudioEngine 完全使用指南

Cocos2d-x 音頻引擎 SimpleAudioEngine 完全使用指南

SimpleAudioEngine 是 Cocos2d-x 封裝的跨平台音頻接口（底層依賴 CocosDenshion，iOS 用 OpenAL，Android 用 OpenSL ES/OpenAL）。本文詳解背景音樂與音效的加載、播放、控制、資源釋放全生命周期管理。

一、 核心區別：背景音樂 vs 音效

二、 單例訪問模式

#include "SimpleAudioEngine.h"
using namespace CocosDenshion;

// 獲取單例
SimpleAudioEngine* audio = SimpleAudioEngine::getInstance(); // 3.x
// 或舊版 SimpleAudioEngine::sharedEngine()

三、 背景音樂 API 全覽

// 預加載 (必須在播放前調用，異步加載解碼)
void preloadBackgroundMusic(const char* path);

// 播放
void playBackgroundMusic(const char* path, bool loop = true); // loop=true 循環

// 暫停/恢復/停止/重播
void pauseBackgroundMusic();
void resumeBackgroundMusic();
void stopBackgroundMusic();      // 停止並重置位置
void rewindBackgroundMusic();    // 從頭播放 (不改變播放狀態)

// 狀態查詢
bool isBackgroundMusicPlaying();

// 音量控制 (0.0 ~ 1.0)
void setBackgroundMusicVolume(float volume);
float getBackgroundMusicVolume();

四、 音效 API 全覽

// 預加載/卸載
void preloadEffect(const char* path);
void unloadEffect(const char* path); // 釋放內存

// 播放：返回音效 ID (unsigned int)，用於後續精確控制
unsigned int playEffect(const char* path, bool loop = false); // 默認不循環

// 單個音效控制 (需 ID)
void stopEffect(unsigned int soundId);
void pauseEffect(unsigned int soundId);
void resumeEffect(unsigned int soundId);

// 全局音效控制
void stopAllEffects();
void pauseAllEffects();
void resumeAllEffects();

// 音量 (0.0 ~ 1.0)
void setEffectsVolume(float volume);
float getEffectsVolume();

// 注意：無 isEffectPlaying(soundId) 接口，需自行擴展底層實現

五、 關鍵最佳實踐與避坑指南

1. 格式選擇：BGM 用 mp3（體積小、硬解碼）；音效用 wav（無壓縮、延遲極低、適合高頻觸發）。
2. 生命周期管理：
   • 場景切換時 stopBackgroundMusic() 或 pauseBackgroundMusic()。
   • 遊戲退出/進入後台 AppDelegate::applicationDidEnterBackground 調用 pauseBackgroundMusic() / pauseAllEffects()。
   • 恢復前台 applicationWillEnterForeground 調用 resumeBackgroundMusic() / resumeAllEffects()。
   • 完全退出釋放引擎資源：SimpleAudioEngine::end() (釋放單例、關閉音頻設備)。
3. 常見問題排查：
   • **無聲音**：檢查 preloadBackgroundMusic 是否調用；文件路徑大小寫（Android 區分大小寫）；mp3 編碼是否標準（嘗試格式工廠轉碼）。
   • **黑屏後音效丟失**：檢查 applicationDidEnterBackground / applicationWillEnterForeground 是否正確處理暫停恢復。
   • **音效疊加失控**：播放前判斷是否已在播放，或用 ID 精確停止舊實例。

六、 代碼片段：完整播放流程

// 初始化 (AppDelegate::applicationDidFinishLaunching)
auto audio = SimpleAudioEngine::getInstance();
audio->preloadBackgroundMusic("bgm.mp3");
audio->preloadEffect("jump.wav");
audio->setBackgroundMusicVolume(0.5f);
audio->setEffectsVolume(0.8f);

// 遊戲開始
audio->playBackgroundMusic("bgm.mp3", true);

// 角色跳躍
unsigned int jumpId = audio->playEffect("jump.wav");

// 關卡結束
audio->stopEffect(jumpId);
audio->stopBackgroundMusic();

// 遊戲退出
SimpleAudioEngine::end();

1. 上一篇文章： 線程安全代碼核心原則：從變量作用域到同步機制
2. 下一篇文章： C++ 常量深度解析：字面值、宏、const 常變量與原生字符串

C++ 入門

C++ 代碼審查清單：參考林銳《高質量 C/C++ 編程》

文件結構 頭文件/定義文件命名、目錄合理 版權版本聲明完整

C++ 開發人臉性別識別教程（12）：整合性別識別功能

C++ 開發人臉性別識別教程（12）：整合性別識別 離線訓

UVA 488 Triangle Wave——簡單模擬輸出三角波形

題目大意 給定振幅 A（1~9）和頻率 F，輸出 F 個三角

CF 196 Div2 D：樹形 DP 求可能包含邪惡之書的節點數

問題描述 n 個節點的樹（n ≤ 1e5），m 個已知受影響