遊戲/互動 App 中的短促音效 (按鈕點擊、碰撞、金幣、爆炸) 需要 低延遲、支援多聲道疊加、獨立音量控制。MediaPlayer 適用於長音樂/影片,延遲高、不支援疊加;SoundPool 專為短音效設計,API 21+ 新增 SoundPool.Builder 更穩定。本文提供生產級封裝類 SoundManager,支援資源預載、ID 映射、流量控制、釋放資源。
public class SoundManager {
private static final String TAG = "SoundManager";
private static final int MAX_STREAMS = 10; // 最大同時播放聲道數
private static final int SOUND_QUALITY = 100; // 採樣率品質 (無實際影響,保留參數)
private final SoundPool soundPool;
private final SparseIntArray soundIdMap; // 業務音效 ID -> SoundPool 內部 ID
private final AudioManager audioManager;
private float masterVolume = 1.0f; // 總音量倍率 0.0f - 1.0f
public SoundManager(Context context) {
// API 21+ 使用 Builder,舊版用 new SoundPool(maxStreams, streamType, quality)
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
AudioAttributes attrs = new AudioAttributes.Builder()
.setUsage(AudioAttributes.USAGE_GAME)
.setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
.build();
soundPool = new SoundPool.Builder()
.setMaxStreams(MAX_STREAMS)
.setAudioAttributes(attrs)
.build();
} else {
soundPool = new SoundPool(MAX_STREAMS, AudioManager.STREAM_MUSIC, SOUND_QUALITY);
}
soundIdMap = new SparseIntArray();
audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
}
/**
* 預載音效資源 (建議在 Loading 畫面/Application 啟動時呼叫)
* @param soundId 業務邏輯使用的音效 ID (如 R.raw.coin, R.raw.jump)
* @param rawResId raw 目錄下資源 ID
*/
public void load(int soundId, @RawRes int rawResId) {
int poolId = soundPool.load(context, rawResId, 1); // priority=1
soundIdMap.put(soundId, poolId);
Log.d(TAG, "Loaded soundId=" + soundId + " -> poolId=" + poolId);
}
/** 批次預載 */
public void loadAll(SparseIntArray mapping) {
for (int i = 0; i < mapping.size(); i++) {
load(mapping.keyAt(i), mapping.valueAt(i));
}
}
/**
* 播放音效
* @param soundId 業務音效 ID
* @param loop 循環次數:0=播放一次, -1=無限循環, >0=循環次數
* @param volume 單獨音量倍率 0.0f-1.0f (最終音量 = masterVolume * volume * 系統媒體音量)
*/
public void play(int soundId, int loop, float volume) {
Integer poolId = soundIdMap.get(soundId);
if (poolId == null) {
Log.w(TAG, "音效未預載: " + soundId);
return;
}
float finalVolume = masterVolume * volume * getSystemVolumeRatio();
int streamId = soundPool.play(poolId, finalVolume, finalVolume, 1, loop, 1f);
Log.d(TAG, "Play soundId=" + soundId + " streamId=" + streamId + " vol=" + finalVolume);
}
/** 便利方法:播放一次,預設音量 */
public void play(int soundId) { play(soundId, 0, 1.0f); }
/** 停止特定音效實例 (需保存 play 回傳的 streamId) */
public void stop(int streamId) { soundPool.stop(streamId); }
/** 停止所有音效 */
public void stopAll() { soundPool.autoPause(); }
/** 設定總音量倍率 */
public void setMasterVolume(float volume) { masterVolume = Math.max(0f, Math.min(1f, volume)); }
/** 獲取系統媒體音量比率 (0.0f - 1.0f) */
private float getSystemVolumeRatio() {
int maxVol = audioManager.getStreamMaxVolume(AudioManager.STREAM_MUSIC);
int curVol = audioManager.getStreamVolume(AudioManager.STREAM_MUSIC);
return maxVol > 0 ? (float) curVol / maxVol : 1f;
}
/** 釋放資源 (在 Application.onTerminate 或 Activity.onDestroy 釋放) */
public void release() {
soundPool.release();
soundIdMap.clear();
Log.d(TAG, "SoundPool released");
}
}
public class GameApplication extends Application {
public static SoundManager soundManager;
@Override
public void onCreate() {
super.onCreate();
soundManager = new SoundManager(this);
// 預載常用音效
SparseIntArray map = new SparseIntArray();
map.put(SoundId.COIN, R.raw.coin);
map.put(SoundId.JUMP, R.raw.jump);
map.put(SoundId.EXPLOSION, R.raw.explosion);
map.put(SoundId.BUTTON_CLICK, R.raw.click);
soundManager.loadAll(map);
}
@Override
public void onTerminate() {
soundManager.release();
super.onTerminate();
}
}
// 遊戲邏輯中播放
GameApplication.soundManager.play(SoundId.COIN);
GameApplication.soundManager.play(SoundId.EXPLOSION, 0, 0.8f); // 稍微降低爆炸音量
// 背景音樂請改用 MediaPlayer 或 ExoPlayer
.ogg (Vorbis) 或 .mp3,採樣率 44.1kHz/22.05kHz,單聲道 (Mono) 檔案較小且延遲低。res/raw/sfx_coin.ogg、sfx_jump.ogg,對應 R.raw.sfx_coin。| 問題 | 原因 | 解決 |
|---|---|---|
| 首次播放有明顯延遲 | SoundPool 需解碼載入 | 務必在 Loading 階段 load() 預載,或使用 soundPool.setOnLoadCompleteListener 等待載入完成再播放 |
| 同時播放過多聲音靜音/截斷 | 超過 MAX_STREAMS | 增大 MAX_STREAMS (上限 32),或實作優先級隊列自動停止低優先級聲音 |
| 音量無效/忽大忽小 | 系統媒體音量、通話音量、鈴聲音量混淆 | 統一使用 AudioManager.STREAM_MUSIC,並在設定頁提供獨立音效音量滑桿控制 masterVolume |
| OOM / Native Crash | 載入過多/過大音效 | 控制總大小 < 1-2MB,釋放不用音效 soundPool.unload(poolId) |
| Android 8.0+ 靜音 | AudioAttributes 用法錯誤 | 確認 USAGE_GAME + CONTENT_TYPE_SONIFICATION |
SoundPoolManager 單例,提供 acquire(soundId)/release(streamId) 池化管理,避免重複載入。