让观众在哔哩哔哩直播间发送 点歌 曲名，主播的游戏就会在选曲界面自动定位到对应歌曲。多首点歌按顺序排队；由主播决定是否开始游玩。

OBS 网页演示

游戏内 Overlay

• 第一次安装
• 观众怎么点歌
• 主播日常使用
• 常用设置
• 常见问题

1. 打开 下载页面。
2. 展开对应版本的 Assets，下载 chart-requester-版本号.zip，例如 chart-requester-0.2.0.zip。Source code 是源代码，安装时不需要下载。
3. 将 ZIP 解压到本机一个可以保存文件的文件夹。

解压后有三项：chart_requester.dll、chart_request_static 网页目录和 README.md 使用说明。DLL 由启动器加载，不需要双击打开，也无需准备配置文件。

1. 用主播账号登录 哔哩哔哩身份码页面，复制自己的身份码。找不到入口时，可参考 blivechat 的获取说明。
2. 稍后在游戏内控制台粘贴身份码。默认连接方式不需要填写直播间号。

无需创建或编辑配置文件，插件会自动保存设置。身份码不要展示在直播画面或发到弹幕里。

确定游戏还没有启动，把 DLL 和 chart_request_static 目录一起放进游戏根目录的 modules 目录下，然后在 bat 或者 spicecfg 里引入这个 DLL 文件。请使用支持 SDK v0.4 D3D9 绘制回调的 Spice2x，以便打开配置界面。

spice64.exe -k chart_requester.dll

• 用 .bat 文件启动： 右键该文件，选择编辑，找到运行 spice64.exe 的那一行，在该行末尾加一个空格，再加上面的参数。
• 用 spicecfg 启动： 启动 spicecfg, 选择 options 选项卡，在 inject dll hook 选项填入 chart_requester.dll。

如果解压到了其他位置，把路径改成你自己的 DLL 完整路径。无需替换游戏的 bm2dx.dll。

1. 按平时的流程开启直播，并用刚修改的启动方式打开游戏。
2. 进入单人 SP 普通选曲界面，双击另一侧的 Start：1P 登录就双击 2P Start，反之亦然。
3. 在控制台选择「直播连接」，粘贴身份码，点击 「应用并保存」。
4. 确认顶部显示 「弹幕已连接」，即可关闭控制台开始点歌。无需重启游戏。

看到 「弹幕已连接」 表示连接成功。插件运行后会自动生成以下文件：

如果文件没有生成，或出现错误，先看下方的 常见问题。

游戏启动后，用浏览器打开 http://127.0.0.1:32133/queue，即可查看实际点歌状态。

1. 在 OBS 当前场景的「来源」中点击 ＋，添加「浏览器」，命名为「点歌队列」。
2. 不勾选「本地文件」，在 URL 中填写 http://127.0.0.1:32133/queue，宽度设为 480、高度设为 800。
3. 将来源摆放到直播画面的合适位置。上方显示点歌和候选，下方显示弹幕与事件；内容限制在来源高度内，未使用的空间保持透明。

有待选歌曲时，上方暂时隐藏当前点歌和队列，完整展示这位观众的所有候选，并反转为主题色背景、深色文字，醒目提示 「请在弹幕发送编号选歌」。较多候选使用两列，编号不分页；多人同时待选时每 6 秒轮换一位观众。全部选择完成或超时后自动恢复队列及原配色，下方弹幕区域始终保留。

空闲时点歌区默认收成一行标题，只有当前点歌时保留紧凑的歌曲卡片；队列或候选出现时平滑展开，清空后平滑收起。弹幕区没有弹幕或事件时也只保留标题，背景随实际条数平滑增高，最多占用剩余空间；断线提示仍会显示。系统启用「减少动态效果」时直接切换。

普通弹幕和点歌事件按到达顺序共同保留，默认最多 10 条，第 11 条到达时移除最早一条，不按时间消失。弹幕使用 16px 字号、较高卡片和上下各 5px 内边距；事件使用 12px 字号与窄卡片。背景按两种卡片的实际数量增减，长内容根据可用高度截断。可在「OBS 显示」调整「网页弹幕与事件保留条数」；增加条数时建议相应增加来源高度。

刷新网页会恢复本次运行的最近记录，短暂断线也保留已显示的内容。切换直播档案或重新启动游戏后清空记录。

当前仅支持 OBS 和游戏运行在同一台电脑。

如果喜欢纯文字方式，可添加两个「文本（GDI+）」来源，勾选「从文件读取」，分别选择 DLL 所在文件夹下的 obs/queue.txt 和 obs/interaction.txt，再自行设置字体与颜色。

在自己的直播间发送：

点歌 AA

如果出现多首候选，由发送这条弹幕的同一个账号再发送一个编号，例如 1。队列空闲且游戏处于可操作的选曲界面时，游戏会定位到选中的歌曲；有其他点歌时则加入等待队列。

能看到提示、选出歌曲并完成定位，就可以开始使用了。

发送 点歌、一个空格，再加曲名：

点歌 冥
点歌 AA SPA
点歌 AA -rebuild- DPA

难度可以不填，不填时使用主播当前的 SP/DP 模式，并沿用游戏当前难度选择。指定难度时，使用下表中的写法，大小写均可：

主播正在 SP 模式时点 DP 的歌会被直接跳过，反之亦然。不存在、未解锁或当前模式不可用的谱面会提示失败。

曲名支持模糊匹配，可以省略部分字符，但保留的字符顺序要一致。遇到多首候选时，提示会显示编号，例如：

1. AA
2. AA -rebuild-

由点歌的同一个账号，在默认 60 秒内只发送编号，例如 2。其他人的回复不会替你选择。即使输入了完整曲名，只要还有其他候选，也需要选择。

超时后重新发送点歌命令即可。等待选择时再次点歌，会替换自己上一次尚未确认的选择。

每次开播时，启动游戏、进入普通选曲界面，确认「弹幕已连接」，并确认 OBS 点歌面板能正常显示。

• 点歌按先后排队。 默认最多等待 20 首，队列满时新请求会收到提示。
• 定位成功就离开等待队列。 该歌曲会在 OBS 中显示为「当前点歌」，不会自动开始游玩。
• 不想打这首，可以直接选别的歌。 开始游玩任意歌曲后，当前点歌就算结束；回到选曲界面时再处理下一首。
• 一直没开始游玩，默认 10 分钟后跳过。 如果此时还在选曲界面，会继续处理下一首；游玩途中不会跳歌。
• 双击另一侧 Start 打开控制台。 单人 SP 选曲时，1P 游玩就双击 2P Start，2P 游玩就双击 1P Start。两次按下默认间隔不超过 400 毫秒，中间需松开。再次双击或按 Esc 关闭；队列为空也能打开。
• 想先玩队列中的某首歌，使用「弹幕与队列」页。 左侧为点歌队列和处理日志，右侧为实时弹幕。打开控制台时自动回到此页并聚焦第一首可选曲目，按一次 B6 即可确认；也可点击曲目定位，或用 B1/B2 移动焦点，队列随焦点自动滚动。B7 返回左侧页面入口；队列为空时焦点也停在该入口。定位成功后面板关闭，该曲目移出队列，其余歌曲保持原顺序；失败时保留曲目并显示原因。等待项旁的垃圾桶可删除该项。控制台打开期间暂停自动定位。
• 所有人都可以点歌。 队列和待选候选在游戏重启后清空。

控制台需要支持 SDK v0.4 D3D9 绘制回调的 Spice2x。双击开关仅在普通选曲、单人 SP 时生效，DP、双人游玩、游玩途中和游戏菜单弹窗内不生效。进入游玩后控制台自动关闭。对侧 Start 仍然只读取、不拦截。

窗口打开后，使用当前登录侧的手台操作（1P 登录用 1P，2P 登录用 2P）：

可以用手台切换页面、跳过 / 删除点歌、调整数值与开关，并选择「应用并保存」。别名、身份码等自由文字仍使用键盘或粘贴输入，鼠标也可照常操作。窗口打开时，当前侧七个琴键与转盘暂时用于控制台；关闭后恢复，已按住的琴键需先松开，避免误操作游戏。

控制台包含以下页面：

修改设置后点击 「应用并保存」。未保存的修改可以撤销；关闭窗口不会自动保存。身份码等凭据隐藏显示。弹幕查看不受日志的 danmu 开关影响。

在游戏内控制台选择相应页面，修改后点击「应用并保存」即可生效。设置会自动写入 DLL 旁的 chart-requester.db，下次启动自动恢复。首次使用采用内置默认设置，所有配置都在 GUI 中操作，不需要安装数据库软件。

同一档案内修改设置不会清空队列、候选或已有倒计时；新规则用于后续请求。切换到另一直播档案时会清空点歌、候选和弹幕历史。配置无效、别名无法确定歌曲或新端口被占用时，本次修改不会应用。若另一个窗口已保存设置，点击「刷新已保存设置」后再编辑。

旧版本的直播连接会自动成为 全局档案。未绑定个人档案的卡号、游客和退出登录后的状态使用全局档案；可在「直播连接」中配置或关闭它。

控制台顶部将主播名称、直播标题和连接状态紧凑地显示在同一行，长标题自动省略，悬停可查看完整内容。信息随实际连接的直播间切换，并每分钟刷新；获取失败不影响弹幕和点歌。

1. 刷卡登录游戏，进入单人选曲后打开控制台。未绑定的卡号会显示 「创建新直播间」。
2. 点击按钮，填写档案名称和主播身份码（或切换为直播间网页模式填写直播间号），点击 「应用并保存」。新档案自动绑定创建时的登录卡号，并立即连接对应直播间。
3. 以后使用这张卡登录时自动切换到该档案。退出登录或使用未绑定的卡号时恢复全局档案。
4. 在「直播连接」中选择个人档案，可添加其他卡号，或点击「绑定当前登录卡号」。手动输入的是读卡器 / Spice2x 使用的 16 位十六进制卡号，不是游戏内的 IIDX ID。多张卡可共用一个档案；一张卡只能绑定一个档案。

档案可重命名、解除卡号绑定或删除，修改均需保存。编辑其他档案不会切换正在使用的直播间。切换档案时清空原直播间的队列、当前点歌、候选、冷却和弹幕历史；同一档案的多张卡之间切换不清空。两侧同时参与时使用全局档案，避免选错玩家。

创建或绑定过程中若登录卡号变化，保存会被拒绝，请撤销后重新操作。档案选择、创建和卡号管理按钮支持控制器导航；名称、卡号及身份码使用键盘或粘贴输入。

要备份或把设置搬到另一台机器：

1. 在「备份与恢复」页填写 JSON 文件路径，点击「导出已保存设置」。导出只包含已保存的设置；同名文件已存在时，请更换文件名。
2. 在目标机器的同一页面填写备份路径，点击「导入到编辑区」。这会替换尚未保存的编辑内容，但不会立即更改运行设置。
3. 检查各页设置，尤其是本机路径，再点击「应用并保存」。游戏模块和曲库路径在下次启动生效。

JSON 是程序生成的备份，无需手动编辑。它包含所有直播档案、绑定卡号和直播身份码等凭据，请妥善保管。旧版本 JSON 备份仍可导入，导入后只有全局档案。队列和弹幕历史不包含在备份中。

以下设置都在「点歌规则」页，时间单位为秒：

想让观众用昵称点歌，在「歌曲别名」页点击「添加别名」，例如：

应用后，观众就可以发送 点歌 红武士。

右边填写游戏里的完整曲名；遇到同名歌曲时，也可以直接填写歌曲 ID。别名配置有问题时，界面会提示错误。

双击速度可在「按键操作」页调整，默认 400 毫秒，可设置 100–2000 毫秒。

想把 OBS 文件放到其他位置，在「OBS 显示」页修改「队列文本文件」和「交互文本文件」，然后在 OBS 中重新选择文件。

网页界面默认开启。如需关闭或更换端口，在「OBS 显示」页调整「启用浏览器来源」或「本机端口」。应用端口修改后，将 OBS URL 中的 32133 改成相同数字。关闭浏览器来源后，原来的文本文件仍可使用。

网页记录条数默认 10，可设为 1–100。减少条数会立即移除最早的记录，之后增加不会恢复已移除的内容。「文本提示保留（秒）」和「文本提示条数」只影响交互文本文件。候选歌曲在上方完整展示，多人同时待选时每 6 秒轮换一位观众；队列根据可用空间显示最多 6 首。

网页文件默认从 DLL 同目录下的 chart_request_static 读取，index.html 是入口，CSS、JS、图片和字体也放在这个目录或其子目录中。可以直接替换这些文件，然后刷新 OBS 浏览器来源，无需重新编译 DLL 或重启游戏。需要使用其他目录时，在「OBS 显示」页修改「网页静态目录」并应用；支持绝对路径，相对路径以 DLL 所在目录为准。更换目录后 OBS 地址仍为 /queue；自定义页面可通过 /api/state 获取实时点歌数据。

要调整网页样式，可在 OBS 浏览器来源的「自定义 CSS」末尾添加，例如：

:root {
  --accent: #dfbf83;             /* 点缀颜色 */
  --title-size: 26px;            /* 当前曲名字号 */
  --panel: rgba(18, 22, 25, .94); /* 面板颜色与不透明度 */
  --radius: 9px;                 /* 圆角大小 */
}

这里修改后点击 OBS 的「确定」即可，不需要重启游戏。字号增大或曲名较长时，可相应增加浏览器来源高度，避免内容被裁掉。

这是输入轮询函数的入口校验失败。2dxtra 会在同一位置安装 MinHook；当前版本可识别并保留这种调用链。退出游戏后替换新版 chart_requester.dll，再启动并查看日志中的 Input poll chain: MinHook -> 2dxtra.dll。

如果仍提示 Input poll ... is incompatible，请提供该行完整错误和插件列表；其他未知修改仍会阻止插件启动。

先确认是在单人 SP 的普通选曲界面。按的是另一侧 Start，中间要松开；如果按得较慢，可增大 controls.double_tap_ms。还需在 Spice2x 中正确绑定两侧 Start。队列为空不影响打开窗口。

查看日志中的 [input]：active_side=Some(1) / Some(2) 表示可用的游玩侧；sdk_status=-1 表示未获得 SDK 按键接口，-2 表示尚未读取，0 表示读取成功。再看 [gui]：status=-1 表示缺少绘制接口，请升级到支持 SDK v0.4 D3D9 回调的 Spice2x；0 表示已注册，1 表示正在绘制。旧版启动器仍可点歌，但无法显示控制台。新绘制接口只支持 D3D9 游戏画面。

身份码用于授权连接主播的直播间。默认方式会通过 blivechat 的公共服务创建连接，再接收哔哩哔哩弹幕，服务返回的信息包含对应直播间。因此只需要填写身份码，room_id 保持默认即可。无需安装或运行 blivechat。

先查看 obs/interaction.txt 中的具体原因，再依次检查：

1. 已在「直播连接」页启用弹幕连接，并点击「应用并保存」。
2. 填入的是主播身份码，复制时没有多余空格；使用刷新后的身份码时，也更新了配置。
3. 网络能正常访问哔哩哔哩和 blivechat 公共服务。短暂断线时插件会自动重连。
4. 如果提示连接数量达到上限，关闭不再使用的重复弹幕连接，等待一段时间后再试。

仍然失败时，请按下方说明提供日志。

先进入普通 STANDARD / FREE / PREMIUM FREE 选曲界面，再重新发送点歌。首次进入选曲前，插件还没有获得点歌所需的信息。

如果已经在这个界面仍持续提示等待，请确认使用的是最新版插件，然后退出并重新启动游戏。仍未恢复时，请附上日志反馈。

先启动游戏，再用普通浏览器打开 http://127.0.0.1:32133/。网页服务随插件启动，关闭游戏后也会停止。

• 普通浏览器能打开：核对 OBS URL 和端口，不要勾选「本地文件」，并点击来源属性中的「刷新当前页面缓存」。如果 OBS 早于游戏启动，也可以这样刷新。
• 普通浏览器打不开：检查 DLL 是否已加载、「OBS 显示」页是否启用了浏览器来源，以及日志中是否有「网页界面启动失败」。
• 提示端口被占用：在「OBS 显示」页把本机端口改为其他端口，例如 32134，应用后同时更新 OBS 地址。网页启动失败不会阻止原有文本点歌。
• 提示静态目录或 index.html 无法读取：确认 chart_request_static 已和 DLL 一起复制，或在「OBS 显示」页选择包含 index.html 的目录并应用。运行中删除网页文件会返回 404，恢复文件后刷新即可。

先用记事本打开 OBS 正在读取的那份 .txt 文件：

• 文件内容正常：检查 OBS 是否勾选「从文件读取」、路径是否正确，以及来源是否可见。
• 文件不存在：检查插件是否加载成功、DLL 路径是否正确、插件文件夹能否保存文件。
• 文件里有错误提示：按该提示排查。不要选择 .db 数据库、JSON 备份或 .log 日志作为 OBS 来源。

查看「点歌提示」和「点歌队列」。可能正在等待你回复候选编号，也可能排在其他点歌之后。点歌命令中的 点歌 后面需要有空格。

游戏需要处于可操作的普通选曲界面；菜单、过场和游玩途中不会跳歌。相反模式、未解锁或不可用的谱面也无法定位。

模糊搜索允许省略字符，不会自动纠正所有错别字。先试试完整曲名；常用中文昵称可以在「歌曲别名」页添加。

当前只适配了上方列出的 IIDX 33 游戏版本。同为 IIDX 33，不同更新包也可能不兼容。仅修改版本号文字不能解决；请等待相应适配，或在反馈中注明自己的游戏版本和报错。

修改后需要点击「应用并保存」，仅关闭窗口不会保存。若界面提示未应用，请按具体原因修正，例如重复别名、无效曲名或端口被占用。保存失败时原设置继续生效。

如果提示设置被另一个窗口更新，可点击「刷新已保存设置」读取数据库中的设置，再继续编辑。

更新前可在「备份与恢复」页导出 JSON，或退出游戏和独立预览后备份 chart-requester.db。解压新版本并替换 DLL 和 chart_request_static，保留数据库即可继续使用原来的设置；新增选项会使用默认值。自己修改过网页时，请先备份页面，或将自定义页面放在单独目录并配置「网页静态目录」。

从旧版升级时，如果 DLL 旁只有 chart-requester.toml，首次启动会自动导入到数据库，保留旧文件不动。迁移成功后程序只读取数据库，修改旧 TOML 不再生效；可以将旧文件移走备份。新安装不会生成 TOML。

暂时停止接收点歌，可在「直播连接」页取消启用并应用。完全移除时，退出游戏，删除启动命令中对应的 -k "…\chart_requester.dll" 参数，再删除插件文件夹即可。

在 问题反馈页面 说明插件版本、游戏版本、当时所在界面、发送的点歌命令，以及实际看到的提示。附上 DLL 旁 chart-requester.log 中出问题时间附近的内容；较早的日志可能在 .log.1 等文件中。

日志默认记录收到的弹幕及处理结果。分享前检查其中的用户名、弹幕等个人信息，不要上传自己的配置数据库、JSON 备份、旧 TOML 或身份码。想减少日常日志，可在「日志」页改为普通级别并应用；排错时改回详细级别。

需要编译插件或深入排错，请看 技术参考与开发指南；游戏版本与适配依据见 游戏适配分析。

调试控制台样式时，可以在源码目录运行 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/preview-menu.ps1，打开无需游戏的独立窗口。它连接真实直播间，用本地曲库检查匹配请求的处理状态和入队效果；支持鼠标、键盘及 F2–F7 模拟手台操作。首次运行在「直播连接」页填写身份码并保存；曲库与已有配置的指定方法见开发指南。