GitHub / 开源地址：https://github.com/klkq6r33n/LCCBmusic

[EN] Prerequisites: CybergrindMusicExplorer (CGME) 2.3.2+ and greycsont-Fffffff. This package is an add-on DLL for CGME, not a replacement fork — keep CGME enabled. The old standalone fork (1.x) must be removed before installing this version. Downloader: this package ships no downloader binaries; CGME handles its own downloader. Install: install this zip with r2modman / Thunderstore Mod Manager, or extract it into the ULTRAKILL folder (runtime file: BepInEx/plugins/Claude-JukeboxLimbusCompany/JukeboxLimbusCompany.dll). Optional: ZedDev-USTManager is supported — F5 replacement pauses/mutes multi-segment and UST-driven soundtrack sources, and USTManager will not replace the F5 track. Disclaimer: this is an independent, unofficial extension. It is not affiliated with or endorsed by Flazhik (CybergrindMusicExplorer) or greycsont. It contains AI-assisted content; see the AI disclosure. Lyrics: put Track.srt next to Track.mp3. Optional translation: also add Track.zh.srt / Track.cn.srt / Track.ja.srt / Track.trans.srt. Both lines are shown at different, non-overlapping positions. Songs: this mod bundles no audio. Every song is read from ULTRAKILL's built-in Cyber Grind music folder (ULTRAKILL/Cybergrind/Music); put your audio there. UI: default language is English. In the Jukebox menu (F4) use LANGUAGE to switch to Chinese and SETTINGS for precise numeric inputs (position, color, font size, motion, translation). Safety: lyrics are clamped on-screen and never overlap each other. Special thanks to greycsont for the ULTRAKILL font, and to Flazhik and the Jukebox / CybergrindMusicExplorer team for the original mod this extension depends on.

[中文] 前置：CybergrindMusicExplorer（CGME）2.3.2+ 与 greycsont-Fffffff。本包是 CGME 的扩展 DLL，不是替代 fork——请保持 CGME 启用。安装本版本前需先移除旧版 1.x 独立 fork。 下载器：本包不附带下载器程序；下载功能由 CGME 自身负责。 安装：用 r2modman / Thunderstore Mod Manager 安装本 zip，或直接解压到 ULTRAKILL 游戏根目录（运行文件：BepInEx/plugins/Claude-JukeboxLimbusCompany/JukeboxLimbusCompany.dll）。 可选：ZedDev-USTManager 已适配——F5 取代时会暂停/静音多段与 UST 驱动的关卡音乐音源，USTManager 也不会把 F5 替代曲再替换一次。 声明：本扩展为独立、非官方作品，与 Flazhik（CybergrindMusicExplorer）及 greycsont 无隶属或背书关系。本项目含 AI 辅助内容，详见 AI 说明。 歌词：把 Track.srt 放在 Track.mp3 同目录。可选翻译：再放 Track.zh.srt / Track.cn.srt / Track.ja.srt / Track.trans.srt，两行歌词会在不同且不重叠的位置同时显示。 歌曲：本 mod 不附带任何音频，所有歌曲均读取自 ULTRAKILL 自带的电子血宫音乐文件夹（ULTRAKILL/Cybergrind/Music），把音频放进该文件夹即可。 界面：默认英文。在 Jukebox 菜单（F4）用 LANGUAGE 切换中文，用 SETTINGS 精确填写位置、颜色、字号、动态与翻译。 防重叠/防出屏：歌词自动限制在屏幕内，且不会互相交叠。 特别感谢 greycsont 提供的 ULTRAKILL 字体，以及 Flazhik 与 Jukebox / CybergrindMusicExplorer 团队提供的原型 mod 与源码。

Jukebox LimbusCompany

Author / 作者：6r3²n

AI disclosure / AI 说明 This project was made with AI assistance; the author (6r3²n) has limited programming knowledge and used AI to build it. 本项目在 AI 辅助下完成；作者（6r3²n）计算机知识有限，使用 AI 制作了此扩展。

LimbusCompany lyric performance extension for CybergrindMusicExplorer.

CybergrindMusicExplorer 的 LimbusCompany 歌词演出扩展 mod。

An add-on extension DLL for the open-source Flazhik/Jukebox (CybergrindMusicExplorer) 2.3.2. CGME stays installed and enabled; this DLL only adds the LimbusCompany lyric layer and its F4/F5 UI, and blanks the original subtitle panel at runtime instead of replacing any CGME assembly. It renders lyrics in a LimbusCompany style: text color, outline, glow, font size/spacing, shake, fade-in, rise, random angle, pseudo-perspective and position range.

Requires CGME 2.3.2+ (enabled) and greycsont-Fffffff. From 2.0.0 this mod is a separate extension assembly (JukeboxLimbusCompany.dll) with its own plugin GUID; the old 1.x standalone fork must be removed.

Downloader: this extension ships no yt-dlp / ffmpeg / ffprobe. URL/YouTube downloading is provided by CGME itself when its Downloader is installed.

基于开源 Flazhik/Jukebox (CybergrindMusicExplorer) 2.3.2 的扩展 DLL。CGME 保持安装并启用；本 DLL 只追加 LimbusCompany 歌词层及其 F4/F5 界面，运行时清空原版字幕面板，不替换任何 CGME 程序集。 歌词按 LimbusCompany 演出风格渲染：文字颜色、描边、辉光、字号/字距、抖动、淡入、上升、随机角度、近似透视、位置范围。

需要 CGME 2.3.2+（保持启用）与 greycsont-Fffffff。 从 2.0.0 起本 mod 是独立扩展程序集（JukeboxLimbusCompany.dll），使用自己的插件 GUID；旧版 1.x 独立 fork 必须移除。

下载器： 本扩展不附带 yt-dlp / ffmpeg / ffprobe；URL / YouTube 下载由 CGME 自身的 Downloader 提供。

Contents / 内容

manifest.json, icon.png and README.md stay at the zip root; all runtime files below are packaged under BepInEx/plugins/Claude-JukeboxLimbusCompany/.

manifest.json、icon.png、README.md 位于 zip 根目录；下列运行文件均在 BepInEx/plugins/Claude-JukeboxLimbusCompany/ 下。

JukeboxLimbusCompany.dll     extension assembly (plugin GUID: dev.6r3n.jukeboxlimbuscompany)

Only the extension DLL is shipped. CGME's Jukebox.dll / JukeboxCore.dll /
Jukebox.ThornExtensions.dll, its Assets/ bundles, and the RTLTMPro /
SubtitlesParser / TagLibSharp libraries are NOT redistributed — they are
provided by the CybergrindMusicExplorer package this mod depends on.
No downloader binaries (yt-dlp / ffmpeg / ffprobe) and no font files are included.

JukeboxLimbusCompany.dll     扩展程序集（插件 GUID: dev.6r3n.jukeboxlimbuscompany）

仅附带扩展 DLL。CGME 的 Jukebox.dll / JukeboxCore.dll /
Jukebox.ThornExtensions.dll、Assets/ 资源以及 RTLTMPro /
SubtitlesParser / TagLibSharp 均不再重新分发——它们由本 mod 依赖的
CybergrindMusicExplorer 包提供。
不包含 yt-dlp / ffmpeg / ffprobe 等下载器程序，也不附带字体文件。

Installation / 安装

English

1. Install BepInEx 5.4.23 for ULTRAKILL.
2. Install this package with r2modman / Thunderstore Mod Manager. Its dependencies CybergrindMusicExplorer 2.3.2+ and greycsont-Fffffff are installed automatically — keep CGME enabled.
3. Remove any older 1.x standalone fork (Jukebox.dll replacing CGME) before installing 2.x.
4. Manual install: extract the zip into the ULTRAKILL folder. The only runtime file is BepInEx/plugins/Claude-JukeboxLimbusCompany/JukeboxLimbusCompany.dll.
5. If you toggle CGME in a mod manager, let the manager handle all its files (DLLs and Assets/). Enabling only the DLLs can leave the game's input action asset unloaded.

中文

1. 为 ULTRAKILL 安装 BepInEx 5.4.23。
2. 用 r2modman / Thunderstore Mod Manager 安装本包；依赖 CybergrindMusicExplorer 2.3.2+ 与 greycsont-Fffffff 会自动安装，请保持 CGME 启用。
3. 安装 2.x 前先移除旧版 1.x 独立 fork（替换 CGME 的 Jukebox.dll）。
4. 手动安装：把 zip 解压到 ULTRAKILL 游戏根目录。唯一运行文件是 BepInEx/plugins/Claude-JukeboxLimbusCompany/JukeboxLimbusCompany.dll。
5. 在 mod 管理器中启用/禁用 CGME 时，请让管理器处理它的全部文件（DLL 和 Assets/）。只恢复 DLL 会导致游戏输入资源未加载。

Declarations / 声明

• Independent extension / 独立扩展：This is an unofficial add-on, not affiliated with or endorsed by Flazhik (CybergrindMusicExplorer) or greycsont. 本扩展为非官方附加组件，与 Flazhik（CybergrindMusicExplorer）及 greycsont 无隶属或背书关系。
• Dependencies / 依赖：CGME 2.3.2+ and Fffffff are required and installed separately. This package does not redistribute CGME's Jukebox.dll / JukeboxCore.dll / Jukebox.ThornExtensions.dll, its Assets/ bundles, its runtime libraries (RTLTMPro / SubtitlesParser / TagLibSharp), any fonts, or any downloader binaries. CGME 2.3.2+ 与 Fffffff 为必需前置并单独安装；本包不重新分发 CGME 的程序集、Assets/、运行库、字体或下载器。
• Assets / 资源：no audio is bundled. Songs are read from ULTRAKILL/Cybergrind/Music. 不附带任何音频，歌曲读取自 ULTRAKILL/Cybergrind/Music。
• AI / 许可：AI-assisted content; licensed under Apache-2.0 with the original NOTICE retained. 含 AI 辅助内容；使用 Apache-2.0 许可并保留原始 NOTICE。

Operation limits / 操作限制

• F4 is the Cyber Grind menu; F5 is the level-only mouse menu and is ignored in the Cyber Grind. F4 只用于血宫，F5 只在关卡使用，血宫内忽略 F5。
• F5 pauses the game and unlocks the cursor; F5 / Esc close it. If a stale pause remains, press F5 once to force-resume. 打开 F5 会暂停游戏并解锁鼠标；F5 / Esc 关闭；若输入被残留暂停锁住，按一次 F5 强制恢复。
• The visualizer only auto-detects main level BGM. A per-level BGM clip map (generated from the current game version) excludes ambient drones and Cyber Grind (Loop) tracks; level-select, main-menu and Intro scenes do not show it. 可视化只自动识别关卡主 BGM；内置每关 BGM 清单会排除环境 Drone 与血宫 (Loop) 特供曲；选关、主菜单、Intro 场景不显示。
• The glitch filter also applies to the spectrum bars (slice displacement + alternating red/cyan tint + strobe). On parry flash / hitstop, the whole spectrum's intensity is boosted for the trigger duration, in addition to the red/cyan dispersion; the bar count, positions and layout do not change. Higher strength boosts the spectrum more strongly. 故障滤镜同时作用于频谱柱（切片位移 + 逐根红/青交替染色 + 频闪）；弹反/顿帧时整套频谱的强度会整体提高，同时叠加红/青色散；柱子数量、位置和布局都不变，强度越高抬得越明显。
• Multi-segment level BGM is muted/volume-zeroed while an F5 replacement is active, including scene-local boss tracks (e.g. Centaur in 7-4); RESTORE BGM / scene change restores them. 取代期间会静音/零音量所有多段关卡 BGM（含 7-4 的 Centaur 等场景内 Boss 曲）；归还或切场景时恢复。
• USTManager is optional (not a dependency): custom USTs are paused/muted during replacement. USTManager 可选，不是前置；取代期间会暂停/静音其驱动的音源。
• The per-level BGM map is based on the game version parsed during development; a newly added or reworked level may need a mod update. 每关 BGM 清单基于开发时解析的游戏版本；新增或重做关卡可能需要更新本 mod。
• No downloader is included; downloading is CGME's own feature. 不附带下载器；下载功能属于 CGME 自身。
• Cover-row position/adaptation may still be imperfect in some window sizes/aspect ratios. 曲绘行的位置与窗口自适应在部分尺寸/宽高比下仍可能不完美。

Configuration / 配置

On first launch, BepInEx/config/LimbusCompany/lyric_config.json is created:

1. If E:\084music\lyric_config.json (an external lyrics tool) exists on this machine, it is copied as the initial config;
2. Otherwise the built-in defaults are written.

Changes are hot-reloaded within one second (font family needs a restart).

首次启动生成 BepInEx/config/LimbusCompany/lyric_config.json：

1. 若本机存在 E:\084music\lyric_config.json（外部歌词工具），直接复制为初始值；
2. 否则写入内置默认值。

保存后 1 秒内热重载（字体族除外，需重启）。

Supported settings fields / 支持的 settings 字段

text_color, stroke_color, stroke_width, glow_color, glow_enabled, glow_size, glow_alpha, font_family, font_size, spacing, shake_intensity, shake_speed, fade_speed, rise_speed, angle_min, angle_max, delay, perspective_enabled, persp_x_strength, persp_y_strength, pos_x_min, pos_x_max, pos_y_min, pos_y_max, zoom, language.

Extension fields / 扩展字段

Language / 语言

• Default UI language is English. Switch it in the Cyber Grind with the LANGUAGE button injected into the F4 menu, or in any level with F5 → DISPLAY → 中文 / ENGLISH (keyboard G also toggles it).
• The choice is saved as "language": "en" / "zh" in lyric_config.json and re-applied on launch.
• Chinese mode localizes this mod's own UI only (the LANGUAGE / SETTINGS buttons, the settings panel and the F5 menu). The original CybergrindMusicExplorer menu stays English.
• 默认界面语言为英文。血宫内用 F4 菜单里的 LANGUAGE 按钮切换；任意关卡内用 F5 → DISPLAY → 中文 / ENGLISH（键盘 G 也可切换）。
• 选择会写回 lyric_config.json 的 "language"（en/zh），下次启动自动生效。
• 中文模式只翻译本 mod 自己的界面（LANGUAGE / SETTINGS 按钮、设置面板与 F5 菜单），原版 CGME 菜单保持英文。

User presets / 玩家预设

• F4: open the mod's SETTINGS panel and use the new PRESET tab. Type a name, click SAVE CURRENT to store the current lyric/visualizer/row settings, click a preset name to apply it, and DEL / 删除 to delete it.

• F5: open the PRESETS tab for the same save/apply/delete actions (paged list).

• Presets are stored in lyric_config.json under "user_presets", alongside the settings object. Saving with an existing name overwrites it. Language, BGM track/key bindings and the master enabled switch are intentionally not part of a preset.

• F4：打开本 mod 的 SETTINGS 面板，使用新增的 预设（PRESET） 页。输入名称后点 保存当前，即可把当前歌词 / 频谱 / 曲绘行设置存为预设；点击预设名称应用，点 删除 / DEL 删除。

• F5：打开 PRESETS 页，同样可以保存 / 应用 / 删除（列表可翻页）。

• 预设保存在 lyric_config.json 的 "user_presets" 下，与 settings 并列。用相同名称保存会覆盖；语言、BGM 曲目/快捷键与歌词层总开关不会写入预设。

In-game feature settings / 游戏内功能设置

While the Jukebox menu is open, the SETTINGS / 设置 button (next to LANGUAGE) opens a 3-page panel where every value is a numeric / text input field (no coarse presets):

• LAYOUT / 位置: X min/max %, Y min/max %, zoom %, angle min/max, delay (ms), random position / random angle
• TEXT / 文字: text color, font size, spacing, stroke color/width, glow color/size/alpha, glow on/off, font family
• MOTION / 动态 (two sub-pages via the button at the bottom): page 1 has shake intensity/speed, fade speed, rise speed, typewriter on/off + chars per second, perspective + X/Y strength, lyrics on/off, replace original subtitles; page 2 has glitch filter on/off + intensity (0–100) + strobe speed (0.1–5) and reactive glitch on parry flash / hitstop (on/off + strength 0–100 + duration 0.05–1 s), plus a TEST TRIGGER button that previews the current strength/duration immediately. Numeric fields apply while you type; you do not need to press Enter to hear/see the new value.
• VISUAL / 频谱: audio visualizer on/off, wave size, max extent (% of screen), position (BOTTOM / TOP / LEFT / RIGHT / EDGE), bar density (8–512), gradient range (0–1), gradient speed, gradient mode (FIXED 2 / RANGE x~y / MULTI RGB), colour A RGB, colour B RGB, multi RGB (space separated), X mirror — plus an in-panel usage note
• F5 mouse menu (levels only; the Cyber Grind uses F4 and F5 is ignored there): a clickable menu with MUSIC / SETTINGS / DISPLAY pages — browse Cybergrind/Music (the game's built-in Cyber Grind music folder; no audio is bundled), replace/restore the level BGM, switch the UI language, edit every lyric setting, toggle lyrics/now-playing, and drag/resize the cover row. The window is split: left = controls, right = track preview (cover on top, title and artist below). Opening it pauses the game and forcibly unlocks/shows the cursor, like the CGME menu.
• Now-playing row (bottom-left by default): one horizontal line with the cover first, then title and artist; when the track has no cover the ULK-style frame stays hollow. Cover art is read from the audio file's ID3 tag or a same-name / cover / folder image; its position and size are adjustable.
• RESET PAGE (resets only the currently open page) / CLOSE

Every change is written to lyric_config.json immediately; the lyric style refreshes within a second. (replace_original takes full effect after re-entering Cyber Grind; font family needs a restart.)

打开 Jukebox 菜单后，右上角 LANGUAGE 旁边的 SETTINGS / 设置 按钮会打开一个设置面板，每一项都是数值/文本输入框（不再用固定档位）：

• LAYOUT / 位置：X 最小/最大 %、Y 最小/最大 %、缩放 %、角度最小/最大、延迟（毫秒）、随机位置/随机旋转
• TEXT / 文字：文字颜色、字号、字距、描边颜色/宽度、辉光颜色/大小/透明度、辉光开关、字体
• MOTION / 动态（底部按钮分两页）：第一页为抖动强度/速度、淡入速度、上飘速度、逐字显示开关 + 每秒字数、透视与 X/Y 强度、歌词层开关、替换原版字幕；第二页为 故障滤镜开关 + 强度 (0–100) + 频闪速度 (0.1–5)、弹反闪光 / 顿帧触发故障（开关 + 强度 0–100 + 持续时间 0.05–1 秒），以及 预览触发 按钮，可立即按当前强度/持续时间播放一次故障。数值输入框在输入过程中就会实时生效，无需按回车。
• VISUAL / 频谱：音频可视化开关、波动大小、最大幅度（屏幕百分比）、显示位置（底部/顶部/左侧/右侧/四周暗角）、频谱密度（8–512）、渐变范围（0–1）、渐变强度（速度）、渐变模式（固定双色 / 区间渐变 / 多色渐变）、颜色 A RGB、颜色 B RGB、多色 RGB（空格分隔）、X 轴镜像，面板内附使用说明
• F5 鼠标菜单（仅关卡可用；血宫内只用 F4，F5 会被忽略）：可点击的 MUSIC / SETTINGS / DISPLAY 三页——浏览 Cybergrind/Music（ULTRAKILL 自带的电子血宫音乐文件夹，mod 不附带音频）、取代/归还关卡 BGM、切换界面语言、修改全部歌词设置、开关歌词/曲绘行、用鼠标拖动缩放曲绘行。窗口分为左侧功能栏与右侧曲目预览（曲绘在上，曲名与作者在下）。打开时暂停游戏并强行解锁/显示鼠标，操作方式与 CGME 菜单一致。
• 曲绘行（默认左下角）：横排依次显示曲绘、曲名、作者；没有曲绘时 ULK 风格描边框体镂空。曲绘从音频文件的 ID3 标签或同名 / cover / folder 图片读取，位置和大小都可调整。
• 重置本页（只重置当前打开的页面）/ 关闭

每次改动都会立刻写回 lyric_config.json，歌词样式 1 秒内刷新。（replace_original 需要重新进入 Cyber Grind 才完全生效；字体需要重启。）

Audio visualizer / 音频可视化

• Reacts to the currently playing Jukebox track or level BGM (AudioSource.GetSpectrumData), drawn as bars behind the lyrics.

• Only main level BGM is auto-detected: a per-level BGM clip map (generated from the game's level resources and embedded in the DLL) is used first, so multi-segment boss tracks (e.g. Centaur A-x / B-x in 7-4) are recognized while ambient drones and Cyber Grind (Loop) tracks are excluded. Level-select, main-menu and Intro scenes do not show the visualizer.

• While an F5 replacement is active, all level BGM sources from that per-level map (plus MusicManager themes) are muted/volume-zeroed, so multi-segment game music cannot play over the replacement.

• visualizer_enabled (default off), visualizer_amplitude (wave size multiplier, 0.1–5), visualizer_size (max extent as % of the screen dimension, default 50, no upper limit), visualizer_position (bottom default / top / left / right / edge), visualizer_bars (density, 8–512, default 96), visualizer_gradient_range (0 = solid start colour, 1 = full gradient spread), visualizer_gradient_speed (gradient animation speed; the "gradient strength"), visualizer_gradient_mode, visualizer_color_a, visualizer_color_b, visualizer_colors, visualizer_mirror_x (X-axis mirror).

• edge / 四周暗角: bars grow inward from all four screen edges and never enter the central circular empty area; a radial dark vignette sits behind them.

• Glitch filter: applies to both lyrics and spectrum bars (per-bar alternating red/cyan tint, slice displacement, strobe). glitch_enabled, glitch_intensity (0–100), glitch_speed (0.1–5), and glitch_reactive_enabled / glitch_reactive_strength (0–100) / glitch_reactive_duration (0.05–1 s) trigger an extra twitch + dispersion whenever TimeController.parryFlash activates or TimeController.currentStop (hitstop) starts; during that trigger the whole spectrum's intensity is boosted (no bar-count or layout change); higher strength gives a stronger boost.

• Gradient speed / strength (visualizer_gradient_speed, 0–2, default 0.08): how fast the colours move; 0 freezes the gradient.

• Gradient modes (visualizer_gradient_mode) — every mode animates per bar, so different frequency blocks change colour independently:

  • fixed2 — two colours: colour A → colour B flows in one direction along the row and loops.
  • range (default) — x~y: the same two colours sweep back and forth over time.
  • multi — multiple RGB stops: the whole row flows through every colour in visualizer_colors.

• RGB input: each colour is written as R,G,B (0–255), separated by , or ，, e.g. 255,211,77. visualizer_colors holds several such triplets separated by spaces, e.g. 255,0,0 0,255,0 0,0,255. Defaults: A 216,165,35, B 0,229,255, multi 255,0,0 255,165,0 255,255,0 0,255,0 0,140,255 160,0,255.

• Colours never react to audio intensity (bar height still follows the music). Every bar also has a black outline.

• The visualizer is drawn on its own canvas below the original game UI, so it never covers the vanilla HUD.

• Bars are flush with the screen edge (no gap at TOP/BOTTOM/LEFT/RIGHT).

• The maximum extent is entirely user-defined (no 50% cap); set it as large as you want.

• 跟随当前 Jukebox 曲目或关卡 BGM（AudioSource.GetSpectrumData），以可配置密度的柱状条绘制在歌词层下方。

• visualizer_enabled（默认关）、visualizer_amplitude（波动大小倍数，0.1–5）、visualizer_size（最大幅度占屏幕对应方向的百分比，默认 50，无上限）、visualizer_position（默认 bottom，可选 top/left/right/edge）、visualizer_bars（频谱密度，8–512，默认 96）、visualizer_gradient_range（0=起点单色，1=整排铺满渐变）、visualizer_gradient_speed（渐变速度 = 渐变强度）、visualizer_gradient_mode、visualizer_color_a、visualizer_color_b、visualizer_colors、visualizer_mirror_x（X 轴镜像）。

• edge / 四周暗角：柱子从屏幕四边向中心生长，但不会进入中心的圆形空区；后面绘制径向暗角底图。

• 故障滤镜：同时作用于歌词与频谱柱（逐根红/青交替染色、切片位移、频闪）。glitch_enabled、glitch_intensity（0–100）、glitch_speed（0.1–5），以及 glitch_reactive_enabled / glitch_reactive_strength（0–100）/ glitch_reactive_duration（0.05–1 秒）会在 TimeController.parryFlash 激活或 TimeController.currentStop（顿帧）开始时额外触发抽动 + 色散；触发期间整套频谱的强度会整体提高（柱子数量与布局不变）；强度越高，抬升越明显。

• 渐变强度 / 速度（visualizer_gradient_speed，0–2，默认 0.08）：数值越大颜色流动越快；0 表示渐变静止。

• 三种渐变模式（visualizer_gradient_mode）—— 三种模式都会按柱子的不同相位随时间变色：

  • fixed2 —— 双色流动：颜色 A → 颜色 B 沿整排单向流动并循环；
  • range（默认）—— x~y 区间渐变：同样两种颜色，混合比例随时间来回扫动；
  • multi —— 多色渐变：整排按 visualizer_colors 里的多个 RGB 色标依次流动。

• RGB 输入格式：单个颜色写作 R,G,B（0–255），用 , 或 ， 分隔，如 255,211,77；visualizer_colors 里多个颜色用空格分隔，如 255,0,0 0,255,0 0,0,255。默认：A 216,165,35、B 0,229,255、多色 255,0,0 255,165,0 255,255,0 0,255,0 0,140,255 160,0,255。

• 颜色不随音频强度变化（柱高仍然跟随音乐）。每根柱状条都带黑色描边。

• 波形图放在独立画布、排序低于游戏原版 UI，不会盖住原版界面。

• 柱状条紧贴屏幕边缘（TOP/BOTTOM/LEFT/RIGHT 均无空隙）。

• 最大幅度完全由用户设置（不再限制 50%），可以设得任意大。

Level BGM replacement / 关卡 BGM 取代

• Press F5 in any level to open the mouse menu. It is separate from the Cyber Grind menu: F4 works only in the Cyber Grind, F5 only in levels. Opening the menu pauses the game and unlocks the cursor.

• MUSIC: lists every .mp3 / .ogg / .wav under Cybergrind/Music recursively (page buttons at the bottom); click a track to select it, then REPLACE LEVEL BGM or RESTORE BGM. A progress bar shows the replacement track's position — click/drag it to seek — with PAUSE / RESUME and elapsed/total time. The category buttons at the top show PERSONAL (songs outside all category folders) and every registered category folder, starting with ULTRAKILL-OST. Click + to add your own category: enter a folder name, and the mod creates Cybergrind/Music/<name> and switches to it. Category names are saved in lyric_config.json under "song_categories". For a custom category, a DEL button deletes it together with its folder and all songs (with a confirmation); PERSONAL and ULTRAKILL-OST cannot be deleted this way. No official audio is shipped with the mod or downloaded automatically — the folder is for tracks extracted from your own game copy.

• SETTINGS: the same LAYOUT / TEXT / MOTION / TRANS / VISUAL pages as the in-Cyber-Grind menu, fully mouse-driven (inputs, toggles, per-page reset).

• DISPLAY: switch 中文 / ENGLISH, toggle lyrics and the now-playing row, adjust cover/text size, cycle the visualizer position (BOTTOM / TOP / LEFT / RIGHT / EDGE), and turn the glitch filter on/off with intensity (0–100) and strobe speed (0.1–5) sliders. The row is dragged/resized directly with the mouse while F5 is open (no separate adjustment block or shortcuts).

• Only F5 (open/close) and Esc (close) remain as keyboard shortcuts; all other shortcuts were removed.

• Replace pauses every level-music source under the game's MusicManager (clean / battle / boss, and any additional multi-segment sources), not just the currently audible one, then starts the selected track on a loop. The paused level music keeps its exact position.

• USTManager compatibility: while the replacement is active the mod re-scans and pauses/mutes the game's soundtrack sources every frame, so custom USTs and multi-segment switches cannot start playing over the replacement. The replacement track's clip is given an LCCB_ prefix so USTManager never mistakes it for a game cue and replaces it a second time. Restoring returns the sources to their previous mute/pause state.

• Restore stops the replacement and unpauses the level music, which continues from the point where it was paused. Scene changes also end the replacement automatically.

• The audio visualizer reads the replacement track while it is active, and reads the game's level music after restoration — so the spectrum works for both.

• Downloading (if available) is handled by CGME's own Downloader; this extension only adds the lyric layer.

• 在任意关卡中按 F5 打开鼠标菜单。它与血宫菜单分开：F4 只在血宫可用，F5 只在关卡可用。 打开时暂停游戏并解锁鼠标。

• MUSIC：递归列出 Cybergrind/Music 下所有 .mp3 / .ogg / .wav（底部翻页）；点击曲目选中，再点 取代关卡 BGM 或 归还原 BGM。界面带进度条（点击/拖动跳转）、暂停 / 继续按钮以及已播放/总时长。顶部的分类按钮显示 个人（不在任何分类文件夹内的歌曲）以及所有已注册的分类文件夹，第一个是 ULTRAKILL-OST。点 + 可添加自己的分类：输入文件夹名后，mod 会创建 Cybergrind/Music/<名称> 并切换到该分类。分类列表保存在 lyric_config.json 的 "song_categories" 中。选中自定义分类后会出现 删除 / DEL，确认后会连同文件夹及其中所有歌曲一起删除；个人与 ULTRAKILL-OST 不能这样删除。mod 不附带也不会自动下载官方音频，该文件夹用于放置从你自己游戏副本中提取的曲目。

• SETTINGS：与血宫内菜单相同的 位置 / 文字 / 动态 / 翻译 / 频谱 五页，全部可用鼠标操作（输入框、开关、单页重置）。

• DISPLAY：切换 中文 / English、开关歌词与曲绘行，提供 曲绘/文字大小滑块（10–120）、重置位置与大小、频谱位置循环（底部/顶部/左侧/右侧/四周暗角），以及 故障滤镜开关 + 强度（0–100）+ 频闪速度（0.1–5）滑块；菜单打开时也可以直接用鼠标拖动曲绘小方框、滚轮缩放。

• 仅保留 F5（开关）与 Esc（关闭）两个键盘快捷键；其余快捷键已全部移除。

• 取代：暂停游戏 MusicManager 下所有关卡音乐音源（clean / battle / boss 以及其它多段 BGM 音源），而不只是当前正在响的那一个，然后循环播放选定曲目；被暂停的关卡音乐保留准确进度。

• USTManager 适配：取代期间每帧重新扫描并暂停/静音游戏音乐音源，自定义 UST 与多段切换都无法盖过替代曲目；替代曲目的 clip 会加上 LCCB_ 前缀，避免被 USTManager 当成游戏音乐再替换一次。归还时按取代前的静音/暂停状态恢复。

• 归还：停止替代曲目并恢复关卡音乐，从暂停的位置继续；切换关卡时也会自动结束取代。

• 频谱在取代期间读取替代曲目，归还后读取关卡原音乐，两种情况下都有效。

• 下载功能（若已安装）由 CGME 自带的 Downloader 负责；本扩展只追加歌词层。

Now-playing row / 曲绘行

• While a Jukebox song or a replaced level track is playing, one horizontal row is drawn: cover / title / artist (曲绘 / 曲名 / 作者). The row is small by default: the text size is the reference and the cover is only slightly larger than the text (about 1.3×), never the other way around. The title and artist use the same font size; the artist is the last item in the row.

• The cover sits in a ULK-style bordered frame. No cover → the frame stays hollow (only the border is drawn).

• Cover source, in order: an image with the audio file's base name (.png / .jpg / .jpeg), then cover / folder / front / album / artwork / albumart / thumb / jacket / pak images, then any other image in the song folder, then the embedded ID3 picture. Decode results (including failures) are written to the BepInEx log.

• If the file has no performer/composer tag, the artist is recovered from an Artist - Title file name or song folder name; the title is recovered the same way when the title tag is missing.

• Size / position: F5 → DISPLAY has a COVER / TEXT SIZE slider (10–120) and a RESET POSITION & SIZE button (bottom-left, size 32). While the menu is open you can also drag the small cover square to move the row and scroll the wheel over that square to resize; the row always stays inside the screen. Changes save immediately.

• The in-game row defaults to the bottom-left in cover / title / artist order. Like the F5 menu, it is kept inside the screen safe area (12 px margin) even after dragging or an old off-screen position. Its size and position use the current window size (Screen size / canvas scale), so resizing the game window or changing resolution/aspect ratio re-adapts immediately; the F5 window shrinks automatically when the window is smaller than the menu.

• The F5 right-hand preview uses a vertical layout instead: the selected track's cover is shown above its title and author. The in-game row stays horizontal (cover / title / artist).

• Config keys: now_playing_enabled, cover_pos_x/y (row anchor: left edge X and vertical center Y, in % of the screen), cover_size (text/row size, 10–120, default 32; the cover is about 1.3× this); title_pos_x/y are kept for old configs but are no longer used.

• 当 Jukebox 曲目或取代的关卡曲目正在播放时，会绘制一整行：曲绘 / 曲名 / 作者。整行默认很小：以文字大小为基准，曲绘只比文字略大（约 1.3 倍），而不是把文字放大到曲绘那么大。曲名与作者使用相同字号，作者排在整行最后。

• 曲绘外面是 ULK 风格的描边框。没有曲绘时框体镂空（只画边框）。

• 曲绘来源依次为：与音频同名的图片（.png / .jpg / .jpeg）、cover / folder / front / album / artwork / albumart / thumb / jacket / pak 图片、歌曲文件夹内任意其他图片、最后是音频内嵌的 ID3 图片。解码结果（含失败原因）会写入 BepInEx 日志。

• 如果文件没有作者/作曲标签，会从 作者 - 曲名 形式的文件名或歌曲文件夹名补全作者；标题标签缺失时也会按同样方式补全标题。

• 大小 / 位置：F5 → DISPLAY 有 曲绘/文字大小滑块（10–120） 和 重置位置与大小 按钮（左下角，大小 32）。菜单打开时也可以拖动曲绘小方框移动整行、在方框上滚轮缩放；整行始终保持在屏幕内。改动立即保存。

• 游戏内曲绘行默认出现在屏幕左下角，顺序为 曲绘 / 曲名 / 作者。与 F5 菜单一样使用防出屏处理（12 像素安全边距），拖动或旧配置在屏幕外时都会被拉回可见范围。曲绘行大小与位置使用当前窗口大小（Screen 尺寸 / Canvas 缩放系数）计算，调整游戏窗口或切换分辨率/宽高比时会立即重新适配；F5 窗口在窗口小于菜单时会自动缩小。

• F5 右侧预览使用竖排布局：选中曲目的曲绘在上，曲名与作者在下；游戏内的曲绘行仍然是横排（曲绘 / 曲名 / 作者）。

• 配置项：now_playing_enabled、cover_pos_x/y（整行锚点：左边缘 X、垂直中心 Y，屏幕百分比）、cover_size（文字/整行大小，10–120，默认 32，曲绘约为它的 1.3 倍）；title_pos_x/y 仅为兼容旧配置保留，已不再使用。

Position safety / 位置防重叠与防出屏

• Random-position mode re-rolls each new line until it does not overlap the previous line's box, so consecutive lines never stack on the same spot.
• Lines that appear within the avoid_window time window (default 6 s) are forced into different lanes, even when random position is off; the required spacing is avoid_gap pixels (default 30) and the lane step is avoid_step % of screen height (default 10). All are editable in SETTINGS → LAYOUT.
• Additionally, overlap with any line from the last 2.5 s is a hard constraint (minimum 12 px). With very large avoid_gap values the preferred spacing is relaxed, but two nearby lines can never share the same box.
• Each cue is an independent line: when a new line starts, the previous line stays at its own position and finishes its own fade-out (it is not replaced in place), while the new line is placed somewhere else and avoids every still-visible line. So cues that are 0.1 s apart never collapse onto the same spot, and neither line cuts the other's fade-in/fade-out. This applies to every song.
• Position is user-controlled: random_position (default true) makes every line spawn at a random point; the available area is the pos_x_min/max × pos_y_min/max percentage rectangle, which defaults to the whole screen (0–100). Turn random_position off to keep all lines at the centre of that rectangle.
• Position anchor (position_anchor, default random): choosing top-left / top / top-right / left / center / right / bottom-left / bottom / bottom-right pins every lyric to that spot (e.g. bottom-left / bottom-right); random keeps the full-screen random behaviour. Cycle it in SETTINGS → LAYOUT. When a previous line is still fading at the anchor, the new line steps away from the anchored edge instead of being drawn on top of it.
• Every line is still clamped inside the screen using its measured size and rotation, so it can never render off-screen.
• When a translation SIDECAR exists, the main lyric is restricted to the upper half of the screen and the translation always sits in the lower half, so the two can never overlap, regardless of anti_overlap_mode.
• Translation placement is always STRICT now: the main lyric uses the upper half of the safe area and the translation the lower half (safe area = screen minus the visualizer band). The two halves never intersect, so overlap is physically impossible regardless of gaps, randomness, rise or typewriter. The anti_overlap_mode setting (MIRROR / BELOW / AUTO / CUSTOM) is kept for compatibility but no longer changes translation placement.
• Main lyric and translation line avoid each other both at spawn and while moving; each new line is shifted up/down/left/right until the boxes no longer intersect.
• The lyric box is clamped inside the canvas using its measured text size and rotation, so it never renders off-screen at any resolution.
• 随机位置模式下，每一句都会重新取点，直到不与上一句的文本框重叠。
• 在 avoid_window 时间窗（默认 6 秒）内出现的歌词会强制换到不同车道（即使关闭随机位置），间距由 avoid_gap（默认 30 像素）控制，车道步长为 avoid_step（屏高百分比，默认 10）；均在 SETTINGS → LAYOUT 可调。
• 另外，与最近 2.5 秒内任何歌词的重叠是硬约束（至少 12px）。avoid_gap 设得再大也只是放宽偏好间距，不会让相近歌词共用同一个位置。
• 每一句都是独立歌词：新句出现时，上一句仍留在自己的位置继续完成它自己的渐隐（不会被就地替换），新句则另选位置并避开所有仍然可见的旧句。因此 0.1 秒间隔的连句不会挤到同一处，两段的淡入/淡出互不影响；所有歌曲都按这个方式处理。
• 位置由用户决定：random_position（默认 true）时每句在 pos_x_min/max × pos_y_min/max 百分比范围内随机出现，默认范围为整屏（0–100）；关闭后所有歌词固定在该范围的中心点。
• 固定位置（position_anchor，默认 random）：可选 top-left / top / top-right / left / center / right / bottom-left / bottom / bottom-right，把歌词固定钉在对应位置（例如左下 / 右下）；random 则保持全屏随机。可在 SETTINGS → LAYOUT 里循环切换。若上一句还在锚点处渐隐，新句会沿着远离该边缘的方向逐级让位，不会直接压上去。
• 每句都会按实际文字尺寸和旋转角度钳制在屏幕内，不会跑出屏幕。
• 存在翻译 sidecar 时，主歌词限制在屏幕上半、翻译固定在屏幕下半，两者无论 anti_overlap_mode 怎么设置都不可能重叠。
• 翻译歌词现在固定使用分区 STRICT：主歌词占安全区上半，翻译占下半（安全区 = 屏幕去掉波形占用带），两个区域互不相交，物理上不可能重叠（不受间距、随机、上飘、逐字显示影响）。anti_overlap_mode 里的 MIRROR / BELOW / AUTO / CUSTOM 仅为兼容旧配置保留，不再改变翻译位置。
• 主歌词与翻译歌词在生成和移动过程中都会互相避让，上下左右错开直到包围盒不相交。
• 歌词框会按实际文字尺寸和旋转角度限制在画布内，任意分辨率下都不会跑到屏幕外。

Fields from the external tool that are ignored / 不生效的外部工具字段

loop, trans_only, mode, margin_time, max_interval, max_duration, player, source, inst_patterns, netease_adapter_enabled, presets, players. These belong to an external player's lyric fetching / auto timing. In game, the SRT timeline is used directly.

这些属于外部播放器抓词/自动时间轴的部分；游戏内直接使用 SRT 时间轴。

Lyrics source / 歌词来源

Songs: this mod bundles no audio at all. It only reads the tracks already placed in ULTRAKILL's built-in Cyber Grind music folder — ULTRAKILL/Cybergrind/Music (shown as Cybergrind/Music below). The F5 MUSIC page lists exactly that folder recursively. For official tracks, use the ULTRAKILL-OST category, which maps to Cybergrind/Music/ULTRAKILL-OST (created automatically).

歌曲： 本 mod 不附带任何音频，只读取 ULTRAKILL 自带电子血宫音乐文件夹 ULTRAKILL/Cybergrind/Music（下文简写为 Cybergrind/Music）里已有的曲目；F5 的 MUSIC 页就是递归列出这个文件夹。官方歌曲使用 ULTRAKILL-OST 分类，对应 Cybergrind/Music/ULTRAKILL-OST（不存在时自动创建）。

Same as the original mod: a .srt file with the exact same filename next to the audio file.

与原 mod 相同：音频旁同名 .srt（同目录）。

Cybergrind/Music/Mili - Rendezvous/Mili - Rendezvous.mp3
Cybergrind/Music/Mili - Rendezvous/Mili - Rendezvous.srt

Folder-form songs are fully supported. Inside the song folder, the main subtitle can be any of:

• <audio file name>.srt (preferred);
• <folder name>.srt;
• any other .srt in the folder (files that look like translation sidecars, e.g. .zh.srt / .trans.srt, are skipped as the main subtitle).

Translation sidecars are also read from the same folder. A level BGM replaced through F5 → MUSIC follows the same rules and displays its lyrics from the replacement track's own playback position.

文件夹形式的歌曲已完整支持。歌曲文件夹里的主字幕可以是：

• <音频文件名>.srt（优先）；
• <文件夹名>.srt；
• 该文件夹内任意其他 .srt（类似翻译字幕的例如 .zh.srt / .trans.srt 不会被当作主字幕）。

翻译字幕同样从该文件夹读取。通过 F5 → MUSIC 取代的关卡 BGM 也按相同规则读取字幕，并按替代曲目自己的播放进度显示歌词。

Bilingual lyrics / 双语歌词

Add a second, translated SRT next to the track. Any of these suffixes is picked up automatically:

在音频旁再放一份翻译字幕，以下后缀会被自动识别：

Track.zh.srt   Track.cn.srt   Track.chs.srt   Track.cht.srt
Track.ja.srt   Track.jp.srt   Track.trans.srt Track.translation.srt
Track.中文.srt  Track.翻译.srt
Track_zh.srt   Track_cn.srt   Track_ja.srt    Track_trans.srt

• The original line and the translation line are shown at the same time, at different positions.

• The translation line is placed separately and is shifted until it does not overlap the main lyric box; both are clamped on-screen.

• Translation style: translation_enabled, translation_font_size (absolute size for the translated text; 0 = auto), translation_scale (used only when the absolute size is 0; default 0.75), translation_color (default #d8d8d8), editable in the TRANS / 翻译 page of the in-game settings panel.

• The main lyric and the translation line have independent font sizes: set font_size for the original language and translation_font_size for the translated language.

• 原歌词与翻译歌词会同时显示，位置不同。

• 翻译行单独取点，会自动上下移动直到不与主歌词框重叠；两者都被限制在屏幕内。

• 翻译样式：translation_enabled、translation_font_size（翻译文字的绝对字号，0 表示自动）、translation_scale（仅当绝对字号为 0 时生效，默认 0.75）、translation_color（默认 #d8d8d8），可在游戏内设置的 TRANS / 翻译 页修改。

• 主歌词与翻译歌词的字号相互独立：font_size 设置原文语言字号，translation_font_size 设置翻译语言字号。

Special thanks / 特别感谢

• greycsont — ULTRAKILL font reference and font mods (Fffffff / FNT_font_no_tsubasa).

• Flazhik and the Jukebox / CybergrindMusicExplorer team — the original mod this extension depends on.

• end_4 / Thorn — HUD framework used by Jukebox.ThornExtensions.

• Google Fonts / Noto team — Noto Sans JP / Noto Sans SC (SIL OFL 1.1); users may install them, but no font files are bundled.

• SubtitlesParser, RTLTMPro, TagLib# authors — runtime libraries supplied by CGME (not redistributed here).

• greycsont —— ULTRAKILL 字体参考与字体 mod（Fffffff / FNT_font_no_tsubasa）。

• Flazhik 与 Jukebox / CybergrindMusicExplorer 团队 —— 本扩展所依赖的原版 mod。

• end_4 / Thorn —— Jukebox.ThornExtensions 使用的 HUD 框架。

• Google Fonts / Noto 团队 —— Noto Sans JP / Noto Sans SC（可由用户自行安装，本包不再附带字体文件）。

• SubtitlesParser、RTLTMPro、TagLib# 的作者 —— 运行时库由 CGME 提供，本包不再分发。

Fonts / 字体

This extension ships no font files. English/Latin text uses ULTRAKILL's own TMP font (VCR OSD). All non-English (CJK) text automatically uses the fonts shipped by greycsont-Fffffff — Fusion Pixel 10px Mono zh_hans, with Unifont-T as the fallback. A system font is created only if Fffffff is unavailable.

本扩展不附带字体文件。英文/拉丁文字使用 ULTRAKILL 自带的 VCR OSD 字体；除英文外的中日韩文本会自动使用 greycsont-Fffffff 自带字库（Fusion Pixel 10px Mono zh_hans，回退 Unifont-T）。只有 Fffffff 不可用时才会动态生成系统字体。

Known limitations / 已知限制

• The original SubtitlesPanel is blanked. Thorn's Subtitle HUD module keeps an empty frame (auto-hidden when HideBackgroundWhenEmpty).

• Fonts are chosen per line: English / Latin lines use the ULTRAKILL official VCR OSD font. Non-English (CJK) lines automatically use greycsont-Fffffff's own fonts (Fusion Pixel 10px Mono zh_hans, fallback Unifont-T); a dynamic system font is used only if Fffffff is unavailable.

• Outline/glow depend on the TMP shader variants shipped with the game; glow may be missing if the variant was stripped.

• Changing font_family requires a restart.

• Lyric text is NFKC-normalized at runtime: CJK compatibility ideographs (e.g. U+F9EC 溺 → 溺), variation selectors and stray control characters are removed, so copy-pasted lyrics cannot flicker as missing glyphs.

• Diagnostics are written to BepInEx/LogOutput.log under [Jukebox LimbusCompany] (normalized text, line placement, and a warning if an overlap is still detected).

• The cover / title / artist row position and its window adaptation may still be inaccurate in some window sizes or aspect ratios; the author (6r3²n) lacks the computer knowledge to fully fix it.

• 曲绘 / 曲名 / 作者行的位置及其窗口自适应，在部分窗口尺寸或宽高比下仍可能不准确；作者（6r3²n）计算机知识不足，无法完全修复。

• No downloader is bundled. yt-dlp, ffmpeg, ffprobe and yt-dlp.sha256 are not included. URL / YouTube downloading is handled by CGME itself when its Downloader is installed; this extension never downloads anything.

• Only the lyric layer is added. CGME's non-lyric localization extras and helper scripts are not included; the Jukebox core (player, playlists, menu) is still required and remains as-is.

• Known issue: in some cases lyrics may still overlap; the author (6r3²n) lacks computer knowledge and made this mod with AI, but the AI used could not fix this issue.

• 原版 SubtitlesPanel 被置空；Thorn 的 Subtitle HUD 模块会保留一个空框（HideBackgroundWhenEmpty 时自动隐藏）。

• 特别感谢 greycsont 提供的 ULTRAKILL 字体。 / Special thanks to greycsont for the ULTRAKILL font.

• 字体按行自动选择：英文/拉丁行使用 ULTRAKILL 官方 VCR OSD 字体；除英文外的中日韩文本自动使用 greycsont-Fffffff 自带字库（Fusion Pixel 10px Mono zh_hans，回退 Unifont-T）；只有 Fffffff 不可用时才动态生成系统字体。

• 描边/辉光依赖游戏内 TMP 着色器变体；若被裁剪可能看不到辉光。

• 换 font_family 需重启游戏。

• 歌词在运行时做 NFKC 归一化：CJK 兼容汉字（如 U+F9EC 溺 → 溺）、变体选择符和多余控制字符会被替换/移除，避免从音乐平台复制的歌词因缺字反复闪烁。

• 诊断信息写入 BepInEx/LogOutput.log 的 [Jukebox LimbusCompany] 下（字符归一化、每句落点，以及仍检测到重叠时的警告）。

• 不附带任何下载器。 不包含 yt-dlp、ffmpeg、ffprobe、yt-dlp.sha256。URL / YouTube 下载由 CGME 自身的 Downloader 负责（若已安装）；本扩展不会下载任何内容。

• 本包只新增歌词层。 不包含 CGME 的非歌词本地化内容与辅助脚本；Jukebox 核心（播放器、播放列表、菜单）仍是必需部分，保持原样。

• 已知问题： 部分情况下歌词仍可能重叠；作者（6r3²n）计算机知识不足，使用 AI 制作此 mod，但所使用的 AI 无法修复该问题。