萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android 遊戲音效引擎:SoundPool 完整封裝與最佳實踐 (低延遲、多聲道、音量控制)

遊戲/互動 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) 檔案較小且延遲低。
  • 長度: 单個音效 ≤ 5 秒,超過請用 MediaPlayer。
  • 命名: res/raw/sfx_coin.ogg、sfx_jump.ogg,對應 R.raw.sfx_coin。
  • 音量標準化: 製作階段將所有音效標準化至 -3dB 至 -6dB,避免播放時忽大忽小。

常見問題與解決

問題原因解決
首次播放有明顯延遲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) 池化管理,避免重複載入。
  • OpenSL ES / AAudio (NDK) 可實現更低延遲 (< 10ms) 與 3D 空間音效,適合高階遊戲引擎 (Unity/Unreal/Godot 已內建)。
copyright © 萬盛學電腦網 all rights reserved