Android 原生安全音量功能实现原理与定制分析

public void onSystemReady() {
    ...
    sendMsg(mAudioHandler,
        MSG_CONFIGURE_SAFE_MEDIA_VOLUME_FORCED,
        SENDMSG_REPLACE,
        0,
        0,
        TAG,
        SystemProperties.getBoolean("audio.safemedia.bypass", false) ?
            0 : SAFE_VOLUME_CONFIGURE_TIMEOUT_MS);
    ...
}

这里有一个关键属性 audio.safemedia.bypass。如果该属性为 true，则跳过超时等待直接执行；否则，会等待 SAFE_VOLUME_CONFIGURE_TIMEOUT_MS 毫秒后再执行配置，确保系统在完全就绪后处理。

2. 配置阶段：onConfigureSafeVolume

收到 MSG_CONFIGURE_SAFE_MEDIA_VOLUME_FORCED 消息后，AudioService 会执行 onConfigureSafeVolume(boolean force, String caller) 方法。该方法负责读取配置并更新内部状态。

private void onConfigureSafeVolume(boolean force, String caller) {
    synchronized (mSafeMediaVolumeStateLock) {
        // Mobile country code，国家代码，用于区分不同国家的策略
        int mcc = mContext.getResources().getConfiguration().mcc;
        
        // 只有当 MCC 改变或首次启动时才重新配置
        if ((mMcc != mcc) || ((mMcc == 0) && force)) {
            // 获取 config_safe_media_volume_index 中的阈值，乘以 10 作为实际比较值
            mSafeMediaVolumeIndex = mContext.getResources().getInteger(
                    com.android.internal.R.integer.config_safe_media_volume_index) * 10;

            mSafeUsbMediaVolumeIndex = getSafeUsbMediaVolumeIndex();

            // 决定使能状态：优先使用系统属性，其次使用 XML 配置
            boolean safeMediaVolumeEnabled =
                    SystemProperties.getBoolean("audio.safemedia.force", false)
                    || mContext.getResources().getBoolean(
                            com.android.internal.R.bool.config_safe_media_volume_enabled);

            // 检查是否被强制绕过
            boolean safeMediaVolumeBypass =
                    SystemProperties.getBoolean("audio.safemedia.bypass", false);

            int persistedState;
            if (safeMediaVolumeEnabled && !safeMediaVolumeBypass) {
                persistedState = SAFE_MEDIA_VOLUME_ACTIVE; 
                // 如果之前已确认过安全警告，且未超时，则保持 inactive 状态
                if (mSafeMediaVolumeState != SAFE_MEDIA_VOLUME_INACTIVE) {
                    if (mMusicActiveMs == 0) { 
                        mSafeMediaVolumeState = SAFE_MEDIA_VOLUME_ACTIVE;
                        enforceSafeMediaVolume(caller);
                    } else {
                        mSafeMediaVolumeState = SAFE_MEDIA_VOLUME_INACTIVE;
                    }
                }
            } else {
                persistedState = SAFE_MEDIA_VOLUME_DISABLED;
                mSafeMediaVolumeState = SAFE_MEDIA_VOLUME_DISABLED;
            }
            mMcc = mcc;
            // 持久化当前状态到 Settings.Global
            sendMsg(mAudioHandler,
                    MSG_PERSIST_SAFE_VOLUME_STATE,
                    SENDMSG_QUEUE,
                    persistedState,
                    0,
                    null,
                    0);
        }
    }
}

关键点解析：

1. MCC 检测：通过移动国家代码判断是否需要重新加载配置，支持多区域部署。
2. 优先级：系统属性（System Properties）的优先级高于 XML 配置，方便 OTA 升级时动态调整而不需重刷 ROM。
3. 状态持久化：配置结果会通过 MSG_PERSIST_SAFE_VOLUME_STATE 消息保存到 Settings.Global.AUDIO_SAFE_VOLUME_STATE 中，确保重启后状态可恢复。

3. 持久化逻辑

case MSG_PERSIST_SAFE_VOLUME_STATE:
    onPersistSafeVolumeState(msg.arg1);
    break;

private void onPersistSafeVolumeState(int state) {
    Settings.Global.putInt(mContentResolver,
            Settings.Global.AUDIO_SAFE_VOLUME_STATE,
            state);
}

持久化的状态值只能是 active 或 disabled，不存在 inactive 的持久化记录，因为 inactive 是临时状态。

安全音量触发机制

在实际操作中，安全音量的触发条件是'音量增大到指定值'。这一逻辑在 AudioService 处理音量调节请求时执行。

1. 调节音量接口

当用户操作音量键或通过 API 调节音量时，最终会调用 AudioService 中的 adjustStreamVolume 或 setStreamVolume 方法。

adjustStreamVolume 逻辑：

protected void adjustStreamVolume(int streamType, int direction, int flags,
        String callingPackage, String caller, int uid) {
    ...
    } else if ((direction == AudioManager.ADJUST_RAISE) &&
            !checkSafeMediaVolume(streamTypeAlias, aliasIndex + step, device)) {
        Log.e(TAG, "adjustStreamVolume() safe volume index = " + oldIndex);
        mVolumeController.postDisplaySafeVolumeWarning(flags);
    ....
}

当方向为上升（ADJUST_RAISE）且 checkSafeMediaVolume 返回 false 时，直接触发警告弹窗。

setStreamVolume 逻辑：

private void setStreamVolume(int streamType, int index, int flags, String callingPackage,
            String caller, int uid) {
    ....
    if (!checkSafeMediaVolume(streamTypeAlias, index, device)) {
        mVolumeController.postDisplaySafeVolumeWarning(flags);
        mPendingVolumeCommand = new StreamVolumeCommand(
                                            streamType, index, flags, device);
    } else {
        onSetStreamVolume(streamType, index, flags, device, caller);
        index = mStreamStates[streamType].getIndex(device);
    }
    ....
}

当传入的音量索引大于安全阈值时，同样触发警告，但会将请求暂存到 mPendingVolumeCommand 中，待用户确认后应用。

2. 核心判断条件：checkSafeMediaVolume

private boolean checkSafeMediaVolume(int streamType, int index, int device) {
    synchronized (mSafeMediaVolumeStateLock) {
        // 1. 功能是否处于激活状态
        if ((mSafeMediaVolumeState == SAFE_MEDIA_VOLUME_ACTIVE) &&
            // 2. 是否为媒体音频流
            (mStreamVolumeAlias[streamType] == AudioSystem.STREAM_MUSIC) &&
            // 3. 设备类型是否匹配
            ((device & mSafeMediaVolumeDevices) != 0) &&
            // 4. 音量是否超过阈值
            (index > safeMediaVolumeIndex(device))) {
            return false; // 不满足安全条件，触发警告
        }
        return true; // 满足安全条件
    }
}

判断依据详解：

1. 状态变量：mSafeMediaVolumeState 必须为 SAFE_MEDIA_VOLUME_ACTIVE。
2. 音频流类型：仅针对 STREAM_MUSIC，通话、闹钟等不受影响。
3. 设备类型：默认只针对有线耳机、蓝牙耳机及 USB 耳机。

   /*package*/ final int mSafeMediaVolumeDevices = AudioSystem.DEVICE_OUT_WIRED_HEADSET
           | AudioSystem.DEVICE_OUT_WIRED_HEADPHONE
           | AudioSystem.DEVICE_OUT_USB_HEADSET;
   

   如需对扬声器（Speaker）启用安全音量，需修改此常量。
4. 音量阈值：当前音量 Index 必须超过 safeMediaVolumeIndex(device) 的值，该值源自 config_safe_media_volume_index。

UI 交互与警告弹窗

当满足触发条件时，AudioService 通过远程服务 mVolumeController 通知 UI 层显示警告对话框。最终入口在 VolumeDialogImpl.java 的 showSafetyWarningH 方法中。

public class VolumeDialog {
    ...
    private void showSafetyWarningH(int flags) {
        if ((flags & (AudioManager.FLAG_SHOW_UI | AudioManager.FLAG_SHOW_UI_WARNINGS)) != 0
                || mShowing) {
            synchronized (mSafetyWarningLock) {
                if (mSafetyWarning != null) {
                    return;
                }
                mSafetyWarning = new SafetyWarningDialog(mContext, mController.getAudioManager()) {
                    @Override
                    protected void cleanUp() {
                        synchronized (mSafetyWarningLock) {
                            mSafetyWarning = null;
                        }
                        recheckH(null);
                    }
                };
                mSafetyWarning.show();
            }
            rescheduleTimeoutH();
        }
    }
    ...
}

UI 行为特性：

1. 抢占焦点：弹窗会抢占当前 UI 焦点，阻止用户操作其他界面元素。
2. 确定按钮：点击确定后，调用 disableSafeMediaVolume() 暂时关闭安全音量警告。此时系统会启动一个计时器（默认为 20 分钟或根据配置），在此期间内允许音量继续调大而不触发警告。计时结束后，功能自动恢复。
3. 取消按钮：点击取消后，音量设置不会生效，再次尝试调大音量时，警告框会重复弹出。

disableSafeMediaVolume 深度解析

点击确定后的处理逻辑在 AudioService 的 disableSafeMediaVolume 方法中。

public void disableSafeMediaVolume(String callingPackage) {
    enforceVolumeController("disable the safe media volume");
    synchronized (mSafeMediaVolumeStateLock) {
        setSafeMediaVolumeEnabled(false, callingPackage);
        if (mPendingVolumeCommand != null) {
            onSetStreamVolume(mPendingVolumeCommand.mStreamType,
                              mPendingVolumeCommand.mIndex,
                              mPendingVolumeCommand.mFlags,
                              mPendingVolumeCommand.mDevice,
                              callingPackage);
            mPendingVolumeCommand = null;
        }
    }
}

执行步骤：

1. 权限校验：调用 enforceVolumeController 确保调用者具有相应权限。
2. 状态变更：调用 setSafeMediaVolumeEnabled(false) 将内部状态置为无效，暂时停止检查。
3. 恢复挂起命令：如果之前有因警告而挂起的音量设置命令（mPendingVolumeCommand），此时将其应用到系统中，确保用户设置的音量最终生效。

开发者定制指南

对于 OEM 厂商或需要特殊场景适配的开发者，以下是常见的定制方案：

1. 修改默认阈值

直接在 frameworks/base/core/res/res/values/config.xml 中修改 config_safe_media_volume_index 的值。例如，将阈值从 10 调整为 15，意味着只有在音量达到更高水平时才会报警。

2. 全局禁用功能

通过系统属性 audio.safemedia.force 设置为 false，或者在 config.xml 中将 config_safe_media_volume_enabled 设为 false。这适用于某些不需要合规性检查的市场或特定设备型号。

3. 添加新设备类型支持

如果需要针对扬声器开启安全音量，需修改 AudioService 中的 mSafeMediaVolumeDevices 常量，加入 AudioSystem.DEVICE_OUT_SPEAKER。

4. 绕过测试

在调试过程中，可通过 ADB 命令临时绕过安全音量限制：

adb shell setprop audio.safemedia.bypass true

这将导致系统忽略安全音量检查，直到下次重启。

常见问题排查

1. 弹窗无法消失：检查 mSafetyWarning 对象是否被正确释放。有时由于内存泄漏或死锁，可能导致弹窗常驻。
2. USB 设备未触发：确认 mSafeMediaVolumeDevices 是否包含 DEVICE_OUT_USB_HEADSET。部分第三方 USB 音频驱动可能上报不同的设备类型码。
3. 重启后失效：检查 Settings.Global.AUDIO_SAFE_VOLUME_STATE 是否正确写入。如果存储权限异常，可能导致状态丢失。
4. 倒计时不准确：mMusicActiveMs 的计数依赖于系统时间同步。如果设备时间频繁变动，可能会影响 20 分钟倒计时的准确性。

小结

Android 原生的安全音量功能是系统层面保护用户听力的重要机制。它默认强制开启，在插入耳机后，当音量调节超过指定阈值时，会触发全屏警告弹框。该弹框会抢占焦点，强制用户做出选择。点击确定后，系统允许暂时提升音量，但会启动倒计时（通常为 20 分钟），倒计时结束后功能自动恢复。对于系统开发者而言，理解 AudioService 中的状态机流转、配置读取逻辑以及 UI 交互链条，是实现定制化开发和故障排查的关键。