简介： CSDN博客专家、《Android系统多媒体进阶实战》作者

博主新书推荐：《Android系统多媒体进阶实战》🚀
Android Audio工程师专栏地址： Audio工程师进阶系列【原创干货持续更新中……】🚀
Android多媒体专栏地址： 多媒体系统工程师系列【原创干货持续更新中……】🚀
专题一 二：AAOS车载系统+AOSP14系统攻城狮入门视频实战课 🚀
专题三：Android14 Binder之HIDL与AIDL通信实战课 🚀
专题四：Android15快速自定义与集成音效实战课 🚀
专题五：Android15音频策略实战课 🚀
专题六：Android15音频性能实战课(无声/杂音/断音/爆音实战案例) 🚀

人生格言： 人生从来没有捷径，只有行动才是治疗恐惧和懒惰的唯一良药.

🌻1. 前言

本篇目的：Android16音频深度解析之 Equalizer.getProperties 调用流程与实战。

在 Android 均衡器开发中，频繁地逐个获取频段增益（Gain）会产生多次跨进程通信开销。其要点如下：

• 全量状态检索：该方法通过一个 Equalizer.Settings 对象，一次性获取均衡器的所有核心参数（包括当前预设、频段数及各频段增益）。
• 状态持久化基准：它是实现“保存用户自定义音效”功能的核心接口，捕获的快照可直接用于后续的状态恢复。
• 数据一致性：由于是原子操作，获取到的所有频段参数均处于同一时间截面，避免了逐个读取时可能产生的中间态差异。
• 落地建议：在应用进入后台或用户点击“保存预设”时，应优先使用此方法进行数据备份。

🌻2. 用法与应用场景

Equalizer.getProperties() 方法返回一个 Equalizer.Settings 对象，包含了均衡器当前的所有配置信息。

• 用法说明：无需参数。返回的对象包含成员：curPreset（当前预设索引）、numBands（总频段数）以及 bandLevels（各频段增益数组）。
• 运行结果：获得均衡器当前的完整配置快照。
• 应用场景：
  1. 用户预设持久化：将返回的对象序列化并保存到 SharedPreferences 或数据库中。
  2. 配置快速克隆：将一个均衡器实例的配置快速应用到另一个不同 Session 的均衡器实例。
  3. 状态备份与回滚：在用户尝试调整复杂参数前记录初始状态，以便提供“撤销”或“重置”功能。

🌻3. 调用流程剖析

3.1 核心步骤

1. Java 层块请求：应用调用 getProperties()。Equalizer.java 内部会创建一个空的 Equalizer.Settings 对象，并向底层发起批量参数获取请求。
2. JNI 批量传递：在 android_media_AudioEffect.cpp 中，该调用被转换为 GET_PARAMETER 指令，并分配足够的缓冲区来容纳整个设置块。
3. AudioFlinger 进程分发：请求通过 Binder 机制跨进程传输至 MediaServer。AudioFlinger 定位到目标音轨关联的均衡器模块。
4. 引擎库数据填充：均衡器算法引擎（如 libbundlewrapper.so）解析请求，将当前的预设索引、频段数量和增益数组依次写入缓冲区。
5. 对象属性回填：Native 层将填充后的数据包原路返回，JNI 层负责解析该字节序列，并将具体数值赋值给 Java 层 Settings 对象的成员变量。

3.2 涉及核心时序图

🌻4. 实战应用案例

public class EqPersistenceManager {
    private Equalizer equalizer;

    public void initEqualizer(int sessionId) {
        equalizer = new Equalizer(0, sessionId);
        equalizer.setEnabled(true);
    }

    /**
     * 获取并保存当前所有均衡器设置
     */
    public Equalizer.Settings captureCurrentSettings() {
        if (equalizer == null) return null;
        try {
            // 1. 一次性获取完整设置对象
            Equalizer.Settings settings = equalizer.getProperties();
            
            // 2. 打印关键信息
            System.out.println("成功捕获设置：");
            System.out.println("当前预设索引: " + settings.curPreset);
            System.out.println("包含频段总数: " + settings.numBands);
            
            for (int i = 0; i < settings.numBands; i++) {
                System.out.println(String.format("频段 %d 增益: %d mB", i, settings.bandLevels[i]));
            }
            return settings;
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }

    /**
     * 快速恢复设置
     */
    public void restoreSettings(Equalizer.Settings savedSettings) {
        if (equalizer != null && savedSettings != null) {
            try {
                // 3. 批量应用设置，效率远高于循环 setBandLevel
                equalizer.setProperties(savedSettings);
                System.out.println("均衡器状态已完整恢复");
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }

    public void release() {
        if (equalizer != null) {
            equalizer.release();
            equalizer = null;
        }
    }
}

🌻5. 用法总结

最优实战方案落地步骤：

1. 快照优先：在编写设置界面时，应通过 getProperties 获取初始状态，而不是依赖硬编码的默认值。
2. 序列化处理：由于 Equalizer.Settings 仅包含简单数据，可将其转换为 JSON 字符串保存，方便版本跨度下的兼容。
3. 状态校验：恢复设置（setProperties）前，应校验当前硬件的 numBands 是否与保存的设置一致，防止因硬件差异导致的越界异常。
4. 性能优化：在需要频繁同步 UI 状态的场景中，使用批量获取可显著减少 JNI 转换开销，降低主线程 CPU 占用。