InfinityNikkiPlayer 用户指南

无限暖暖自动演奏工具 - 让你的角色自动演奏

github仓库地址: https://github.com/Ztachi/strawberrybear-tools/tree/main/apps/infinity-nikki-player

1. 安装说明

下载地址

macOS: InfinityNikkiPlayer.dmg
Windows: InfinityNikkiPlayer.exe

macOS 安装

首次安装

点击上方 macOS 下载链接，获取 .dmg 文件
双击打开 DMG 文件
将 InfinityNikkiPlayer.app 拖入 Applications 文件夹

关于"无法验证开发者"的提示

首次打开应用时，你可能会看到以下提示：

"InfinityNikkiPlayer.app 来自未验证的开发者"

这是正常现象，原因如下：

Apple 要求所有应用都必须经过代码签名和公证才能分发
作为个人开源项目，我们没有购买 Apple 开发者账号（$99/年）
这意味着应用未经 Apple 官方认证，但这不代表应用有问题

解决方法：

看到提示后，前往 系统设置 → 隐私与安全性
滚动到底部，你会看到 "仍要打开" 按钮
点击该按钮即可运行应用

此后再打开应用就不会有任何警告了。

安全说明：我们在 GitHub 上完全开源了代码，你可以自行审查源代码，确认应用安全后再使用。

如果提示"文件已损坏"

极少数情况下可能会显示"文件已损坏"。此时在终端执行：

sudo xattr -rd com.apple.quarantine /Applications/InfinityNikkiPlayer.app

然后重新打开应用即可。

Windows 安装

点击上方 Windows 下载链接，获取 .exe 安装包
双击运行安装程序
按照安装向导完成安装

关于管理员权限

重要：Windows 版本需要以管理员身份运行才能正常模拟键盘按键。

原因：自动演奏功能需要模拟键盘输入，而 Windows 为了安全考虑，限制普通程序模拟系统级按键。通过管理员权限运行可以绕过这个限制。

设置方法：

右键点击桌面上的 InfinityNikkiPlayer 快捷方式
选择属性
切换到 兼容性 标签页
勾选 "以管理员身份运行此程序"
点击确定

或者每次运行时右键选择 "以管理员身份运行"。

2. 什么是 MIDI 文件？

MIDI（Musical Instrument Digital Interface）是一种音乐文件格式，与普通的音频文件（如 MP3、WAV）不同：

文件类型	说明	特点
MP3/WAV	存储声音本身	文件大，质量固定
MIDI	存储演奏指令	文件小，可编辑

MIDI 存储的是什么？

MIDI 文件不存储实际的声音，而是存储一系列"指令"，告诉电脑：

哪个音符（如 C4、E4）
何时按下（时间戳）
何时松开
力度多大

就像一份乐谱而不是录音。

为什么需要 MIDI 文件？

可编辑：你可以修改音符、速度、力度等参数
文件小：一首曲子只有几十 KB，比 MP3 小几十倍
可程序控制：程序可以读取 MIDI 并转换为键盘按键

如何获取 MIDI 文件？

游戏录制：在游戏中演奏并录制
网络下载：许多音乐爱好者分享 MIDI 乐谱
自行制作：使用 FL Studio、Audacity 等音乐制作软件

注意：请确保你有权使用这些 MIDI 文件。

3. 快速入门

准备工作

下载并安装应用
授予必要的权限（见下方详细说明）
准备好 MIDI 格式的乐谱文件

基本流程

导入 MIDI 文件 - 将你的乐谱文件导入应用
选择模板 - 选择与你按键布局对应的键盘映射模板
进入悬浮模式 - 切换到悬浮窗口
切换到游戏 - 将游戏窗口置于前台
开始演奏 - 点击播放，应用将自动在游戏中演奏

4. 界面介绍

主界面布局

应用主界面分为以下几个区域：

┌─────────────────────────────────────────────────────────┐
│  [logo] 无限暖暖自动演奏    [权限警告] [悬浮模式] [语言] │  <- 顶部栏
├─────────────────────────────────────────────────────────┤
│  [📁 文件]  [📋 模板]                    [导入] [导入] │  <- 标签栏
├─────────────────────────────────────────────────────────┤
│                                                         │
│                    文件列表区域                          │  <- 主内容区
│              （显示已导入的 MIDI 文件）                  │
│                                                         │
│                                                         │
└─────────────────────────────────────────────────────────┘

顶部栏

Logo 和标题：显示应用名称
权限警告按钮：当缺少必要权限时显示，点击可快速跳转设置
悬浮模式按钮：进入悬浮窗口模式
语言切换：中/英文切换

文件列表

显示所有已导入的 MIDI 文件
每个文件显示：文件名、时长、音轨数、旋律音符数
点击文件名打开详情面板
点击右侧菜单可删除文件

详情面板

从右侧滑入的详细面板，包含：

播放器控制：播放/暂停、上/下一曲、进度条、音量
模板选择：选择当前使用的键盘映射模板
键盘预览：实时显示当前按键状态
音轨管理：查看和开关各个音轨

5. MIDI 文件管理

导入文件

方法一：拖拽导入

直接将 MIDI 文件或包含 MIDI 文件的文件夹拖入应用窗口即可。

方法二：按钮导入

点击 "选择文件" 按钮
在弹出的文件选择器中选择 MIDI 文件
支持多选，可一次导入多个文件

方法三：文件夹导入

点击 "选择文件夹" 按钮
选择包含 MIDI 文件的文件夹
应用会自动扫描并导入所有 MIDI 文件

删除文件

在文件列表中找到要删除的文件
点击右侧的 菜单按钮（三个点）
选择 "删除"

注意：删除操作会将文件从应用库中移除，但不会删除你电脑原始位置的文件。

查看文件信息

点击文件名即可打开详情面板，显示：

时长：文件总播放长度
音轨数：MIDI 文件包含的音轨数量
旋律音符数：主旋律的音符数量

6. 演奏模式详解

两种演奏模式

应用提供两种不同的演奏模式，适用于不同的使用场景：

自动演奏模式（Auto）

特点：播放 MIDI 文件中的所有音符
适用场景：纯欣赏音乐、调试、预览
键盘模拟：不启用

模板演奏模式（Piano）

特点：将音符映射到特定键盘按键，并可模拟按键
适用场景：在游戏中自动演奏
键盘模拟：可启用，会在游戏中模拟按下对应的键
智能音高适配：采用移调算法 + 音域压缩，将任意 MIDI 音符适配到模板按键范围

模板演奏模式详解

模板演奏模式是本应用的核心功能。它的工作原理是：

音符映射：将 MIDI 音符转换为键盘按键
键盘模拟：在游戏中按下对应的键

智能音高适配算法

由于 MIDI 文件的音高范围很广，而游戏角色的按键数量有限，应用采用了智能算法来适配：

移调（去除黑键）：将音符映射到 C 大调音阶（只保留白键对应的音高），消除黑键差异
音域压缩：当音符超出模板范围时，自动压缩到最近的有效音高

例如：原曲中有 C4、E4、G4、B4、D5、F5

经过移调后映射到模板的 Q、W、E、R、T、Y 按键上

为什么需要权限？

macOS：

macOS 对辅助功能有严格的安全限制
应用需要访问"辅助功能"权限才能模拟键盘按键
这是 Apple 的系统级安全机制

Windows：

需要以管理员身份运行
管理员权限允许程序模拟系统级键盘事件

权限授予方法

macOS：

点击顶部栏的 权限警告按钮
或前往 系统设置 → 隐私与安全性 → 辅助功能
点击左下角 + 按钮
添加 InfinityNikkiPlayer.app
确保应用处于开启状态

如果更新后仍提示缺少辅助功能权限，但系统设置里旧的权限开关已经打开，请按以下步骤重新授权：

完全退出应用
在 系统设置 → 隐私与安全性 → 辅助功能 中删除旧的 InfinityNikkiPlayer 或 无限暖暖自动演奏 项
重新打开应用
再次点击顶部栏的 权限警告按钮 并重新授权

Windows：

见上方 Windows 安装说明

启用键盘模拟

确保已选择 模板演奏模式
在播放器控制区找到 "键盘模拟" 开关
开启开关

注意：键盘模拟仅在模板演奏模式下可用。

7. 悬浮模式

悬浮模式是专为游戏设计的窗口模式，让你在游戏时也能控制播放。

进入悬浮模式

在主界面顶部点击 "悬浮模式" 按钮
窗口会变为半透明的悬浮条
此时可以将应用窗口拖动到屏幕边缘

悬浮条功能

┌──────────────────────────────────────────┐
│  歌曲名称...        [模板▼] [✕]          │  <- 拖拽区域
├──────────────────────────────────────────┤
│  [⏮] [▶/⏸] [⏭] [⏹] [🔊] [📋]         │  <- 控制按钮
└──────────────────────────────────────────┘

拖拽区域：拖动此区域可移动窗口位置
模板选择：快速切换键盘映射模板
播放控制：播放/暂停、上/下一曲、停止
静音：临时播放器静音，以便听游戏内演奏
展开/收起：展开显示播放列表

使用技巧

将悬浮条拖动到屏幕边缘（不遮挡游戏）
展开面板，选择要演奏的曲目
切换到游戏窗口
点击悬浮条的播放按钮
3秒倒计时后开始自动演奏（给你时间切换到游戏）

退出悬浮模式

点击悬浮条右上角的 ✕ 按钮即可退出悬浮模式，恢复主界面。

8. 模板管理

什么是键盘映射模板？

模板定义了 MIDI 音符与键盘按键之间的对应关系。

不同的游戏角色可能有不同的按键布局，你需要选择与你当前角色匹配的模板。

内置模板与自定义模板

应用内置了常用的键盘映射模板：

模板类型	按键数量	适用乐器/角色
21 键模板	21 个按键	小提琴、琵琶等需要大量音符的乐器
14 键模板	14 个按键	笛子等音域相对较窄的乐器

除了内置模板，你也可以在模板标签页创建、编辑、复制、导入和导出自定义模板。自定义模板会完整保存名称、按键映射和编辑状态，适合为不同角色、乐器或个人习惯维护独立配置。

模板选择

在详情面板的模板下拉框中选择
或在悬浮模式下使用模板选择器快速切换

切换模板会立即应用到当前播放配置。悬浮模式下切换模板时，正在播放或倒计时的试听会自动停止，避免继续用旧模板输出按键。

模板列表

在主界面切换到模板标签页后，可以管理所有模板：

新建模板：创建空白模板，从头配置音符与键盘按键
从模板复制：以现有模板为基础生成一份新模板
编辑模板：进入模板编辑器调整映射
删除模板：删除不再使用的自定义模板
导入模板：导入 JSON 或压缩包中的模板配置
导出模板：导出单个模板，方便备份或分享
批量操作：多选模板后批量导出或删除

内置模板用于提供基础布局参考，建议复制后再按自己的游戏键位进行调整。

模板编辑器

模板编辑器提供 88 键钢琴画布、键盘预览和编辑工具栏，用于精确维护映射关系。

顶部区域从左到右包含：

全局预览/局部预览：在完整钢琴视图和可滚动细节视图之间切换
开始编辑/结束编辑：控制是否进入映射编辑状态
清除映射：在编辑状态下清除当前选中音符的映射
撤销/恢复：回退或恢复最近的映射变更
帮助：打开模板编辑器帮助弹窗，查看全部操作说明
映射数量：显示当前模板已经配置了多少个音符映射

画布中会高亮当前选中的音符。进入模板编辑器时，应用会自动定位到当前选中的音符；点击下方虚拟键盘或按下已经映射的实体按键时，也会同步选中并定位到对应琴键。如果琴键已经在画面内，视图不会重复滚动。

创建和编辑映射

点击 开始编辑
在钢琴画布中选择一个音符
按下你希望绑定的键盘按键
画布和下方键盘预览会立即显示新的映射
继续选择其他音符并按键，直到配置完成
点击保存或 保存并退出

每个键盘按键同一时间只会映射到一个音符。如果把已经使用的按键绑定到新音符，旧音符上的映射会自动被替换。

清除映射

清除映射属于编辑操作，只有点击 开始编辑 后才能使用。

选中一个已经映射的音符后，点击清除按钮可移除该映射
在编辑状态下，也可以按 Esc、Backspace 或 Delete 清除当前选中音符的映射
未进入编辑状态时，清除按钮会置灰，避免误删模板配置

撤销和恢复

模板编辑器会记录映射列表的历史，支持逐步撤销和恢复：

点击撤销按钮，或按 Ctrl/Cmd + Z 撤销上一步映射变更
点击恢复按钮，或按 Ctrl/Cmd + Shift + Z、Ctrl/Cmd + Y 恢复
新增映射、覆盖映射、清除映射都会进入历史
切换预览模式、选择音符、临时高亮不会进入历史
撤销后再进行新的映射操作，会清空可恢复历史
打开另一个模板、创建新模板或加载草稿时，会以当前模板内容作为新的历史起点

保存、草稿与退出

编辑模板时，如果你修改了名称或映射，应用会标记为未保存状态。

保存：保存当前模板并继续编辑
保存并退出：保存后返回模板列表
取消/关闭：如果有未保存内容，应用会提示你确认，避免误丢修改
草稿加载：重新进入未完成的模板编辑时，会恢复草稿内容，并重置撤销/恢复历史

导入和导出建议

导出模板前建议确认名称清晰，方便之后识别
导入他人模板后，先在模板编辑器中预览映射数量和按键位置
不同角色或乐器按键数量不同，导入后仍建议用一首熟悉的 MIDI 简单试听
批量导出适合备份整套模板配置，单模板导出适合分享给其他玩家

模板原理示意

音符:  C4   D4   E4   F4   G4   A4   B4   C5
       ↓    ↓    ↓    ↓    ↓    ↓    ↓    ↓
按键:  Q    W    E    R    T    Y    U    I

当你选择某个 MIDI 乐谱演奏时，应用会通过智能音高适配算法，将音符转换为对应的按键，自动在游戏中按下。

9. 音轨管理

什么是音轨？

MIDI 文件通常由多个音轨组成，常见的有：

旋律轨：包含主旋律音符
伴奏轨：包含和声、伴奏音符
打击乐轨：包含鼓点等节奏乐器（通常在第 10 音轨）

开关音轨

在详情面板中，你可以独立控制每个音轨的开关：

展开 MIDI 详情面板
找到 音轨列表 区域
点击对应音轨即可切换开关状态
被关闭的音轨不会发出声音

使用场景

只听旋律：关闭其他音轨，只保留主旋律
排除干扰：某些 MIDI 文件可能包含你不想要的音轨，可以关闭
调试排查：逐个开关音轨，检查问题出在哪里

音轨识别

标注为 "打击乐" 的是鼓组音轨
其他音轨按序号标识（音轨 1、音轨 2...）

10. 常见问题

Q: 为什么音乐播放的速度和原曲不一样？

A: 这可能是 MIDI 文件本身的问题。不同的 MIDI 文件可能有不同的速度标记，导致播放速度不一致。此外，部分 MIDI 文件可能不包含速度信息，应用会使用默认速度。

Q: 为什么有些音符没有声音？

A: 请检查：

是否选择了正确的键盘映射模板
模板演奏模式下，音符会被过滤到模板定义的音高范围内
切换到自动演奏模式可以播放所有音符

Q: 悬浮模式窗口消失了怎么办？

A: 尝试：

检查窗口是否被拖动到了屏幕边缘
在应用列表中找到并切换回来
重新启动应用

Q: macOS 提示"辅助功能权限"后应用崩溃？

A: 请确保：

在系统设置中已正确添加应用
应用的权限开关已开启
尝试完全退出应用后重新打开

如果是更新后出现权限异常，请先在 系统设置 → 隐私与安全性 → 辅助功能 中删除旧的应用项，然后重启应用并重新授权。

Q: Windows 键盘模拟不生效？

A: 请确认：

应用是否以管理员身份运行
Windows Defender 或其他安全软件是否拦截了键盘模拟

Q: 如何获得更多 MIDI 乐谱？

A: 你可以从以下来源获取 MIDI 文件：

音乐制作软件导出
音乐爱好者分享的乐谱库
自行制作（需要 MIDI 编辑软件）

注意：请确保你有权使用这些 MIDI 文件进行演奏。

技术支持

如果你在使用过程中遇到其他问题，可以通过以下方式获得帮助：

QQ：414135950
在 GitHub 仓库提交 Issue
查看项目的 README 文档

InfinityNikkiPlayer - 让音乐在游戏中自由流淌

无限暖暖自动演奏工具