音乐节拍摆动与跳舞调参

目标：学会调节音乐联动——节拍摆动幅度/关节、跳舞触发阈值，让 LeLamp 跟着音乐"律动"但不过度

一、两个层次的音乐联动

LeLamp 的音乐响应分两层：

1. 节拍摆动（默认）：播放音乐时，手腕关节（wrist_pitch）随节拍小幅摆动——像跟着音乐轻轻打拍子。任何音乐都会触发（在线/本地/Spotify）。
2. 跳舞动画（可选）：音乐能量足够强时才触发完整跳舞动画（dance_normal / dance_excited，10 秒循环）。轻柔音乐不会跳。

二、节拍摆动配置

在 ~/.lelamp/config.yaml 的 modifiers.music 段：

modifiers:
  music:
    enabled: true                 # 播放音乐时自动开启摆动
    joints: ["wrist_pitch.pos"]   # 摆动的关节（当前用 5 号手腕）
    amplitude: 8.0                # 摆动幅度（归一化值，越大摆得越猛）
    beat_divisor: 1.0             # 1=每拍摆一次；2=每两拍
    groove: 0.3                   # 0-1 摇摆感（次谐波）
    wave_spread: 0.08             # 多关节时关节间相位差（波浪效果）
    energy_threshold: 0.15        # 音乐能量低于此值不摆动

多关节：代码支持 joints 填多个关节（如 ["wrist_pitch.pos", "base_pitch.pos", "elbow_pitch.pos"]）形成波浪摆动；当前默认只用手腕单关节，想加回改这一行即可。

常见调节：

• 摆动太猛 → amplitude 调小（如 5.0）
• 摆动太快/太慢 → beat_divisor 2=隔拍摆
• 在线音乐摆动不明显 → 确认 energy_threshold 是 0.15（在线音乐保守能量 0.4，只要阈值低于它就有摆动）

三、跳舞触发阈值

modifiers:
  music:
    dance_threshold: 0.45    # 音乐能量超过此值触发跳舞动画
    excited_threshold: 0.6   # 能量超过此值跳更嗨的 dance_excited

• 能量来源：本地文件用 ffmpeg 真实分析 RMS 能量（强节奏能量高）；在线音乐无法分析，用保守值 0.4
• 默认设计：0.4（在线）< 0.45（跳舞阈值）→ 在线音乐只摆动不跳舞；本地强节奏歌（能量 > 0.45）才会跳舞
• 想更容易跳舞 → 调低 dance_threshold（如 0.35）；想更安静 → 调高（如 0.6）

四、跳舞动画本身

• 内置两支舞：dance_normal（常规，幅度收敛版）和 dance_excited（更嗨）
• 每支 300 帧（10 秒），无缝循环
• 跳舞时 RGB 灯效联动（bpm_pulse / energy_wave）
• 想改舞步：动画页面播放/录制，或用 AI 生成器生成新动画后设为跳舞动画

五、常见问题