{{ i18n.pages.start.title }}
{{ i18n.pages.start.subtitle }}
{{ i18n.pages.start.privacyHint }}
{{ i18n.pages.start.subtitle }}
{{ i18n.pages.start.privacyHint }}
{{ i18n.pages.lrcConverter.description }}
{{ lrcxResult }}{{ feedback }}
{{ i18n.pages.playlistPage.description }} {{ desc }}
{{ i18n.pages.fileMaintenance.kicker }}
{{record.summaryText}}
{{emptyText}}
{{record.summaryText}}
{{ i18n.pages.fileMaintenance.noCandidates }}
使用指南
MiuPlayer Box 选择网页路线,不做二进制分发,尽量跟随浏览器新特性来实现本地音乐播放、歌词展示和数据管理。下面是关键能力、限制和常见配置说明。
浏览器对文件访问、缓存、PWA、媒体控制和画中画的支持已经足够承担一部分桌面音乐播放器场景。相比传统桌面软件,网页播放器更轻、更容易更新,也更容易控制权限边界。
文件和目录访问由浏览器授权,风险操作需要用户明确确认。
无需安装完整桌面程序,可离线使用,也方便保留或回退版本。
面向万级曲库做渲染优化,避免为播放器额外启动一个完整浏览器壳。
尊重磁盘结构,不做多余缓存;歌单数据可导入、导出和备份。
网页平台仍有边界。例如系统级快捷键、直接打开文件资源管理器等能力会受到浏览器限制。MiuPlayer Box 会尽量提供替代方案。
| 限制 | 补救 | 权衡 |
|---|---|---|
| 无法注册系统级快捷键 | 播放器内快捷键与系统媒体控制 | 不会抢占其他应用快捷键。 |
| 网页不能直接打开文件资源管理器 | 安装 pwa-enhancer.exe 后使用自定义协议 | 该能力需要用户主动安装并授权。 |
| 没有桌面歌词 | 歌词小窗播放器可以部分替代 | 浏览器目前不会支持透明顶层窗口这种危险API这个网页做不了≧ ﹏ ≦ |
pwa-enhancer想确认浏览器能力是否完整?
请打开 兼容性检测 页面查看结果。
支持 .lrc 和 .lrcx 歌词文件,并会在需要时回退到内嵌歌词。
MiuPlayer Box 提供两类 Picture-in-Picture 播放器:迷你控制器和歌词播放器。
该功能允许网页应用通过自定义协议打开系统文件资源管理器。
pwa-enhancer.exepwa-enhancer.exepwa-enhancer,并放在固定目录。pwa-enhancer.exe --install。pwa-enhancer.exe 会注册 explorerlink: 协议,使网页应用可以发起受控的资源管理器打开请求。卸载可运行 pwa-enhancer.exe --uninstall。你可以把 MiuPlayer Box 安装为独立窗口运行的 PWA。
Chromium 内核浏览器,版本高于 110。
Guide
MiuPlayer Box takes the web app route instead of binary distribution. It follows modern browser features to provide local playback, lyric display, and data management. This page covers key features, limits, and common setup steps.
Browser support for file access, caches, PWA installation, media controls, and picture-in-picture is now strong enough for part of the desktop music player workflow. Compared with traditional desktop software, a web player stays lighter, easier to update, and clearer about permission boundaries.
File and folder access is controlled by the browser, and risky actions require explicit user confirmation.
No heavy desktop installation. Offline use and version staying are easier to manage.
The UI is optimized for large libraries and avoids launching another full browser shell just for playback.
The app respects your folder structure, avoids unnecessary caches, and supports playlist import, export, and backup.
The web platform still has boundaries. System-wide shortcuts and directly revealing files in Explorer are limited by the browser, so MiuPlayer Box provides practical workarounds where possible.
| Limit | Workaround | Note |
|---|---|---|
| No system-wide shortcut registration | Use in-player shortcuts and system media controls | The app will not hijack shortcuts from other apps. |
| A web page cannot directly open File Explorer | Install pwa-enhancer.exe and use the custom protocol | This requires explicit installation and user-level authorization. |
| No desktop lyric overlay | The lyric popup player can partially replace it | Browsers are not going to support risky APIs like transparent always-on-top windows, so this web app cannot do that. |
pwa-enhancer installed if you need reveal-in-file-explorer supportWant to verify browser support?
Open the Compatibility Check page and review the result.
Supports .lrc and .lrcx lyric files, with fallback to embedded lyrics when needed.
MiuPlayer Box provides two Picture-in-Picture players: a compact controller and a lyric player.
This feature lets the web app open a system file explorer through a custom protocol.
pwa-enhancer.exe installedpwa-enhancer.exepwa-enhancer below or from GitHub, then place it in a fixed folder.pwa-enhancer.exe --install in a terminal.pwa-enhancer.exe registers the explorerlink: protocol, allowing controlled Explorer launches from the web app. Uninstall it any time with pwa-enhancer.exe --uninstall.You can install MiuPlayer Box as a standalone PWA window.
Chromium-based browser, version above 110.
{{ i18n.pages.compatibility.eyebrow }}
{{ i18n.pages.compatibility.intro }}
{{group.description}}
{{item.description}}
{{item.detail}}关于项目
一个主打轻量、灵活和本地优先的网页音乐播放器。它尽量把浏览器的新能力用到音乐管理、歌词播放和歌单整理上,同时保留网页应用的低负担体验。 Web Platform New API 实验性项目, light but not slight!
当前应用界面和主要能力仍在持续完善。MiuPlayer Box 已经可以承担日常本地音乐播放,但歌单、设置、历史记录和高级歌词体验还有待持续演进。
通常每周我都会花大量时间听歌。在项目启动之初,我对当时的桌面音乐播放器感到沮丧,因为它们要么操作笨拙、设计过时,要么功能不符合个人习惯。 我对本地音乐做了大致文件夹分类,希望至少有直观的类文件浏览器式的音乐导航并且支持播放列表。 同时,我需要歌词渲染。
当时(2024年末)桌面端也有现成方案,但要么界面复古,要么基于Electron,安装包重、占用偏高、灵活度一般。歌词显示模式没有我设想的,并且在播放细节控制上我不大满意。 比较挑剔,那就自己造!? 基于一些Web平台新的实验性API,MiuPlayer Box从自用需求起步,再一次次尝试中逼近网页App的边界,并逐步把设想变为现实。
2MB。MiuPlayer Box是一款按个人喜好随心所欲的音乐播放器,也是拒绝循规蹈矩的 Web Experiment Project。
作者只想做极致,目标是最强网页本地音乐播放器;(据说代码非常优雅ヾ(≧▽≦*)o)
同时也是 LRCX 高级歌词播放器示例项目。(作者也绝对不会告诉你大费周章设计歌词格式写播放器只是为了方便学喜欢的歌的!! ̄へ ̄)
About
A lightweight, flexible, local-first web music player. It brings modern browser capabilities into music browsing, lyric playback, and playlist management while keeping the app easy to open and update. It is also an experimental project exploring new Web Platform APIs: light, but not slight!
The interface and major features are still evolving. MiuPlayer Box is already useful for daily local playback, while playlist editing, settings, listening history, and advanced lyric tools will keep improving.
I usually spend a lot of time listening to music each week. When this project started, I was frustrated with the desktop music players available at the time: they were awkward to use, visually dated, or simply did not fit my habits. I had already organized my local music roughly by folders, so I wanted at least an intuitive file-browser-style way to navigate music, with proper playlist support. I also needed lyric rendering.
In late 2024, desktop options were available, but some had dated interfaces while others were built on Electron, with larger installers, higher resource use, and average flexibility. Their lyric display modes did not match what I had in mind, and I was not satisfied with the playback controls. I was picky, so why not build my own!? Using experimental Web Platform APIs, MiuPlayer Box started as a tool for my own needs. Through repeated experiments, it has gradually pushed the boundaries of what a web app can do and turned those ideas into reality.
2MB even before compression.MiuPlayer Box is a music player built around personal taste and freedom, and a Web Experiment Project that refuses to follow convention.
The author just wants to push things to the limit, aiming to build the best local music player on the web; (or so they say—the code is supposedly very elegantヾ(≧▽≦*)o)
It is also an example project for advanced LRCX lyric playback. (The author would never tell you that all the work on designing a lyric format and building a player was just to make it easier to learn favorite songs!! ̄へ ̄)
使用帮助
MiuPlayer Box 把本地文件、浏览器权限与 PWA 能力组合在一起,因此部分行为与传统桌面播放器不同。 这里按实际任务解释最常遇到的问题。
从选择音乐到长期保存曲库,遵循浏览器为本地文件设置的边界。
选择文件适合快速加入一首或少量音乐;选择文件夹会建立一个曲库入口并扫描其中的音频。是否继续扫描子文件夹由导入区的“包含子文件夹”选项决定。不同浏览器提供的文件夹能力不同,支持 File System Access API的浏览器以文件夹打开方可解锁完整体验。功能受限时仍可退回临时播放。
文件访问权限由浏览器保存和恢复,而不是由播放器绕过系统长期持有。重启浏览器、使用隐私模式、清理站点数据、浏览器策略变化,或移动和重命名文件夹,都可能让原授权失效。重新选择同一目录只是恢复访问关系,不会复制或上传目录内容。
不会因为“选择文件”或“选择文件夹”而自动上传。本地音频由浏览器直接读取并播放。在线媒体、在线歌词或其他网络来源可能各自发起网络请求,但这与本地导入是不同的数据路径。
扩展名只说明文件声称的格式,真正能否播放还取决于音频编码、文件是否损坏,以及当前浏览器和系统提供的解码器。同一种容器也可能装入不同编码。可以先查看兼容性检测的格式声明,再用其他已知正常的音频交叉验证。
歌单、设置、文件句柄与离线资源都可能保存在浏览器的站点存储中。清理站点数据、重装浏览器配置或使用临时会话,可能一并删除这些资料。重要歌单与配置应定期从设置页的本地数据区域导出备份;备份不包含音乐文件。
歌单、设置备份导入受支持版本后数据生效。本地音乐文件句柄无法被导出,导入备份到新应用程序需要重新授权与备份目录名称一致的音乐文件夹,期间不宜修改文件夹内音乐名称和路径,歌单根据音乐相对路径确定以有效迁移,歌单中本地灰色音乐文件灰色可请检查对应根目录是否正确添加。
系统设备与离线能力会同时受到浏览器、操作系统和当前安全上下文影响。
支持输出设备专用选择 API 的浏览器会在点击刷新按钮时直接请求输出设备授权,不申请麦克风。其他浏览器会先尝试无权限枚举;只有输出设备名称仍被隐藏时,才会一次性请求临时麦克风权限来解锁设备列表。MiuPlayer Box 取得结果后会立即停止临时音频轨道,不使用麦克风。若浏览器拒绝输出设备授权,设备切换仍可能受限。
不一定。安装只表示应用可以像独立窗口一样启动;离线可用依赖 Service Worker 是否控制当前页面、所需资源是否已经缓存,以及缓存是否被系统回收。首次使用或版本切换后,可关闭应用重新后再次打开确认离线资源状态。
播放相关工具将保持连续工作,同时允许用户随时覆盖自动行为。(AI大人你写了啥,这是在说什么???🥴)
歌词来源可能依赖文件内嵌信息、同名歌词或在线匹配;不完整的标题、艺人和时长会降低匹配准确度。先检查音乐元数据和歌词来源,再手动替换或校正歌词。逐词时间轴本身有误时,需要在歌词工具中重新调整。噢!内置歌词忘记做兜底显示了,下次记得再加吧。。。
页面转换器只做基本格式转换处理,适用于快速转换。需要手动保存同名`.lrcx`。
好消息!!🎉在线转换服务现已可用:LRC to LRCX服务。支持自动批量转换、增加日语注音上标,可自动写入歌词文件。
播放列表突然就不见了?如果不喜欢可以在 设置-播放控制 中关闭播放队列“自动展开/收缩”设置项。不过播放队列按钮处于视觉出让仍会自动消失,该设计会后续会考虑优化。 记忆按钮位置很奇怪,你是对的,但播放队列面板自动收缩是本播放一项特色细节,鼠标靠近右侧响应区域自动浮出,随鼠标停留、隐藏,也许你可以试试;
检测通过也不保证可用😇
“可用”:当前环境暴露了预期能力或已确认相应状态;“受限”:存在回退方案、尚未获得持久状态,或只能确认 API 入口;“不可用”:当前检测没有发现所需入口。检测不会主动申请权限,也不能保证每个文件、设备和系统策略都成功,请结合实际操作判断。
Help
MiuPlayer Box combines local files, browser permissions, and PWA capabilities, so some behavior differs from a traditional desktop player. These answers are organized around the tasks people most often need to complete.
From choosing music to keeping a library, it helps to understand the boundaries browsers place around local files.
Choosing files is useful for quickly adding one track or a small selection. Choosing a folder creates a library entry and scans it for audio. The “include subfolders” option decides whether that scan continues into nested folders. Folder support varies by browser; browsers with the File System Access API provide the full folder-based experience, while limited environments can fall back to temporary playback.
The browser stores and restores file permissions; the player cannot bypass the system and keep permanent access by itself. Restarting the browser, using a private session, clearing site data, changing browser policy, or moving or renaming the folder can invalidate a previous grant. Selecting the same folder again only restores that relationship—it does not copy or upload its contents.
No upload happens automatically when you choose files or a folder. The browser reads and plays local audio directly. Online media, online lyrics, or other network providers may make their own requests, but those use a different data path from local import.
A filename extension only says what the file claims to contain. Playback also depends on the audio codec, file integrity, and the decoders supplied by the browser and operating system. The same container can hold different codecs. Check the format declarations on the compatibility page, then compare with another file that is known to work.
Playlists, settings, file handles, and offline resources may all live in browser site storage. Clearing that storage, rebuilding a browser profile, or using a temporary session can remove them together. Export important playlists and configuration regularly from the Local Data area in Settings. A backup does not include the original music files.
After importing a playlist and settings backup into a supported version, the data becomes available. Local music file handles are not included in exports. When restoring in a new installation, grant access again to the music folder whose name matches the one in the backup. Avoid renaming or moving files inside that folder during migration: playlists locate local tracks by their relative paths. If a local track appears grayed out in a playlist, check that its root folder has been added correctly.
System devices and offline behavior depend on the browser, operating system, and current security context.
Browsers that provide a dedicated output-device picker use it when you click the refresh button, so microphone permission is not needed. Other browsers are queried without permission first; microphone access is only requested as a legacy fallback when output-device names remain hidden. MiuPlayer Box immediately stops the temporary audio tracks afterward and does not record. If output permission is denied, device names or switching may remain limited.
No. Installation means the app can launch in its own window. Offline use also depends on whether a Service Worker controls the page, whether required resources have already been cached, and whether the system has reclaimed that cache. After first use or a version change, close and reopen the app to confirm its offline-resource state.
Playback tools can automate some behavior, but you can override it at any time.
Lyrics may come from embedded metadata, a matching local lyric, or an online match. Incomplete title, artist, and duration data reduces matching accuracy. Check the track metadata and lyric source first, then replace or correct the lyric manually. If word-level timing is wrong, adjust it with the lyric tools. The built-in lyric fallback is not in place yet, but is planned for a future update.
The page converter handles basic format conversion for quick use. Save the result manually as a .lrcx file with the same name.
Good news! 🎉 The online converter is now available: LRC to LRCX Service. It supports automatic batch conversion, adding Japanese ruby annotations, and writing the converted lyric file automatically.
Did the playback queue suddenly disappear? If you prefer, go to Settings → Playback controls and turn off “Automatically expand and collapse the playback queue.” The queue button can still auto-hide even when this setting is off; this behavior may be improved later. The button's placement is admittedly odd, but automatic queue collapse is one of this player's signature details: move the pointer near the activation area on the right to reveal the panel; it hides again as the pointer moves away. Give it a try.
Passing the check does not guarantee that everything will work 😇
“Available” means the expected capability is exposed or its relevant state was confirmed. “Limited” means a fallback exists, persistence has not been granted, or only the API entry point can be confirmed. “Unavailable” means the current check did not find the required entry point. The check never requests permission and cannot guarantee that every file, device, or system policy will work; confirm the result with the actual task.
{{search.status}}
{{search.error}}
{{search.truncated}}
{{pItem.desc}}
{{search.status}}
{{search.error}}
{{emptyText}}
{{item.reason}}
{{item.value}}{{themeCoverColor}} {{themeCoverStatus}} {{themeColor}} {{themeSolidCustomColor}}{{ i18n.pages.settings.exportPlaylistDesc }}
{{ i18n.pages.settings.clearOfflineCacheDesc }}
{{ i18n.pages.settings.deleteDatabaseDesc }}