震动跟着鼓点走：spoti.pw Music Haptics实时音频分析与触觉反馈实战

spoti.pw 是一款免越狱的 Spotify iOS 修改插件（基于 Liquid Glass UI 的 Theos tweak），它的 Music Haptics 功能能让手机的 Taptic Engine 跟着歌曲实时"演奏"：每一次鼓点一声轻敲、每一段贝斯一层低频震动，全部由实时音频分析从声音中"听"出来。本文讲清 Music Haptics 的开关设置、背后的实时音频分析原理，以及它在测试夹具中的验证方式。

📳 功能速览：手机跟着鼓点一起"演奏"

Apple Music 有官方的 Music Haptics，而 spoti.pw 在 Spotify 上把同样的体验做出来了，而且更进一步：不依赖任何预标注的元数据，而是边播放边分析声音，自己听出鼓点在哪里。

开启后的实际效果：

• 🥁 每一下底鼓、军鼓对应一次清脆的敲击震动，力度随真实响度变化
• 🔊 持续的贝斯段落对应一层连续的低频轰鸣，轰鸣强度跟着贝斯电平起伏
• 🎛️ 强度可在 20% 到 200% 之间调节，跟随模式三选一

设置入口在Mod Settings → Player → Vibrations，整张卡片在 HapticsSettings.m 中组装。

🚀 快速上手：开启音乐触觉反馈的三个步骤

1. 构建修改版：准备一个已解密的Spotify 9.1.78IPA，放入ipa/目录后执行make release，生成可用 SideStore、Feather 等证书工具签名的 IPA（完整流程见 README.md 的 Build it 一节）。
2. 打开开关：Mod Settings → Player → Vibrations，打开Music Haptics开关。开关即时生效，无需重启应用。
3. 微调手感：调整Strength（20%～200%，100% 为出厂手感），并从下面三种Follows模式中挑选：

三种模式的定义见 Haptics.h。

🧠 核心原理：如何从声音里"听"出鼓点

1️⃣ 监听 Spotify 的音频输出链路

Spotify 通过自己的 Core Audio 单元（二进制的AudioUnitDriver2，含混响、EQ、混音和 RemoteIO 输出单元）播放音频，它与单元之间没有任何 Objective-C 方法可供挂钩，常规的方法 Hook 无处下手。

spoti.pw 的办法是重绑定导入（rebinding import）：接管 Spotify 对AudioOutputUnitStart的导入槽（见 SGRebind.h），Spotify 每启动一个 RemoteIO 单元，就给它挂上一个render notify——每渲染完一块缓冲区，就把它按硬件输出格式（通常是 48 kHz float）混缩成单声道，交给渲染线程上的分析器。这条"监听线"的主体在 MusicHaptics.x。

2️⃣ 分析器：分辨底鼓与军鼓的"耳朵"

SGMusicAnalyzer 用纯 C 编写、跑在 Core Audio 的渲染线程上，全程不分配、不加锁、不打日志。思路是把声音切成两个频段：

• 低频段（<110 Hz）：底鼓、808 鼓的家
• 高频段（>2 kHz）：军鼓、拍手声的家

判定"一击"的规则：某频段最近 25 ms 的能量明显高于它自己过去 1 秒的平均值，并且要等能量回落过均值后才允许再次触发。高频段还多一个条件——中频（250 Hz～2 kHz）必须跟着一起抬升，军鼓和拍手会这样，踩镲不会，由此过滤掉高频"碎响"（原理见 SGMusicAnalyzer.h 的注释）。

分析器输出两类事件：tap（底鼓/军鼓一击，带力度 intensity 与锐度 sharpness）和level（贝斯包络，每秒约 60 次，供轰鸣使用），存进 1024 槽的事件环形队列（见 MusicHaptics.x）。

3️⃣ 时序校准：震动必须落在"听见"的那一瞬间

震动晚到，比不震更难受。spoti.pw 做了三层时间补偿：

1. 渲染时间戳：每块缓冲区的 AudioTimeStamp 指明这段声音何时到达扬声器，事件因此拿到精确的"被听见时刻"；
2. 加上输出延迟：读取AVAudioSession.outputLatency（蓝牙场景下可达数十毫秒）加上去，音频路由变化时重新读取；
3. 减去电机响应：Core Haptics 从排期到 Taptic Engine 达到峰值约需 12 ms（kHapticLead）；一旦某次敲击已迟到超过 50 ms（kLatestTap），直接丢弃，宁可漏一拍也不打乱节拍（常量定义见 MusicHaptics.x）。

最后由一条专属 player 线程从环形队列取事件、用 Core Haptics 按时刻排期：敲击是一次性 transient 事件，贝斯轰鸣是一个循环 continuous 事件，强度参数随电平动态下发。轰鸣还带"起振阈值 0.05、回落到 0.02 以下 0.3 秒才停"的机制，安静段落自然归于平静。

🧪 实测与验证：harness 里的打分流程

实时分析器不是靠耳朵调出来的。仓库在 harness/haptics/ 里备了两套验证：

• Mac 端打分：把与 tweak 完全一致的分析器放在 Mac 上跑，对解码后的整首歌输出事件 CSV，再由 score.py 用 mir_eval 与 librosa 标注的 onsets 逐一对比（50 ms 容差窗口），并与"同密度的随机敲击"基线对照。调优后的分析器在 172 BPM 曲子上稳定输出约 3.3 次敲击/秒，precision 0.88、recall 0.82；合成 124 BPM 节拍中，58 个底鼓命中 57 个、29 个军鼓全部命中，且零踩镲误报。
• 模拟器端挂钩验证：harness/haptics/sim/ 用真实音频单元复刻 Spotify 的播放链，以假的 Core Haptics "计数"实际请求，逐项验证三种 Follows 模式、50%/200% 强度、开关切换和 16 位交织输入，全部通过。

⚠️ 使用注意：这些时候它不会震

• 📱仅在前台生效：iOS 不为后台应用播放震动，Spotify 失去前台焦点时监听会立刻停止。
• 📡Connect / AirPlay 播放不跟震：歌曲在另一台设备上播放时，本地没有声音经过输出单元，自然无从跟随（说明见 HapticsSettings.m）。
• 📟设备需支持 Taptic Engine：代码启动时会检查 Core Haptics 硬件能力，不支持的设备静默保持关闭（见 MusicHaptics.x）。
• ⚡一切设置实时生效：开关、强度、Follows 的修改都作用于下一个事件，无需重启。

📁 相关文件一览

一句话总结：Music Haptics 把"听"（渲染线程上的分析器）、"校准"（时间戳 + 延迟补偿）、"弹"（独立线程 + Core Haptics）拆在三个线程各司其职——这正是震动"踩在鼓点上"和"随机乱震"之间、毫秒级工程差距的全部所在。