3D PLAYLIST SHELF MEMORY
3D Playlist Shelf Memory
2026-06-24 详情页歌词可读与避让边界
- 3D 歌单详情页打开时，歌词不能再被压成几乎不可见；用户要的是“默认歌词仍可读，只是不挡歌单详情页”，避让应主要靠 stageLyrics.group.renderOrder 低于详情页和削弱 glow/sun/spark。
- 当前边界：updateStageLyrics3D() 的 shelfDetailLyricProfile 普通详情页文字 opacity 约 0.38、骷髅详情页约 0.30；readability/辉光单独降低，退场歌词也乘 outgoing，防止选歌、切歌或新词进来时突然跳亮。
- 禁止回退：不要把详情页歌词目标透明度恢复到 0.055 左右；不要只压当前歌词而放任旧词退场保持高亮；不要让发光层重新横穿详情页中心高亮行。
2026-06-24 常驻实卡质感与歌词层级
- 常驻 3D 歌单架默认视觉要接近右键展开后的实体卡效果，不能再把 passiveAlways 压成灰暗半透明幽灵卡；当前边界是保留 shelfBgOpacity 的实卡黑玻璃底，passiveAlways 只做极轻微透明/亮度压制。
- 层级不能因此回退：常驻未命中时 shelf group/card 仍保持在歌词后层，避免长期遮挡歌词；只有鼠标真实命中/选中卡片后，通过 selected / floatMix 浮起动画把卡片抬到歌词前景。
- 常驻侧栏中，已选卡片只在光标仍处于活动显示状态时允许升到歌词前方；光标自动隐藏后应让 floatMix 有界退场并回到后层，不能让一次旧悬停永久压住歌词。
- 多行歌词不能只提升行 Mesh 或最外层 stageLyrics.group；rowLayerGroup、contextGroup、readabilityGroup 必须同步当前 renderBase，防止 Three.js 嵌套 Group 重写透明排序层级。
- 相关位置：public/index.html 的 makeShelfManager().placeCard()，关注 passiveAlways、floatMix、card.mesh.renderOrder、group.renderOrder 和 shelfVisibility。
- 禁止回退：不要为了让常驻卡片更清楚而把整组歌单架永久放到歌词上层；不要再把常驻默认卡片透明度压回 0.5 左右导致看起来像没有右键展开质感。
2026-06-24 自动隐藏触发区边界
- 3D 歌单架在“自动隐藏”显示状态下，不允许保留右侧隐形动态镜头触发区；只有歌单架已经显示、正在淡入/淡出可见、详情页打开、固定展开、常驻真实卡片命中或视觉引导时，shelfAutoHiddenInputReady() 才能放行动态镜头 focus、hover 高亮和滚轮接管。
- fullscreen DIY 悬浮入口不能和视觉控制台/视觉引导/热键弹窗抢层级；shouldSuppressFullscreenDiyPeek() 需要在这些场景下移除 fullscreen-diy-peek，不要再靠提高 z-index 硬压。
2026-06-24 内容开关与连续滚动
- 3D 歌单架内容开关必须保留：fx.shelfShowPodcasts 默认 true，用于控制播客歌单是否显示；fx.shelfMergeCollections 默认 false，默认仍保留“我的歌单滚到底再进入收藏歌单”的二段体验。
- 开启“合并收藏歌单”后，activePlaylists() 应返回 mine.concat(fav)，滚轮一路向下就是我的歌单到收藏歌单，不再触发 switchPane('fav') 的二段切页。
- 切换播客显示或合并收藏时必须重建 shelf，并且列表签名要包含开关值、播客数量和实际 item 采样，避免 UI 开关亮了但 3D 卡片还停在旧内容。
- 不要把播客永久移出歌单架，也不要把合并收藏设成默认开启；这是用户可选的内容组织方式，不是替换原手感。
2026-06-24 动态/静态详情页边界
- 动态镜头模式下，歌单详情页必须跟随镜头，使用 camera.quaternion 面向当前镜头；不要把动态详情页也绑到封面粒子旋转上。
- 静态/固定镜头模式下，歌单详情页才跟封面粒子/画布绑定旋转移动，避免像硬贴镜头。
- 动态镜头 + 常驻歌单架同时开启时，常驻未展开状态不能用 shelfAlwaysVisible() 直接触发 shelf focus、滚轮或点击；只允许真实卡片命中触发，封面粒子/画布区域继续留给画布交互。
更新时间：2026-06-24
这份文档保存 3D 歌单架已经调好的交互和视觉边界。后续修改歌单架时先读本文件，优先小步调整，不要推倒重做。
已确认的功能边界
- 视觉控制台里保留「3D / 手势」折叠分组，入口文案为「歌单架 / 摄像头交互」。
- 歌单架模式保留三段：关闭、侧栏、舞台。
- 歌单架镜头保留两段：动态镜头、静态镜头。
- 歌单架显示保留两段：自动隐藏、常驻。
- 歌单架外观保留独立颜色，不只跟随全局高亮色；颜色需要接入高级取色器和用户存档快照。
- 参数滑条保留：歌单架大小、左右位置、上下位置、前后景深、侧向角度、整体透明度、背景透明度。
关键实现位置
- 主文件：public/index.html
- 控制台 UI：#shelf-seg、#shelf-camera-seg、#shelf-presence-seg、#shelf-accent-picker、#fx-shelfsize、#fx-shelfx、#fx-shelfy、#fx-shelfz、#fx-shelfangle、#fx-shelfopacity、#fx-shelfbgalpha
- 默认状态：fxDefaults.shelf、shelfCameraMode、shelfPresence、shelfSize、shelfOffsetX、shelfOffsetY、shelfOffsetZ、shelfAngleY、shelfOpacity、shelfBgOpacity、shelfAccentColor
- 调参入口：shelfLayoutProfile()、makeShelfManager()、makeContentListManager()、setFocusZone()
手感边界
- 不要把歌单架手感推倒重做；最强手感来自 hover 透明度、视差、展开节奏、轻微浮动和旧版张力线索。
- 后续优化应在 makeShelfManager() / makeContentListManager() 周围小步调参。
- 悬停展开和点击可用之间要更清楚，避免用户以为 hover 后已经可以直接操作。
- 滚动选择必须跟随中心卡/中心行高亮，并触发短促、清脆、偏 PSP 的机械齿轮咔哒反馈；当前用 WebAudio 合成，不额外依赖二进制音效素材。
- 选择音效要偏清脆金属齿点，不要太钝、太闷或低频太厚；以后如果替换开源素材，优先找许可证明确、清脆机械咔哒质感的短 UI selection。
- 侧栏滚轮接管区不能再使用半屏 shelfPreviewUseZone；滚轮只在真实卡片命中、详情页实际面板/行命中，或右侧窄热区内接管，避免抢走封面粒子半边滚轮交互。
- 性能优化不要回到一次性渲染全部歌单或全部歌曲。
镜头和布局边界
- 动态镜头保留当前默认聚焦逻辑。
- 静态镜头要阻止歌单架触发镜头跟随，不要让画面被歌单架突然拉走。
- 侧栏歌单架的角度偏好：动态镜头默认 0；静态/固定镜头默认 -15，这个角度才更接近与画布粒子平行。用户手动拖动侧向角度滑条后才视为自定义角度。
- 常驻模式下，侧栏歌单架需要跟随粒子封面角度绑定，保持和舞台视觉同向。
- 常驻模式下，未悬停选中时侧栏歌单架应退到歌词后层并降低存在感；鼠标命中卡片后再通过 selected / floatMix 浮起到歌词前景，形成上浮动画和高亮描边。
- 常驻或详情页打开时，歌词需要主动避让，减少遮挡歌单架操作；但常驻未选中卡片不能长期压住歌词。
- 歌单详情页层级必须高于歌单卡片，打开后盖在卡片最上层，便于选择歌曲。
- 歌单详情页需要保持选中行居中和完整页面显示；普通非骷髅布局不要再回到过右、偏下、右侧被裁切的详情页位置。
- 歌单详情页打开时要和封面粒子/画布绑定旋转与轻微移动，不能像相机贴片一样硬跟随镜头；中心高亮行应尽量和歌词保持同一水平线，面板不能显小、偏下。
- 歌词与封面粒子画布的绑定必须使用同一个世界位置和世界四元数基准；不要再用相机坐标轴叠加封面欧拉角，否则左上方俯视/大角度旋转时会出现歌词偏轴、倾斜过度、像绕另一个轴运动的 bug。
- 歌单详情页打开时歌词必须主动让出可读性：降低歌词 renderOrder/亮度/辉光/可读性层，详情页中心高亮行不能被歌词横穿遮挡，尤其固定/静态状态下。
- 安魂/骷髅预设打开 3D 歌单架时，应保持左侧大骷髅近景、右侧偏中歌单架构图。
禁止回退
- 不要恢复 3D 歌单架强制切回星河预设的问题。
- 不要恢复常驻歌单架长期遮挡歌词的问题；常驻默认退后，只有悬停/选中卡片才浮到歌词上层。
- 不要恢复滚动选中高亮不跟随、滚轮热区吃掉封面粒子半屏、或选择音效完全静默的状态。
- 不要把静态/固定镜头默认角度改回 0；不要让详情页打开后硬跟随镜头、偏小、偏下或脱离画布粒子运动。
- 不要恢复歌词在画布大角度旋转时偏轴倾斜、或固定详情页被歌词发光层挡住的状态。
- 不要恢复详情页被卡片遮挡、滚动卡手、按钮设计偏差、Home 与后方歌单架误穿透的旧问题。
- 不要恢复详情页右侧被隐藏、整体偏下不居中的旧布局。
- 不要让右键唤起歌单架时误唤出底部播放器控制台；歌单架打开期间应抑制底部控制台热区。
- 不要因为 shelf 重建或 3D 详情列表绘制失败而误报“歌单加载失败”。
---
DESKTOP LYRICS VISUAL
Desktop Lyrics Visual Baseline
Last saved: 2026-06-22
Approved Effect
- The approved desktop lyrics effect keeps the lyric fill color true to the in-app lyric color. Do not tint the glyph interior gray, yellow, green, or black for contrast.
- White-background readability is handled by a neutral outside feather only:
- .lyric-viewport uses filter: drop-shadow(0 1px 2.4px rgba(4,6,12,.58)) drop-shadow(0 0 4.8px rgba(4,6,12,.30)).
- .line uses a very light white stroke: -webkit-text-stroke:.18px rgba(255,255,255,.72).
- .line text glow stays color-based and subtle: text-shadow:0 0 1px rgba(255,255,255,.34), ... var(--lyric-shadow-soft), ... var(--lyric-shadow-glow).
- The dark/black background result must remain crisp: white lyric core, restrained glow, no gray fog covering the text.
- Highlight-follow may show a soft lyric-progress gold/cyan transition, but the non-highlighted glyph interior must not become dirty or split into gray/yellow bands.
Interaction Baseline
- Locked desktop lyrics must not block operations behind the lyric window. In locked state, the Electron overlay should be mouse-through.
- Unlock/lock is handled by the main process middle-mouse poller using GetAsyncKeyState(4) and the lyric hot bounds. This lets middle-click work even when the overlay is click-through.
- Renderer hover logic must not call pointer capture while locked. Locked hover may show the delayed hint, but it must keep setPointerCapture(false).
- Unlocked state may capture pointer for dragging and the close button only.
Do Not Regress
- Do not restore mix-blend-mode, difference, multiply, .line::before, or .line::after contrast layers for lyric readability.
- Do not use dark pseudo text layers or heavy dark strokes that turn the glyph interior gray.
- Do not reintroduce magnet/snap behavior for dragging unless the user explicitly asks.
- Do not make the locked lyric window intercept background clicks in order to support middle-click; keep middle-click in the main-process poller.
- Verify both white and black backgrounds after changes. White should be readable without color pollution; black should stay clear and bright.
---
GLASS SVG TEXTURE
Mineradio SVG Glass Texture
这是用户明确要求保存的播放器 SVG 玻璃质感基线。后续可以修补偏移、缺角、套用范围和响应式问题，但不要随意重写核心质感。
User Approval
用户已经确认：当前播放器控制台质感要保存，并计划逐步套用到搜索栏、小按钮、部分面板和 3D 歌单架。
用户不接受：
- 普通毛玻璃，没有扭曲质感。
- 中间糊成一团的毛玻璃。
- 大面积白色渐变扫过去的廉价质感。
- 右侧缺一块、整体右偏、上下错位明显。
- 因套用 SVG 导致性能明显下降。
Core CSS Variables
位置：public/index.html 顶部 :root。
:root{
--saved-panel-glass-bg:rgba(0,0,0,.10);
--saved-panel-glass-filter:blur(12px) saturate(1.8) brightness(1.16);
--saved-panel-glass-svg-filter:url(#mineradio-control-glass-filter) saturate(1);
--saved-panel-glass-shadow:inset 0 0 2px 1px rgba(255,255,255,.35),inset 0 0 10px 4px rgba(255,255,255,.15),0 4px 16px rgba(17,17,26,.05),0 8px 24px rgba(17,17,26,.05),0 16px 56px rgba(17,17,26,.05),inset 0 4px 16px rgba(17,17,26,.05),inset 0 8px 24px rgba(17,17,26,.05),inset 0 16px 56px rgba(17,17,26,.05);
--saved-panel-glass-radius:50px;
--saved-button-glass-bg:rgba(0,0,0,.10);
--saved-button-glass-filter:blur(12px) saturate(1.8) brightness(1.16);
--saved-button-glass-svg-filter:url(#mineradio-control-glass-filter) saturate(1);
--saved-button-glass-shadow:inset 0 0 2px 1px rgba(255,255,255,.34),inset 0 0 10px 4px rgba(255,255,255,.13),0 10px 30px rgba(0,0,0,.18);
--saved-button-glass-hover-bg:rgba(255,255,255,.055);
--saved-button-glass-hover-shadow:inset 0 0 2px 1px rgba(255,255,255,.42),inset 0 0 12px 5px rgba(255,255,255,.17),0 12px 34px rgba(0,0,0,.22),0 0 18px rgba(255,255,255,.06);
}Bottom Bar Baseline
位置：public/index.html 的 #bottom-bar。
#bottom-bar{
border-radius:50px;
background:rgba(0,0,0,.10);
border:0;
backdrop-filter:blur(12px) saturate(1.8) brightness(1.16);
-webkit-backdrop-filter:blur(12px) saturate(1.8) brightness(1.16);
box-shadow:inset 0 0 2px 1px rgba(255,255,255,.35),inset 0 0 10px 4px rgba(255,255,255,.15),0 4px 16px rgba(17,17,26,.05),0 8px 24px rgba(17,17,26,.05),0 16px 56px rgba(17,17,26,.05),inset 0 4px 16px rgba(17,17,26,.05),inset 0 8px 24px rgba(17,17,26,.05),inset 0 16px 56px rgba(17,17,26,.05);
}
html.control-glass-svg-ok #bottom-bar{
background:rgba(0,0,0,.10);
backdrop-filter:url(#mineradio-control-glass-filter) saturate(1);
-webkit-backdrop-filter:url(#mineradio-control-glass-filter) saturate(1);
}
#bottom-bar::before{content:none}
#bottom-bar::after{content:none}SVG Filter Baseline
位置：public/index.html 的 <svg id="control-glass-svg">。
关键点：
- color-interpolation-filters="sRGB"
- 主 filter：id="mineradio-control-glass-filter"
- filter 区域：x="-12%" y="-28%" width="124%" height="156%"
- RGB 三通道 displacement scale：Red 180、Green 170、Blue 160
- RGB 共同对齐中心：dx="-90" dy="0"；controlGlassChromaticOffset 只能围绕该中心做 Red/Green/Blue 相对分离，不要再整体平移所有通道；UI 下限为 30，这是保留最低可见色差的底线。
- merge 后用 screen 混合。
- 最后 feGaussianBlur stdDeviation="0.5"。
不要把 RGB 偏移改成正向、不要删三通道色差、不要把 stdDeviation 拉大。
色差滑块的当前语义：30 为最低可见通道分离，默认值 90 保持共同中心 -90 并增加适中 RGB 边缘分离，最大值 140 只扩大三通道相对距离，不移动整块玻璃。
Displacement Map Generator
位置：public/index.html 的 generateControlGlassDisplacementMap(width, height, radius)。
核心参数：
width = Math.max(240, Math.round(width || 400));
height = Math.max(48, Math.round(height || 92));
radius = Math.max(12, Math.round(radius || 50));
var borderWidth = 0.07;
var edge = Math.min(width, height) (borderWidth 0.5);核心 SVG：
'<linearGradient id="glass-red" x1="100%" y1="0%" x2="0%" y2="0%"><stop offset="0%" stop-color="#0000"/><stop offset="100%" stop-color="red"/></linearGradient>' +
'<linearGradient id="glass-blue" x1="0%" y1="0%" x2="0%" y2="100%"><stop offset="0%" stop-color="#0000"/><stop offset="100%" stop-color="blue"/></linearGradient>' +
'<rect x="0" y="0" width="' + width + '" height="' + height + '" fill="black"/>' +
'<rect x="0" y="0" width="' + width + '" height="' + height + '" rx="' + radius + '" fill="url(#glass-red)"/>' +
'<rect x="0" y="0" width="' + width + '" height="' + height + '" rx="' + radius + '" fill="url(#glass-blue)" style="mix-blend-mode:difference"/>' +
'<rect x="' + edge.toFixed(2) + '" y="' + edge.toFixed(2) + '" width="' + innerW.toFixed(2) + '" height="' + innerH.toFixed(2) + '" rx="' + radius + '" fill="hsl(0 0% 50% / 1)" style="filter:blur(11px)"/>'Search Reveal Timing
搜索栏必须像底部播放器控制台一样“带着 SVG 质感一起出现”，不能先显示透明玻璃框，再等动画结束才加载色散。
- setPeek(..., true, 'search') 前先调用 prepareSearchGlassBeforePeek()。
- 如果搜索栏还处在 search-glass-priming，不要立刻添加 peek；等 search-glass-ready / search-glass-fallback 出现，或最多等约 140ms 兜底后再显示。
- updateSearchBoxGlassDisplacementMap() 不能在 search-glass-priming 期间因为二次调用直接把状态切成 ready，否则会绕过预热帧，造成首帧无 SVG 质感。
- .search-mode-tabs 容器不能再盖一层 rgba(0,0,0,.90) 的普通 blur 黑底；外层 rail 保持透明，SVG 质感只放在每个 tab 胶囊按钮上。
- quick-check 的 Search glass entrance guard 必须验证首帧没有提前 peek，下一帧后才带着 url(#mineradio-search-box-glass-filter) 出现。
Search reveal surface rule: search must mirror the bottom bar reveal. Hidden #search-box stays transparent with backdrop-filter:none; visible #search-area.peek #search-box carries the saved panel background/shadow and, when SVG is available, directly uses url(#mineradio-search-box-glass-filter) saturate(1). Do not put the search box SVG glass on #search-box::before; that creates a separate layer from the reveal state and can make the popup feel like the SVG arrives late.
Wallpaper Engine Single-Surface Rule
2026-07-18 用户明确否定了额外的“可直接透明”玻璃层。旧方案 Mineradio WE Glass Refraction、第二个圆角 DWM 面、DwmQueryThumbnailSourceSize 局部取样与 1.105 放大/错位全部失效，禁止恢复。
当前唯一允许的实现：
- 原生层只有一个全窗 Mineradio WE DWM Surface；精确 WE 源窗仍在它下面保持真实 Windows 鼠标视差。
- #wallpaper-engine-glass-sampler 只裁切真实 #bottom-bar；内部视频保持完整视口 1:1 对齐，不做缩放镜片或二次折射。
- 采样源 HWND 必须与唯一基础 DWM HWND 相同。运行时兼容字段 dwmGlassSurfaceWindowId 只是该 HWND 的别名，不代表第二个窗口。
- 采样流必须在 DWM 缩略图激活前对普通基础 HWND 建立；捕获首帧后再激活同一 HWND 的 DWM 缩略图，并在预热黑帧变成真实壁纸像素后才添加 wallpaper-engine-glass-sampler-ready。
- 最终扭曲和 RGB 色散只由既有 #mineradio-control-glass-filter 产生。Red 180、Green 170、Blue 160、共同中心 -90、screen 混合、stdDeviation=0.5 等冻结参数不因 WE 接入改变。
- 采样 HWND 本身没有光标画面；不得用读取/隐藏/替换系统光标或 DOM 假光标处理捕获。Scene 停止、切换、隐藏或退出时必须停止该 MediaStream。
验收时同时检查：Mineradio WE Glass Refraction 窗口数为 0、基础 HWND 与采样源 HWND 相等、采样视频轨为 live 且无音频、采样器矩形与控制台矩形一致、最大化/还原后仍对齐。
Safe Change Rules
- 可以：修复右侧缺块、尺寸缓存、ResizeObserver 更新、特定面板的 SVG map 尺寸。
- 可以：给搜索栏、小按钮等新增独立 filter/map，避免共享同一个大尺寸 map。
- 谨慎：调整 filter 区域、offset、scale。改前截图对比。
- 禁止：把 controlGlassChromaticOffset 改回同时设置所有 feOffset dx 的整体左右偏移。
- 禁止：整体替换为普通 blur() 毛玻璃。
- 禁止：为了性能删除色差或扭曲质感。性能要通过节流、缓存、减少实时重算来做。
Verification Checklist
在黑底和亮底都看一遍：
- 控制台右侧没有缺块。
- 搜索栏没有右侧缺失、整体右偏或白色廉价渐变。
- 播放器中间不是糊的，仍有水波扭曲和 RGB 色差。
- 鼠标 hover、播放暂停、切歌后没有明显卡顿。
---
INSTALLER STYLE
2026-06-25 P0 Installer Safety Notes
- Full setup adoption rule: the installer may adopt an existing registered install only when the registered path itself is a dedicated ...\Mineradio directory and contains Mineradio files or .mineradio-install-root; mixed parent folders and drive roots must stay blocked/quarantined.
- Quick patch rule: installer/uninstaller safety bugs cannot be fixed by a quick patch JSON alone, because the Windows uninstaller and install registry must be replaced by the full NSIS setup.
2026-06-26 Fixed Installer Packaging Baseline
- Future Windows releases must keep the repaired v1.1.1 installer shape: custom NSIS pages and safety logic from build/installer.nsh, full setup .exe, .blockmap, latest.yml, and SHA256SUMS.
- Baseline release asset: Mineradio-1.1.1-Setup.exe, SHA256 1d35750c5b9c5099bd608baa4cc8564d5a08a183dccb2aa7ab85ef613fd536f7, size 115090051 bytes.
- Do not publish installer/uninstaller safety fixes as quick patch JSON only. They must be delivered by a full setup package so the Windows uninstaller and registry are replaced.
- Never remove customRemoveFiles or restore electron-builder's default recursive $INSTDIR deletion path. Keep deletion limited to known Mineradio/Electron top-level files and non-recursive empty-directory cleanup.
- Keep safe overwrite behavior: existing dedicated ...\Mineradio folders containing Mineradio files can be overwritten; mixed folders, parent folders, drive roots, and user data folders must stay blocked or quarantined.
Mineradio Installer Style
2026-06-22 用户确认保留当前安装包格式。以后发布安装包，默认沿用这套样式和流程，除非用户明确要求重做。
视觉方向
- 中文极简安装器。
- 主色：白底 #FFFFFF，主文字 #111217，弱文字 #4B5263 / #6B7280，蓝色点缀 #3257F7。
- 不要再使用红色 MR、深色大卡片、复杂装饰、英文大段说明或黑底黑字。
- 顶部横幅和侧边图保持黑白蓝极简：build/installerHeader.bmp、build/installerSidebar.bmp。
页面结构
- 欢迎页只保留：
- MINERADIO
- Mineradio 安装
- 简短中文说明
- 默认位置：D:\Mineradio
- 安装目录页只保留：
- 选择安装位置
- 简短中文说明
- 安装目录 输入框
- 浏览... 按钮
- 默认推荐：D:\Mineradio；选盘符会自动建文件夹。
技术边界
- 使用 build/installer.nsh 的自定义欢迎页和自定义安装目录页。
- package.json 中 build.nsis.allowToChangeInstallationDirectory 保持 false，避免 electron-builder 原生目录页读取旧安装注册表后回填到 AppData\Local\Programs\Mineradio。
- 自定义目录页必须保留可编辑输入框和 浏览... 按钮。
- 默认路径通过 MineradioUsePreferredInstallDir 设置为 D:\Mineradio；命令行 /D= 参数仍可覆盖。
- 用户选择盘符根目录时，通过 MineradioNormalizeInstallDir 自动补成 盘符:\Mineradio。
发布前验证
发布前必须本地打开新生成的 dist\Mineradio-版本-Setup.exe 验证：
- 欢迎页显示中文极简样式，默认位置为 D:\Mineradio。
- 安装目录页输入框显示 D:\Mineradio。
- 浏览... 按钮能弹出中文文件夹选择窗口。
- 验证时不要点 安装，确认后取消退出。
2026-06-25 安装安全补充
- 默认安装路径从 D:\Mineradio 开始按 D-Z 顺序选择第一个存在的盘；只有电脑不存在任何 D-Z 盘时，才允许默认落到 C:\Mineradio。
- 用户手动选择目录时，安装器必须强制落到独立 Mineradio 子文件夹；若 D-Z 盘存在，手动选择 C 盘也要阻止。
- 非空且无法识别为 Mineradio 的目录必须阻止安装，避免卸载阶段删除用户其它文件。
- 新安装器写入 .mineradio-install-root 标记；新卸载器必须先验证路径和标记/主程序/卸载器，再进入卸载。
- 新卸载器禁止使用 RMDir /r $INSTDIR 删除整个安装根目录，也禁止递归删除 resources、locales 等应用子目录；只能删除 Mineradio/Electron 顶层已知文件，最后用非递归 RMDir "$INSTDIR" 尝试移除空目录。
- 安装新版本时，若检测到旧版本没有 .mineradio-install-root 安全标记，必须跳过旧卸载器，只删除旧目录中的 Uninstall Mineradio.exe 单文件并清理卸载注册表，避免触发历史安装包的整目录递归删除逻辑。
---
LOW SPEC OPTIMIZATION DOCTRINE
Mineradio 低配优先优化原则
2026-07-10 - 歌词分帧加载必须保持视觉连续
- 一帧一层纹理上传仍是硬预算，但上传顺序必须先完成当前窗口的所有正文，再放行可读层和辉光；正文未齐时统一保持透明，不能让“少数正文 + 特效”先露出形成断层。
- 当前窗口稳定后，透明预热视野外相邻 1 行的原文和译文。已预热行滚入视野时立即沿用纹理，不再叠加 reveal 延迟；预热仍受每帧 1 层预算约束。
- 同曲轻量/完整轨升级和滑窗跨页必须短暂保留旧 mesh，等新页正文完整后再交叉退场。连续性不能靠同步上传、扩大单帧预算、长期保留双份 mesh 或删除译文/辉光来换取。
2026-07-10 - 歌词构建与 GPU 上传必须同时有预算
- 只把 Canvas 绘制拆帧还不够；歌词纹理第一次进入 WebGL 场景也必须限流。每个歌词更新帧最多放行 1 个新文字/可读/辉光纹理，已上传层再次滚入视野可以立即复用。
- 行纹理分辨率按 renderer 物理宽度和 runtimeHardwareProfile 计算：低配档进一步封顶，高分屏保留更高预算。所有尺寸、字号、基线、描边和辉光半径必须等比缩放，不能靠砍译文、描边、辉光或降低前台动画功能换性能。
- 轻量首屏优先级高于完整轨道预热；完整构建只能在轻量页完成并接管后运行。timer、RAF、idle callback、半成品和旧 mesh 都必须可取消、可去重、可分批释放。
- 独立羽化辉光属于保留视觉边界：允许降低过采样像素，禁止把它裁进文字遮罩同尺寸硬框；也禁止使用 renderer.initTexture() 把上传工作同步塞回主线程。
2026-07-10 - 歌词重任务必须协作调度
- 多行/双语歌词不得在开关、切歌或动画 tick 中一次性创建整窗 CanvasTexture、材质与网格；首屏使用小窗口，稳定播放使用重叠滑窗并提前预热，最终视觉和歌词功能保持完整。
- 单次协作任务只创建 1 个歌词显示行；新歌曲或设置变化必须能取消旧任务并分批释放半成品。隐藏歌词行和附属可读/溢光层保持不可见，进入可见窗口后再分帧显现，避免首帧 GPU 纹理上传峰值。
- 歌词 mesh 销毁不得在用户点击关闭或切歌帧整批执行；资源回收使用有时间预算的小批次队列。
2026-06-29 补充：前瞻加载、无黑闪切歌和可控系统释放
- 大歌单 UI 懒加载不能只在“到底部”才补页。3D 详情、歌单详情和播放队列这类可滚动列表应在用户距离已加载尾部还有一段缓冲时预取下一批，并提前预热下一屏封面，避免滚动断层。
- 切歌背景过渡必须保留旧视觉层直到新封面图片解码成功。封面背景优先使用双层 opacity crossfade，不要在新图 ready 前清空旧背景或把 uHasCover 置空造成黑闪。
- 歌词溢光属于文字的从属视觉层，必须以当前文字 mesh 的位置、缩放和可见状态为锚点；字号、位置、漂浮动画或高亮行变化时，后层溢光不能独立漂移。
- 系统级内存释放允许保留普通手动入口，但自动系统释放、提权释放、UAC/PowerShell 弹窗默认锁定；前台可见播放时应跳过系统释放，最小化/隐藏后才做低风险释放。
- Electron 多进程是 Chromium 架构事实，不以“强行单进程”为优化目标。后台优化应优先停掉不可见渲染、压缩工作集、关闭未启用的桌面歌词/壁纸窗口和降低定时器/IPC 频率。
更新日期：2026-06-29
核心目标
优化版的长期目标不是“只在高端显卡上效果拉满”，而是让低配电脑、核显机器、轻薄本也能稳定、流畅、低占用运行。视觉效果可以高级，但默认实现必须有性能预算、能力检测和降级路径。
基本判断
- 强兼显卡版可以作为参考，但不能整包移植。
- RTX 40 系、DLSS-G、native frame generation、NVIDIA Streamline DLL 只能作为可选高端路径，不能成为默认依赖。
- 非 40 系显卡、核显、老笔记本必须能正常启动、正常播放、正常关闭高级效果。
- 默认策略优先保证稳定帧时间、低 CPU、低功耗、少发热，而不是跑满高刷屏。
新功能必须满足
每个新增视觉、音频、桌面、登录、歌单、歌词或更新功能，都要同时回答：
- 默认是否会增加主循环每帧工作量？
- 是否能在不可见、后台、最小化、未播放时停掉？
- 是否有 dirty flag，只在数据变化时重算？
- 是否有低配降级路径？
- 是否能被用户关闭？
- 是否会引入 40 系或 NVIDIA 专属依赖？
- 是否会增加启动失败或黑屏风险？
没有这些答案的新功能，不应直接进入默认路径。
强兼版代码移植规则
可以优先借鉴：
- Chromium/Electron GPU 启动参数的安全子集
- GPU 信息诊断和日志
- 前后台渲染策略
- 帧率调度、任务分频、脏更新、缓存策略
- 音频分析降频、Worker 化、封面/颜色/深度预处理缓存
必须谨慎或默认排除：
- native FG / DLSS-G / Streamline / NVIDIA DLL
- 只对 RTX 40/50 有意义的功能开关
- 无条件 disable-software-rasterizer
- 默认开启 FSR/NIS/DLSS UI
- 会导致非 NVIDIA 或老机器黑屏的强制 GPU 路径
如果未来接入高端路径，必须做成：
- 自动能力检测
- 默认关闭或自动安全模式
- 非 40 系隐藏或禁用，不报错
- 失败后回退原生 WebGL 渲染
- 日志能说明为什么不可用
低配默认模式
默认前台画面应保证垂直同步的连续感；低配治理不能再靠默认砍掉可见连续运动层的刷新率：
- 主渲染默认使用显示器 requestAnimationFrame / VSync，播放、时间轴拖动、歌词、歌单架和封面连续运动优先逐个显示帧更新。
- 45 / 60 / 75 / 90 / 120 只作为用户在高级性能设置里主动选择的固定上限，不得静默替代默认 VSync。
- 低配优化优先降低音频分析、不可见图层、离屏纹理构建、缓存维护和后台任务频率；可见运动层仍保留插值与连续性。
- 后台/最小化进入深度降载，未播放和不可见任务及时暂停或释放。
- 昂贵歌词纹理只为当前及邻近可见行按需生成，必须使用全舞台共享的字节预算、行数上限、淘汰与显式释放；不得按清晰度倍率重建整首歌词。清晰度换档只能在目标纹理可提交后原子替换旧纹理，最多容纳一张过渡纹理，不能为了省显存让当前行闪回 1×。
- 大计算尽量移出主线程、拆成协作任务或复用缓存。
性能验收
每次性能相关改动都至少记录：
- 前台空闲 CPU
- 播放中 CPU
- 3D 歌单架打开 CPU
- 全屏 CPU
- 后台/最小化 CPU
- window.__mineradioPerf 或 window.__mineradioPerfSnapshot 可用字段
不同电脑差异很大，不用单台机器绝对值吹结论。优先看同场景前后对比、帧时间稳定性、是否卡顿、是否发热明显。
长期开发习惯
- 优先在优化版模块化目录开发：public/js/modules/
- 不再回到旧单文件思路堆几万行代码。
- 大功能先拆边界，再接入主循环。
- 默认路径必须轻，重功能放到显式开关或能力分流里。
- 任何“看起来很酷”的效果，都不能牺牲低配机器的基本播放体验。
激进但可控的优化风格
强兼显卡版的价值不只在具体代码，而在它愿意从 Electron/Chromium 启动参数、GPU 诊断、前后台渲染、任务调度、缓存和原生能力边界一起下手。以后优化版要吸收这种系统级优化风格，不能只做常规的“小改一点 CSS / 少调用一次函数”。
但激进优化必须有硬边界：
- 不出 bug 是第一边界；不能为了低占用引入启动失败、黑屏、播放器失控、歌曲切换异常或设置丢失。
- 不影响现有视觉效果是第二边界；可以按场景降频、暂停不可见层、复用缓存，但前台可见播放观感不能肉眼变差。
- 所有激进路径必须有能力检测、失败回退、日志说明和用户可关闭入口。
- 任何高端 GPU 专属路径都只能作为可选加速层，不得成为默认依赖。
- 目标是低端 CPU 低占用、轻薄本低发热、核显机器可流畅运行；不是只追求高端独显上的峰值效果。
内存压缩与释放策略
内存优化要和 CPU 优化一起做，不能只盯帧率：
- 后台、最小化、不可见、未播放时，释放或暂停非必要纹理、粒子、封面分析、歌词离屏画布、歌单详情缓存。
- 大对象必须有生命周期：创建点、复用点、失效点、释放点要清楚。
- 缓存默认要有容量上限和淘汰策略，不能无限增长。
- 可复用纹理/画布优先池化，避免频繁 GC；长期不用的资源要主动 dispose() 或清空引用。
- Electron 主进程和渲染进程都要避免无意义常驻监听、定时器和 IPC 高频广播。
- 内存压缩类能力只能作为“空闲/后台/最小化”的低风险路径，前台播放中不做会造成卡顿的强制回收。
混合显卡适配原则
以后可以加入核显/独显之间的能力识别和分流，但必须尊重用户机器实际状态：
- 不能在用户禁用核显时硬跑核显。
- 不能假设所有笔记本都有可用核显，也不能假设独显一定存在或一定适合渲染。
- 首选读取 Chromium/Electron GPU 信息、系统可见适配器、渲染器字符串和失败日志，再决定是否启用某条 GPU 路径。
- 默认尊重 Windows / 显卡驱动 / 用户设置的 GPU 选择；软件内部只做建议、检测和安全分流。
- 独显可用于高视觉负载，核显可用于低功耗路径，但必须有黑屏/初始化失败回退到原生 WebGL 或软件兼容路径。
- 显卡切换能力要记录日志：当前选择了哪个 renderer，为什么选它，哪些高级能力被禁用。
2026-06-29 补充：前台丝滑与后台内存压缩边界
- 前台正在播放且画面可见时，可见连续运动层（歌词粒子、舞台歌词、头骨粒子、封面旋转联动）优先跟随 RAF/VSync；低配优化不能简单把这些层锁死到 60fps 或更低，否则高刷机器会出现用户明确反感的“不贴垂直同步”观感。
- CPU 优化优先从后台/最小化、音频分析 stride、不可见任务暂停、缓存淘汰、渲染像素预算和系统资源生命周期下手；只有在持续高压力且高刷/高像素负载时，才允许按显示器刷新率整除 cadence 回退。
- 切歌视觉过渡期间，非用户主动打开的 3D 歌单架必须进入短保护窗，常驻模式也不能在封面粒子过渡中闪出；这类闪现按实际 bug 处理，不按“动画风格”处理。
- 强兼版内存优化可迁移为可控能力：默认允许后台压缩 Mineradio/Electron 工作集；系统级 Mem Reduct（工作集、修改页、待机页、低优先待机页）必须有开关、阈值、间隔、手动按钮和提权边界，不能默认弹 UAC，也不能前台播放中强制释放导致卡顿。
- 最小化/隐藏/托盘后台是深度省电省内存主场；桌面歌词仍要保持设置要求的可用性，不要因主窗口后台压缩把桌面歌词的刷新、锁定或可读性破坏掉。
2026-06-29 补充：大歌单必须数据拿全、界面懒渲染
- 大歌单、播放队列、迷你队列和歌单详情页默认按 48 条为一批渲染；滚动接近底部再加载下一批，避免一次性创建上千个 DOM 节点导致前台 CPU、布局和图片解码飙升。
- 后端同步不能用小 limit 冒充优化。网易云歌单歌曲要分页拉全，QQ/网易云个人歌单也要分页同步；前端懒加载只限制显示批次，不裁掉真实数据。
- 3D 歌单详情已经是虚拟行思路，只渲染当前可见行；后续新增列表类功能优先沿用“数据全量/分页同步 + UI 懒渲染/虚拟化”的结构。
- 3D 歌单详情属于预览/浏览入口，打开时禁止等待万首歌单全量返回；必须先取 48 首进入界面，再按滚动位置用 limit/offset 补页。播放整张歌单和浏览歌单详情是两个不同负载路径，不能混用同一个全量等待。
- 禁止为了低占用把用户歌单硬截断到 500 首或固定几十首；性能优化应来自分页、缓存、虚拟化、图片 lazy/decode 和滚动批量加载。
2026-07-11 补充：列表批量取数不等于批量堆 DOM
- 旧的“每次追加 48 条”只延迟了卡顿：滚动足够久后仍会累积几千个节点。现在歌单目录、歌单详情、主队列和迷你队列必须使用真窗口虚拟化，只保留可见区加 overscan，顶部/底部用占位高度维持滚动位置。
- 数据层继续完整分页：目录和详情可以 48 条快速首屏、后台 200/500 条预取；万首歌单播放只等首批最多 96 首，随后在后台按页补齐。数据没有加载完时必须显示轻量进度和重试入口，不能假装已经结束，也不能提前循环到队首。
- 3D 歌单架采用卡片/详情行 GPU 对象池复用。优化对象创建、图片解码和签名扫描，不删除 hover 浮起、居中缓动、揭示、视差、滚轮、GSAP 和原有粒子/玻璃效果。
- 大数据量验收必须同时检查“总数据可继续增长”和“当前 DOM/GPU 对象数量保持有界”；只看接口拿全或只看首屏不卡都不算完成。
2026-07-11 补充：万首队列必须有界流动，左栏只能有一条视觉滚动轴
- “渐进装载”不能在后台以很短间隔自动跑完整个万首歌单。首批满足播放后最多暖取一页，后续由播放前瞻、用户浏览到已加载尾部或手动入口驱动；总数仍显示完整，不能伪装成 256 首上限。
- 网易云底层 playlist_track_all 每页都会重新读取整份 trackIds，不能直接用于连续万首分页。服务端应缓存有 TTL/LRU 边界的曲目 ID 索引，再对当前小页调用详情接口；一次只允许一个补页请求在途。
- 后台补页禁止重复重建 3D 歌单架、批量同步不可见歌曲红心或触发全量存档。可见队列状态可以轻量刷新，但 3D 原有效果不因这条规则被删除。
- 左侧目录仍可在实现层使用窗口虚拟化；但歌单展开详情必须与 #playlist-panel 共用一条外层滚动轴，不能让用户在左栏里再操作第二个固定高度滚动窗。行虚拟化要用透明占位维持连续长列表的视觉。
- 展开态属于导航状态：必须有高亮边框/指示条/连体背景，并在自动定位时避开顶部 sticky 区域，让用户一眼分清当前展开歌单与下面普通歌单。
---
RELEASE NOTES V1.1.0
Mineradio v1.1.0 纯净安装版
这是 Mineradio 1.1.0 的纯净安装发布版。安装包从当前可信源码重新构建，旧 dist、旧安装包、旧备份包和旧 packaged build 都没有作为本次发布来源。
重要安全说明
- v1.0.10 及更早旧安装包不再建议继续安装或传播，请先隔离旧 .exe 安装包。
- 本次不提供从 v1.0.10 到 v1.1.0 的软件内本地更新，不提供快速补丁。
- 请手动下载 Mineradio-1.1.0-Setup.exe，卸载旧版本后进行纯净安装。
- 本次 Release 不上传 latest.yml，也不作为旧版软件内更新通道的 latest。
下载
- Windows 安装包：Mineradio-1.1.0-Setup.exe
- 校验文件：Mineradio-1.1.0-SHA256SUMS.txt
主要更新
- 将 默认测试.json 设置为首次启动默认用户存档，软件内默认视觉参数也同步使用这份快照。
- 新用户首次启动时，用户存档列表会自动预置「默认测试」。
- 默认视觉参数更新为：emily 预设、封面粒子分辨率 1.55、电影镜头强度 0.5、歌词发光 0.28、高亮色 #fac900、发光色 #008aff、UI/Home/视觉图标白色。
- 默认 3D 歌单架为静态常驻侧栏，侧向角度 -15，播客歌单默认关闭。
- 3D 歌单架新增「显示播客歌单」和「合并收藏歌单」开关。
- 高级设置新增后台策略和画质档位，直播后台保持开启后不会进入低占用暂停。
- 修复用户存档应用后切歌/跳歌回退到上一个视觉预设的问题。
- 修复 3D 歌单详情页动态/静态镜头绑定混乱、常驻触发区异常、详情页遮挡和滚轮高亮不同步问题。
- 修复详情页选歌时歌词透明度跳亮；详情页打开时歌词保持可读，但不遮挡中心高亮行。
- 修复全屏 DIY 悬浮入口遮挡视觉预设热键按钮，以及视觉控制台隐藏按钮残留的问题。
- 更新 Electron / electron-builder 依赖，并保留更新下载失败时的安全停住逻辑。
安装建议
1. 不要继续运行或转发旧安装包。
2. 先卸载旧版 Mineradio。
3. 隔离旧 .exe 安装包和旧打包目录。
4. 下载并安装 Mineradio-1.1.0-Setup.exe。
5. 安装后如需对照校验，请使用 Release 中提供的 SHA256 文件。
当前安装包暂未进行代码签名，Windows 可能显示安全提示。
---
SUPPORT
Mineradio 作者支持渠道
如果 Mineradio 陪你多听了一首歌，也欢迎通过下面的二维码支持作者继续维护。
扫码前请确认收款人信息。二维码来自作者提供的支付宝与微信赞赏原图裁切。
---
THIRD PARTY PORTS
Third-party ports
Mineradio-LX-Music desktop/home reference
- Upstream: ww085213/Mineradio-LX-Music
- Initial reference revision: 82826df814c32853d99697c0ee60f749a2fcad79
- Homepage refresh revision: 812e2dc2e18bbc263e61dbd0206cb765e003d6e9
- License: GNU GPL v3 (GPL-3.0-only)
- Port dates: 2026-07-18 (initial), 2026-07-19 (homepage refresh)
Mineradio's full desktop mode adapts the upstream idea of moving the existing
Electron main-window HWND between the Windows WorkerW desktop layer and an
interactive top-level window. The native attach/detach code in this project was
rewritten around the optimized edition's fail-closed WorkerW discovery, DPI
conversion, structured acknowledgements, serialized lifecycle, and cleanup
requirements.
The home dashboard adapts the upstream information hierarchy (continue,
library, daily recommendations, recent playback, today's listening, next up,
discovery, and radio entry points). Its data adapters use this project's current
multi-provider discovery, playlist, search, playback queue, and listen-history
state. Upstream LX-only server routes and the legacy standalone wallpaper
overlay were not copied.
The 2026-07-19 refresh additionally adapts the three-song "For You" strip,
stable cover-image swaps, in-place quick-card updates, daily-review hover
feedback, and compact-height scrolling/settings behavior. These features remain
implemented against Mineradio's existing provider, weather-radio, local-library,
queue, and playback modules rather than the upstream LX/local-only data model.
The combined application remains distributed under the repository's GNU GPL v3
license. Preserve this notice and the corresponding source when redistributing
modified builds.
Qishui Passport Web QR authentication
- Upstream: Wx2yZx/Mineradio-Qishui-QR-Login
- Reference revision: aaadaab7d011714f94fbe45b382ba8dcc7cf17b9
- Declared license: GPL-3.0-only
- Port date: 2026-07-30
Mineradio ports only the official Passport Web QR authentication boundary:
an isolated hidden Electron security host, the Qishui web signing bootstrap,
QR creation and polling, account-session cookie persistence, and the official
second-verification UI when the service requests it. The upstream whole-project
installer was not run, and no application files were wholesale replaced.
The QR bridge feeds the authenticated cookie into Mineradio's existingqishui-api.js provider. Search, playlists, likes, comments, entitlement checks,
and audio playback remain Mineradio implementations. Legacy token/manual-cookie
login controls and local SodaMusic cookie discovery are not exposed by the
current login UI.
The web security runtime resources under qishui-auth-v6/ are retained
byte-for-byte for protocol compatibility and remain the property of their
respective rights holders. They are loaded only inside the isolated authentication
partition for the user's own official login session.
---
CHANGELOG
Changelog
v2.1.0
- 优化 Wallpaper Engine 壁纸与全屏模式的兼容性。
- 改进登录、账号状态和本地曲库体验。
- 提升长时间运行与连续播放稳定性。
v2.0.3
- 修复多行歌词与 3D 歌单架的显示层级。
- 优化更新入口与安装包获取流程。
v2.0.2
- 修复 QQ 会员状态识别与登录同步。
- 修复无可用音源时反复切换导致的卡顿与闪退。
- 提升连续播放、异常恢复与账号状态提示的稳定性。
v2.0.1
- 修正部分账号状态识别。
- 改进汽水音乐本地登录态检测。
- 修正首次主题色与 3D 歌单架显示层级。
- 提升播放与启动稳定性。
v2.0.0
- 全面优化视觉层次与动态表现，整体观感更统一。
- 桌面模式与全屏交互更自然，桌面使用体验更完整。
- 重整主页与搜索体验，推荐、历史和长列表浏览更顺手。
- 修复连续播放与切歌稳定性问题，并优化启动和后台性能。
v1.1.1
- P0 installer safety fix: installation now defaults to the first available non-C drive from D:\Mineradio through Z:\Mineradio; it falls back to C:\Mineradio only when no D-Z drive exists.
- The installer now forces the target path into a dedicated Mineradio folder, blocks non-empty non-Mineradio-owned targets, and blocks C drive installs when a D-Z drive is available.
- Existing registered installs in a dedicated ...\Mineradio folder are adopted in place so users can run the new setup over their current installation and receive the safe uninstaller.
- Existing dedicated ...\Mineradio folders that already contain Mineradio files can be overwritten even if they were created before the new safety marker existed.
- The new uninstaller no longer removes the whole installation root or app subfolders recursively; it deletes only known top-level Mineradio/Electron files and leaves unrelated files in place.
- Legacy uninstallers without the new safety marker are skipped during install; the setup deletes only the old Uninstall Mineradio.exe file and registry entry so it cannot indirectly trigger an older unsafe uninstall routine.
- Installer/uninstaller safety fixes require the full setup package; quick patch JSON files must not be used as the only delivery path for this issue.
v1.1.0
- 纯净安装发布版：从当前 resources/app 可信源码重新构建 1.1.0 安装包，旧打包产物、旧备份包和旧安装包不再作为发布来源。
- 重要安全说明：v1.0.10 及更早旧安装包不再建议继续安装或传播，请先隔离旧安装包；本次不提供从 v1.0.10 到 v1.1.0 的软件内本地更新，请到 GitHub Release 手动下载 v1.1.0 进行纯净安装。
- 默认视觉参数更新：将 默认测试.json 作为首次启动默认用户存档和软件内视觉参数默认值；新用户首次启动即使用同一份快照，用户存档中自动预置「默认测试」。
- 默认视觉快照包括：emily 视觉预设、封面粒子分辨率 1.55、电影镜头强度 0.5、歌词发光 0.28、高亮色 #fac900、发光色 #008aff、UI/Home/视觉图标白色、3D 歌单架静态常驻、播客歌单默认关闭、侧向角度 -15。
- 3D 歌单架新增内容开关：可关闭播客歌单，可选择是否把「我的歌单」与「收藏歌单」合并成一条连续滚动列表。
- 3D 歌单架交互修复：动态/静态详情页绑定分流，静态详情页跟随封面粒子世界轴，动态详情页跟随镜头；常驻歌单架未命中时不再长期挡歌词，命中卡片时才浮起到前景。
- 3D 歌单详情页修复：详情页打开后保持更完整的页面显示和中心高亮行；修复固定/常驻状态下详情页被歌词或卡片遮挡、动态镜头触发区异常、滚轮高亮不同步等问题。
- 歌词透明度修复：详情页选歌/切歌时新词不再突然跳亮；详情页打开时歌词保持可读，但降低发光层并保持在详情页下层，避免遮挡中心高亮行。
- 高级设置新增性能项：后台策略支持自动优化、保持运行、停止释放；画质档位支持低/中/高/超高；直播后台保持开启后不再进入低占用暂停。
- 用户存档修复：应用用户视觉存档后会提交播放态视觉预设，跳转歌曲、切歌不再回退到上一个视觉预设。
- 全屏/控制台修复：视觉预设热键按钮不再被全屏 DIY 悬浮入口遮挡；视觉控制台隐藏按钮会跟随一起隐藏，不再残留一个孤立标记。
- 更新 Electron / electron-builder 依赖，修复已知高风险构建依赖告警。
- 修复软件内更新失败后的循环体验：快速补丁失败后不再自动反复拉完整安装包，完整安装包下载完成后也不再自动打开，需用户手动确认。
- 更新下载会复用本地已校验通过的安装包，避免重复下载同一文件。
v1.0.10
- 重做桌面歌词视觉与交互：保持软件内歌词质感，优化白底可读性、长歌词滚动、锁定穿透、电影震动与最小化状态一致性。
- 修复安魂预设歌词位置无法调整的问题，当前嘴部歌词原位置作为原点，景深改为按视角前后移动。
- 歌词布局新增上下角度与左右角度调节，并会随本地布局和用户存档保存。
- 歌词镜头绑定开启时避让右侧 3D 歌单架，安魂预设也同步处理，避免遮挡歌单架操作。
- 新增方向键上下调节音量，每次 5%，输入框和滑条聚焦时不会误触。
- 调整更新包规则：补丁包命名使用 旧版本→新版本 表达，且以后只为低于新版的最近 4 个版本生成快速补丁。
v1.0.9
- 修复安装包深色界面中部分文字仍为黑色导致看不清的问题，安装器改为浅色高对比界面。
- 安装包支持用户自由选择安装目录；默认仍优先 D:\Mineradio，选择盘根目录时会自动补全 Mineradio 文件夹。
- 修复软件可重复打开的问题，重复启动时会聚焦当前已运行的窗口。
- 修复软件每次启动都会自动创建/刷新桌面快捷方式的问题。
v1.0.8
- 修复 QQ 音乐登录后头像/昵称与播放授权状态不同步的问题，歌单能读但歌曲无法播放时会优先识别真实播放票据缺失。
- Home 左侧大卡片改为施工提示，并支持在 Home 页手动展开播放器控制台。
- 视觉预设顺序调整为 emily、安魂、星河、唱片、星球、滚筒、虚空；安魂十字架选中态保持同款蓝色。
- 视觉控制台新增 4 个槽位的“用户存档”，可保存粒子、颜色、滑条和歌词外观习惯，并支持卡片内直接命名。
- 修复重启后歌词预设/自定义颜色没有立即恢复到舞台歌词的问题。
- 播放与暂停增加音频淡入淡出，降低手动启停时的突兀感。
v1.0.7
- 反正没什么人看，布想写日志了
v1.0.6
- 反正没什么人看，布想写日志了
v1.0.5
- 优化 GitHub 更新下载：默认优先尝试国内加速线路，失败后自动切换下一条线路，最后兜底 GitHub 直连。
- 更新弹窗新增下载速度、已下载大小、预计剩余时间、当前线路和线路尝试次数显示。
- 更新失败时保留具体失败原因和已尝试线路数量，方便用户判断是超时、DNS、HTTP、校验失败还是资源未同步。
- 下载完整安装包和快速补丁都会校验 release digest，避免镜像缓存异常导致坏包被应用。
- 修复旧版本快速补丁匹配过宽的问题，确保 1.0.0、1.0.1、1.0.2、1.0.3 只会匹配各自对应的补丁包。
v1.0.4
- 优化最小化/隐藏窗口时的后台占用：只有真正最小化、不可见或文档隐藏时进入深度低占用；可见但失焦、副屏显示时保持正常帧率和电影镜头。
- 修复桌面全屏模式下 3D 视觉画布尺寸不同步导致的裁切/偏上问题；全屏、退出全屏和窗口 resize 后会连续刷新主渲染视口。
- 优化播放器控制台自动隐藏时的残影：隐藏状态不再保留玻璃背景、滤镜和阴影，同时保留显示时的原有玻璃质感。
- 视觉控制台新增“控制台玻璃色差”滑条，并给视觉控制台悬浮按钮增加贴边自动隐藏按钮。
- 左侧“我的歌单”详情页改为分批加载更多歌曲，放大“加载更多”按钮，详情头部支持滚动置顶和回到顶部。
- 沉浸模式恢复左侧歌单栏、3D 歌单架和默认封面渐变背景的可用性。
v1.0.3
- 重构视觉预设控制台的信息结构，新增 预设 / 外观 / 歌词 / 动态 / 高级 五个分区，减少功能堆叠带来的操作压力。
- 优化色轮和封面取色面板的自适应定位，弹层会贴近触发按钮并限制在当前窗口内，降低不同分辨率下错位或越界的概率。
- 修复背景颜色状态混淆问题：纯黑色现在代表真正的黑色背景，封面渐变改为独立模式，控制台会明确显示“封面渐变”。
- 保留并优化根据专辑封面生成背景渐变的功能，避免点击默认时才触发、左侧色块却显示黑色的误导。
v1.0.2
- Add collect-to-playlist and play-next actions to artist detail songs.
- Publish quick patches for 1.0.1 -> 1.0.2 and 1.0.0 -> 1.0.2, plus a full installer for cross-version upgrades.
v1.0.1
- Smooth Emily visual loading and track-change transitions.
- Remove the forced loading-state jump, shorten the Emily cover color mix, and fade cover depth in gradually.
- Publish a 1.0.0 -> 1.0.1 quick patch so installed users can receive an update prompt.
v1.0.0
- 调整播放器控制台显隐规则：播放、切歌、天气电台开播不再主动弹出底部控制台；只有底部手柄/热区唤出时显示，鼠标移出热区后快速收起。
- 修复播放器控制台进度条不随播放推进的问题：进度条和时间显示现在会优先使用真实音频时长，并在浏览器暂未返回 duration 时使用歌曲 metadata 兜底。
- 修复网易云 / QQ 扫码成功但登录态不落地的问题：网易云不再因资料接口短暂无 profile 立刻清空 cookie，QQ 登录支持新式 psrf_ / wx token。
- 修复播放/暂停按钮手动恢复播放失效：手动点击路径现在会在用户点击同步栈内先调用 audio.play()，再恢复音频分析器，避免错过浏览器用户激活窗口。
- 修复播放准备阶段的栈溢出会拖死控制台的问题：歌词预置、封面加载、喜欢状态、Home 状态、listen session 和 beatmap / DJ 视觉预热均改为隔离执行，任何非音频链路异常不再阻断真实切歌。
- playQueueAt 增加播放阶段日志；若后续仍出现异常，控制台会标明 source-url、visual-prep、audio-start 等阶段，界面不再直接弹出 Maximum call stack size exceeded。
- 单曲循环的 ended 回调改为异步再入，避免浏览器在音频结束事件中同步重进 playQueueAt 引发递归风险。
- 修复天气电台 / 歌单播放链路的控制台递归风险：不再运行时重写播放、上一首、下一首按钮的 onclick，避免 Maximum call stack size exceeded。
- 切歌开始时立即刷新队列高亮和迷你队列计数；即使浏览器拦截自动播放，标题、时长、队列当前项也保持同步。
- Home 天气电台主按钮和天气卡片统一到同一启动入口，并增加启动 busy 锁，避免重复点击并发开播。
- 修复右键唤起 3D 歌单架时误唤出播放器控制台：歌单架打开期间会硬隐藏底部控制台，并阻止热区/播放态 reveal。
- 隔离 3D 歌单架刷新/关闭异常：歌单 API 成功后不再因为 shelf 重建或 3D 详情列表绘制失败而误报“歌单加载失败”。
- 天气电台、歌单、播客、每日推荐和 3D 详情播放入口统一使用安全队列刷新；队列写入后播放器控制台会恢复可点击，不再被 UI 渲染异常拖死。
- 恢复歌单 / 天气电台自动开播为非 manual 路径，并将 playQueueAt 前置 UI 阶段纳入兜底，避免队列标题已变但实际音频和上下一首按钮停在旧状态。
- 天气电台音乐来源收窄为网易云搜索，并取消入队前批量播放 URL 探测，避免点击入口时请求堆积造成卡死。
- 天气电台前端复用正在进行的天气加载请求，避免 Home 后台预加载和手动启动同时打到后端。
- 自动播放被系统拦截时，播放器控制台保持可点击并提示手动继续；真正加载失败的队列项会自动跳到下一首。
- 手动下一首 / 上一首现在一定切换实际音频；单曲循环只在自然播完时重复当前曲。
- 切歌开始时立即暂停旧音频，避免出现歌词和 UI 已切走但旧歌还在播的错位。
- 修复天气电台城市经纬度缺失时落到 (0,0) 的问题，并在 Open-Meteo 超时/失败时返回临时电台队列。
- 歌单曲目加载增加 playlist_track_all -> playlist_detail 降级，减少歌单加载失败。
- 播放队列写入后强制恢复底部控制台可交互状态，避免天气电台或歌单开播后控制台残留不可点击。
- 启动页退出后补 Home 恢复安全网，避免首页隐藏在空场背景后。
- 发布 Mineradio 首个正式版本，GitHub 主页和安装包版本统一为 1.0.0。
- 首页正式版包含天气电台、每日推荐、私人电台、继续听、听歌画像和我的歌单入口。
- 天气电台接入 Open-Meteo，并优先混入每日推荐和私人推荐曲库，过滤 AI / 白噪音 / 雨声助眠等低质结果。
- 修复窗口模式下主页 6 张主卡片在紧凑尺寸中过早堆叠、挤出首屏的问题。
- 保持启动后 Wallpaper 银河背景干净显示，播放后切换到 Emily / 默认播放态视觉。
v0.9.13
- 开场动画升级为 WebGL 光流线场，融合 ShipSwiftAnimatedLoop 的 RGB 分通道、Warp 流动和高亮线场质感。
- 移除刻意的环形/花瓣式爆点，改为更自然的斜向流线相位变化，让启动过程更帅气但不突兀。
- 开场动画播放完成后不再自动进入主页，会停留在“点击进入”状态；点击任意位置或按 Enter/空格后进入 Home。
- 保留 2D canvas fallback，WebGL 不可用时仍能显示启动页。
- 生成 0.9.12 -> 0.9.13 快速补丁，用于已安装用户轻量更新。
v0.9.9
- 统一当前版本号为 0.9.9
- 接入 GitHub Releases 更新检测配置
- 增加更新弹窗与更新下载任务接口
- 增加 QQ 音乐与网易云音乐双平台体验方向
- 优化电影镜头节奏分析与 DJ 视觉模式
- 增加自定义封面、自定义歌词、歌词布局和视觉控制相关能力
说明
这是首次公开发布前的整理版本。更早版本属于本地迭代记录，暂不展开。
---
README
Mineradio
Mineradio 是一款 Windows 桌面沉浸式音乐播放器，把搜索播放、歌词舞台、粒子视觉、3D 歌单架和完整桌面模式组合成一个更接近现场感的私人音乐空间。
立即下载 Windows 安装包
安装包可从夸克盘、百度云、蓝奏云或 GitHub Release 手动下载；软件内更新入口仍只打开网盘线路，不读取 Release 附件。
| 下载入口 | 推荐人群 | 链接 |
| --- | --- | --- |
| 夸克盘 | 夸克用户 | 下载 Mineradio 2.1.0 |
| 百度云 | 百度网盘用户（提取码 SJHP） | 下载 Mineradio 2.1.0 |
| 蓝奏云 | 直接下载 | 下载 Mineradio 2.1.0 |
| GitHub Release | GitHub 用户、版本说明与源码 | 下载 Mineradio 2.1.0 |
安装时只需要下载并运行 Mineradio-2.1.0-Setup.exe。不要把 .blockmap、latest.yml 或 win-unpacked 当成正式安装包。
下载或安装被拦截怎么办
小众 Electron 桌面软件、未签名安装包有时会被浏览器、Windows Defender 或 SmartScreen 提示风险。请先确认安装包来自上面的网盘入口或官方 GitHub Release，文件名是 Mineradio-2.1.0-Setup.exe。
1. 浏览器下载栏提示风险时，打开下载列表，点这条下载右侧的 ... 三个点，选择 保留 / 仍要保留 / 显示更多 后继续保留。
2. Windows SmartScreen 弹出蓝色拦截窗口时，点 更多信息，再点 仍要运行。
3. 如果杀毒软件明确显示木马、高危或已经隔离，不要强行运行；删除该文件后重新从上面的网盘入口下载，仍然异常请带截图反馈给作者。
作者支持
如果 Mineradio 陪你多听了一首歌，也欢迎请作者一杯咖啡。
Mineradio 2.1 进一步优化了壁纸与全屏体验，并提升了登录、账号、本地曲库和长时间运行的稳定性。
当前版本
当前版本：2.1.0
状态：Mineradio 2.1.0 正式版。
安全提示：v1.0.10及更早旧安装包不再建议继续安装或传播。请使用本页提供的Mineradio-2.1.0-Setup.exe。
核心特性
- 首页包含每日推荐、平台推荐、继续听、听歌画像和我的歌单入口
- 完整桌面模式保留播放器、主页、歌单和桌面交互
- 支持本地 MP4 与 Wallpaper Engine 视觉内容
- 播放后切换到 Emily / 默认播放态视觉，歌词舞台与粒子舞台同步工作
- 基于节奏的电影镜头视觉系统
- 面向长播客和 DJ 曲目的专属视觉模式
- 歌词舞台、自定义歌词、歌词位置与视觉控制
- 自定义专辑封面上传与裁剪
- 右键唤起 3D 歌单架，支持歌单队列浏览
- 网易云音乐账号、搜索、歌单、播客等体验接入
- QQ 音乐搜索、登录态与音源补充接入
- GitHub Releases 更新检测与下载入口
- 首次启动内置「默认测试」视觉用户存档，软件内默认视觉参数与该存档一致
使用说明
Windows 用户可以从本页列出的夸克盘、百度云、蓝奏云或 GitHub Release 下载安装包。
正式分发以 Mineradio-2.1.0-Setup.exe 为准，不建议直接使用 win-unpacked 目录。安装包会创建桌面快捷方式。
已经安装过旧版本的用户可直接运行 Mineradio-2.1.0-Setup.exe 完成更新。软件内更新入口只会打开浏览器下载页，不会在客户端内下载或应用补丁。
开发运行
npm install
npm start
npm run build:win桌面版入口由 Electron 主进程加载本地服务。npm run build:win 会生成 Windows NSIS 安装包，产物位于 dist/。
更新机制
Mineradio 会请求 GitHub Releases latest 检测新版本。远端版本高于本地版本时，应用内更新入口会展示 Release 内容，并通过系统浏览器打开可选网盘线路；即使 Release 附带完整安装包，2.0.3+ 客户端也不会读取、下载、缓存或应用该附件与补丁。
本地验证更新链路时，可以通过 MINERADIO_UPDATE_MANIFEST 指向一个本地 manifest JSON 或 HTTP 地址来模拟线上 Release。
第三方音乐平台说明
Mineradio 不是网易云音乐、QQ 音乐或腾讯音乐娱乐集团的官方客户端，也不隶属于任何音乐平台。
项目中的第三方平台接入仅用于个人学习、本地客户端体验和用户自有账号的播放辅助。请遵守对应平台的用户协议、版权规则和会员权益规则。项目不会提供绕过付费、绕过会员、破解音质或重新分发音乐内容的能力。
用户数据与隐私
登录 Cookie、搜索历史、自定义封面、自定义歌词、节奏分析缓存等数据只应保存在本机用户数据目录或浏览器本地存储中，不应提交到仓库。
更多说明见 PRIVACY.md。
致谢
Mineradio 由 XxHuberrr 主要设计与打造。emily 作为早期视觉底层想法与 emily 视觉预设改进方向的共创者和灵感来源之一，特此感谢。
同时感谢小天才e宝、应春日、锋将军、軌跡、林中、骊、风痕、花椰菜🥦在早期体验、测试反馈和发布准备中的帮助。
版权与授权
Copyright (C) 2026 XxHuberrr.
本项目采用 GPL-3.0 授权。详见 LICENSE。
MR Logo、Mineradio 名称、界面视觉设计与原创视觉表达归作者所有；第三方依赖和第三方服务分别遵循其各自授权与服务条款。
---
SECURITY
Security Policy
Supported Versions
当前只维护最新公开版本。
Installer Safety Notice
v1.0.10 及更早旧安装包不再建议继续安装或传播。请将旧 .exe 安装包视为不可信历史产物并隔离保留；需要安装 Mineradio 时，请使用 v1.1.0 或更新版本的 GitHub Release 安装包。
v1.1.0 不作为 v1.0.10 的软件内本地更新包发布。旧版本用户请手动下载新版安装包，卸载旧版本后进行纯净安装。
Reporting a Vulnerability
如果你发现安全问题，请通过 GitHub Issues 或仓库作者主页联系作者。
请不要在公开 Issue 中直接贴出 Cookie、Token、账号信息、私密链接或可复现的敏感数据。
Sensitive Data
Mineradio 不应收集或上传用户 Cookie。用户登录状态应保存在本地用户数据目录中。
如果你要提交问题反馈，请先确认没有附带：
- .cookie
- .qq-cookie
- 本地音乐文件
- 用户账号截图
- 调试日志中的 Cookie、Token 或隐私路径
---