Skip to content

installation.md

Latest commit

 

History

History
146 lines (108 loc) · 7.65 KB

installation.md

File metadata and controls

146 lines (108 loc) · 7.65 KB
Raw

安装、升级与卸载

1. 前置条件

  • Xiaomi HyperOS，Android 15（API 35）或更高版本；
  • root 环境可正常使用；
  • LSPosed API 101 或更高版本；
  • 能够在系统异常时进入安全模式或通过 ADB 禁用模块；
  • 目标耳机已经通过系统蓝牙完成配对。

HyperEars 的必选核心作用域只有：

com.android.bluetooth
com.milink.service

从 3.0.0 起，模块另外声明可选作用域 com.xiaomi.bluetooth（系统蓝牙扩展）。 启用“连接时显示”或“耳机电量通知”时需要勾选它，并重启对应宿主进程。 “连接时显示”默认使用“智能”，也可选“仅弹窗”“仅超级岛”或“关闭”； 耳机电量通知默认关闭。无需勾选 System UI 或系统设置。

可选作用域见厂商控制 App 与 LSPosed 作用域。只选择设备上实际安装、 且确实会用于控制当前耳机的 App；同一品牌存在多个候选包名时，选择实际使用的版本即可。 控制 App 作用域只安装进程存活 Hook，用于控制权仲裁；不会 Hook 厂商界面、协议实现或 蓝牙业务，也不会主动建立蓝牙连接。仅打开已安装控制 App 的页面不依赖作用域，但运行时 退避必须依赖已 Hook 进程的 Binder 登记。

请勿为了“提高兼容性”额外勾选系统设置、System UI 或所有应用。扩大作用域不会增加 功能，只会增加不必要的注入面。

2. 下载与校验

只从项目 GitHub Releases 下载：

HyperEars-vX.Y.Z.apk
HyperEars-vX.Y.Z.apk.sha256

PowerShell 校验：

Get-FileHash .\HyperEars-vX.Y.Z.apk -Algorithm SHA256
Get-Content .\HyperEars-vX.Y.Z.apk.sha256

两者的十六进制摘要必须一致。不要安装只提供 APK、不提供来源和校验和的重打包版本。

3. 首次安装

  1. 安装 APK。
  2. 打开 LSPosed，启用 HyperEars。
  3. 确认核心作用域为 com.android.bluetooth 和 com.milink.service。使用连接展示或电量通知时， 勾选 com.xiaomi.bluetooth。需要控制 App 退避时， 再按控制 App 目录勾选对应的已安装厂商控制 App。
  4. 重启整台设备。
  5. 连接耳机，打开 HyperEars 运行看板。
  6. 确认卡片中的 Adapter、形态、传输与控制能力符合目标设备；观察“耳机链路”及 “MiLink 处理”各阶段。需要私有协议的型号都应完成“协议确认”；私有电量和噪声模式 分别在对应合法状态响应到达后开放。

开启“运行时退避”且控制 App 进程成功登记后，看板会显示“专有控制 App 运行中”，私有 通道变为“不需要”，卡片只保留标准耳机能力。该状态由控制 App 进程 Binder 存活判定， 与厂商 App 是否已经连接耳机无关；控制 App 的所有进程退出后自动恢复。

模块不负责首次蓝牙配对。耳机必须先能在系统蓝牙页面正常连接和播放声音。

4. 设置与快捷控制

设置页提供以下策略：

  • 连接时显示：默认智能，按系统场景在桌面／外屏桌面显示弹窗，在应用内显示超级岛； 也可选仅弹窗、仅超级岛或关闭。需要系统蓝牙扩展作用域，且受宿主显示条件限制。
  • 耳机电量通知：默认关闭，与连接展示独立；通知可以清除，后续状态回报可重新发布。
  • 点击卡片“更多设置”：通过下拉选项选择打开系统设置、厂商 App 或 HyperEars； 电量通知和连接弹窗内容区的点击也使用此选择。默认为系统设置，目标不可用时回退到真实 蓝牙设备详情；打开目标后关闭对应弹窗。
  • 运行时退避：厂商控制 App 运行时自动让出耳机私有控制通道；控制 App 进程全部退出后自动恢复。该功能要求勾选对应厂商 App 作用域，不观察厂商 App 是否已经 创建蓝牙连接。
  • 自动检查更新：默认开启，只在打开 HyperEars 时访问 GitHub Releases，且每天最多一次。

“调试”是独立的二级页面，包含“适配器”“详细日志”“导出日志”和原生提示预览。“调试 > 适配器” 按品牌折叠组织全部具体型号、家族回退和标准回退 Adapter，可分别启用或停用；每个品牌的总开关 可一次停用或恢复该组全部 Adapter。关闭具体型号后，设备继续尝试同品牌的家族 Adapter；关闭 相应家族 Adapter 后继续尝试标准回退。重新启用 后，当前仍连接的设备会使用原始身份重新解析。关闭“标准蓝牙耳机”会让没有其他可用适配的 设备不进入 HyperEars 会话。

“返回桌面”“按返回键”和“从最近任务划走”都不保证控制 App 进程退出。使用完厂商 App 后， 如需立即恢复 HyperEars 私有控制，应手动强制停止该 App，或使用下方需要 Root 的“停止厂商 应用”。HyperEars 不会自动结束厂商 App。完整条件与状态矩阵见 控制 App 作用域文档。

“暂停模块”默认关闭。开启后，Bluetooth 进程关闭全部 HyperEars 会话和私有协议通道， MiLink 进程清空模块状态并回到原生处理；Android 的蓝牙配对、A2DP/HFP 音频和系统音量不受 影响。恢复后需重新连接耳机，或使用设置页的“重启蓝牙”重新触发设备会话。

设置页还提供三个需要 Root 的快捷操作：重启 MiLink、重启蓝牙、停止已支持的厂商控制 App。 “导出日志”位于“调试”页面。没有 Root 时 Root 操作和日志导出显示为禁用状态；快捷控制结果 不常驻显示在设置页，只在“详细日志”开启时写入应用日志。重启蓝牙会重新加载系统蓝牙和 系统耳机服务，并验证旧宿主进程已退出；当前蓝牙设备会暂时断开， 停止控制 App 会触发其 Binder death，从而释放外部控制权。

开启“详细日志”时，LSPosed 还需要关闭“禁用详细日志”，并开启“输出日志到守护进程”。 “Xposed API 调用保护”可以保持开启。排查完成后建议关闭 HyperEars 的详细日志开关。

5. 从开发测试包迁移

首个公开 Release 使用独立发布证书。早期由本地 debug 证书签名的测试包无法直接覆盖 安装，Android 通常会提示签名不一致。迁移顺序：

  1. 在 LSPosed 中禁用旧版 HyperEars；
  2. 重启设备；
  3. 卸载旧 APK；
  4. 安装 GitHub Release APK；
  5. 在 LSPosed 中重新启用两个核心作用域，以及 控制 App 目录中实际使用的可选作用域；
  6. 再次重启设备。

这不会解除系统保存的耳机蓝牙配对。

6. 正常升级

同一公开签名链下的后续版本可以直接覆盖安装。升级后建议重启设备，因为蓝牙进程和 MiLink 进程可能仍持有旧模块代码。若版本说明明确要求重新配对，再单独执行该步骤； 普通升级不要先清除蓝牙系统数据。

7. 卸载

  1. 在 LSPosed 中禁用 HyperEars；
  2. 重启设备，确认系统蓝牙与 MiLink 恢复原生行为；
  3. 卸载 HyperEars APK。

不要清除 com.android.bluetooth 数据，除非你明确愿意丢失系统蓝牙配对记录。

8. 安全恢复

如果启用模块后系统界面或蓝牙进程持续崩溃：

  1. 使用 LSPosed 安全模式禁用模块；或
  2. 通过 ADB 卸载 dev.hyperears；或
  3. 在恢复环境中按所用 root/LSPosed 方案禁用对应模块。

恢复后请按 问题排查 采集版本与崩溃信息，再提交 Issue。