SoundPool 專為短促音效設計(遊戲音效、UI 交互聲、按鍵音),支持多聲道並發播放、音量/速率/優先級控制、音頻流類型管理。本文提供生產級封裝類,解決舊版 API 兼容、資源釋放、音量同步、並發控制等實戰痛點。
public class SoundManager {
private static final String TAG = "SoundManager";
private static final int MAX_STREAMS = 8; // 並發流數,避免過大導致混音失真
private static final int SOUND_QUALITY = 0; // 0 = 默認質量
private static SoundManager instance;
private SoundPool soundPool;
private final SparseIntArray soundIdMap = new SparseIntArray(); // resId -> streamId
private AudioManager audioManager;
private float masterVolume = 1.0f; // 主音量倍率 0~1
private boolean isMuted = false;
private SoundManager(Context context) {
audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
initSoundPool();
}
public static synchronized SoundManager getInstance(Context context) {
if (instance == null) {
instance = new SoundManager(context.getApplicationContext());
}
return instance;
}
@SuppressLint("NewApi")
private void initSoundPool() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
// API 21+ 使用 Builder 模式
AudioAttributes attrs = new AudioAttributes.Builder()
.setUsage(AudioAttributes.USAGE_GAME) // 或 USAGE_ASSISTANCE_SONIFICATION
.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);
}
// 載入完成監聽 (可選)
soundPool.setOnLoadCompleteListener((pool, sampleId, status) -> {
if (status != 0) Log.w(TAG, "Sound load failed: sampleId=" + sampleId);
});
}
/** 預載入音效資源 (建議 Application/啟動頁預載) */
public void preload(Context context, @RawRes int... resIds) {
for (int resId : resIds) {
if (soundIdMap.get(resId, 0) == 0) {
int streamId = soundPool.load(context, resId, 1); // priority=1
soundIdMap.put(resId, streamId);
}
}
}
/** 播放音效 */
public int play(@RawRes int resId) {
return play(resId, 1.0f, 1.0f, 1, 0, 1.0f);
}
/** 完整參數播放
* @param resId 原始資源 ID
* @param leftVolume 左聲道音量 0~1
* @param rightVolume 右聲道音量 0~1
* @param priority 優先級 (數值大優先,超過 MAX_STREAMS 會截斷低優先級)
* @param loop 循環次數 (0=不循環, -1=無限循環)
* @param rate 播放速率 (0.5~2.0, 1.0=正常)
* @return 流 ID (可用於 stop/pause/設定音量), 0 表示失敗
*/
public int play(@RawRes int resId, float leftVolume, float rightVolume,
int priority, int loop, float rate) {
if (isMuted || soundPool == null) return 0;
int streamId = soundIdMap.get(resId, 0);
if (streamId == 0) {
Log.w(TAG, "Sound not preloaded: " + resId + ", loading now...");
streamId = soundPool.load(getContext(), resId, priority);
soundIdMap.put(resId, streamId);
// 注意:異步加載,首次播放可能無聲,建議嚴格預載
}
// 同步系統媒體音量 (可選策略)
float volume = getCurrentVolume();
return soundPool.play(streamId,
leftVolume * volume * masterVolume,
rightVolume * volume * masterVolume,
priority, loop, rate);
}
/** 獲取當前媒體流音量 (0~1 歸一化) */
private float getCurrentVolume() {
if (audioManager == null) return 1.0f;
int maxVol = audioManager.getStreamMaxVolume(AudioManager.STREAM_MUSIC);
int curVol = audioManager.getStreamVolume(AudioManager.STREAM_MUSIC);
return maxVol > 0 ? (float) curVol / maxVol : 1.0f;
}
/** 停止特定音效 */
public void stop(@RawRes int resId) {
int streamId = soundIdMap.get(resId, 0);
if (streamId != 0 && soundPool != null) {
soundPool.stop(streamId);
}
}
/** 停止所有音效 */
public void stopAll() {
if (soundPool != null) soundPool.autoPause(); // 或遍歷 stop
}
/** 釋放資源 (Application onTerminate / 退出遊戲時調用) */
public void release() {
if (soundPool != null) {
soundPool.release();
soundPool = null;
soundIdMap.clear();
}
}
// 音量/靜音控制
public void setMasterVolume(float volume) { masterVolume = Math.max(0f, Math.min(1f, volume)); }
public void setMuted(boolean muted) { isMuted = muted; }
public boolean isMuted() { return isMuted; }
}
// 1. 應用啟動預載 (Application.onCreate)
SoundManager.getInstance(this).preload(this,
R.raw.sound_click, R.raw.sound_coin, R.raw.sound_jump, R.raw.sound_explosion);
// 2. 遊戲/界面中播放
// 簡單播放
SoundManager.getInstance(context).play(R.raw.sound_click);
// 進階:3D 位置音效模擬 (左右聲道音量差)
float pan = (touchX - screenWidth/2) / (screenWidth/2); // -1 ~ 1
float left = 1 - Math.max(0, pan);
float right = 1 + Math.min(0, pan);
SoundManager.getInstance(context).play(R.raw.sound_explosion, left, right, 1, 0, 1.0f);
// 3. 退出釋放
@Override
protected void onDestroy() {
super.onDestroy();
if (isFinishing()) SoundManager.getInstance(this).release(); // 最後一個 Activity 釋放
}
| 特性 | SoundPool | MediaPlayer |
|---|---|---|
| 適用時長 | < 5-10 秒 | 任意長度 (音樂、長語音) |
| 解碼方式 | 解碼至內存 (PCM) | 流式解碼 |
| 延遲 | 極低 (~10ms) | 較高 (~100-500ms) |
| 並發 | 支持多流混音 | 單實例單流 |
| 控制能力 | 音量/速率/優先級/循環 | 完整播放控制/緩衝/字幕/DRM |
| 內存佔用 | 較高 (全解碼) | 較低 (流式) |
| 格式支持 | OGG/MP3/WAV (建議 OGG) | 全格式 (含網絡流) |
load() 異步解碼,首次調用 play() 可能無聲。啟動頁/關卡加載時預載所有音效。MAX_STREAMS 設 8-16,過大導致混音失真、CPU 飆升、OOM。AUDIO_BECOMING_NOISY 廣播 (拔耳機) 自動暫停/降低音量。release() 後不可再用,需重新 new SoundPool()。避免在 Activity 銷毀時釋放導致其他頁無聲,建議 Application 級單例管理。AudioAttributes.USAGE_ASSISTANCE_SONIFICATION 繞過。Media3 的 MediaController + MediaSession 統一音頻焦點管理,ExoPlayer 短音效模式 (setRenderersFactory 低延遲) 可替代 SoundPool,但代碼複雜度較高。簡單遊戲/UI音效仍首選 SoundPool。
SoundPool 雖然 API 古老,但在「低延遲、高並發、短音效」領域仍無可替代。構建健壯的 SoundManager 封裝,處理好生命週期、預載策略、音量同步,是遊戲客戶端、互動應用音頻架構的核心環節。