使用指南
Mio Music 把「在线内容从哪里来」交给插件，把「怎么播、怎么看、怎么存」留给应用。本页按使用顺序介绍这两部分。
在线来源与插件
搜索、歌单、专辑、发现与歌手数据必须安装并启用外部的 音乐列表插件。应用不再提供内置的列表 SDK，也不会在能力缺失时自动回退到别的来源：
- 来源菜单只显示两类来源：已启用的列表插件自己提供播放的来源，或与当前已启用的音源插件共同支持的来源。
- 停用或卸载插件后，对应来源立即消失，进行中的旧搜索结果会被取消。
- 歌词、TTML、评论与缺失封面的补查，也按插件声明的
lyrics/comments/cover能力调用；应用只保留解码与显示，不会自行请求来源的 HTTP 接口。
插件的两种类型
| 类型 | 作用 | 入口 |
|---|---|---|
| 音乐列表插件 | 搜索、歌单、专辑、发现、歌手、歌词，并可自己提供播放与下载地址。可同时启用多个。 | 设置 → 插件 → 音乐列表插件 |
| 音源插件 | 为歌曲解析播放地址（兼容澜音脚本，洛雪脚本会自动转换）。需要显式切换使用哪一个。 | 设置 → 插件 |
安装列表插件
- 打开插件页
进入 设置 → 插件，找到「音乐列表插件」。
- 内置插件
Subsonic、Navidrome、Jellyfin、Emby、Plex、Songloft 随应用内置，启动时自动安装与更新，卡片上标有「内置」；它们不能卸载，不用时可以停用。其他插件点右上角的「安装列表插件」，从本地文件或 URL 安装。
- 配置
点插件卡片上的「配置」，按表单填入服务器地址、用户名与密码，保存后生效。
- 测试连接
声明了连接验证的插件，配置页会有「测试连接」。它使用当前表单里的值、每次实际请求一次服务器，保存之后才真正应用这些值。
更新一个已安装的插件，只需重新安装同名脚本，配置会保留。内置的插件有：
| 插件 | 来源 ID | 能力 |
|---|---|---|
| Songloft | songloft | 搜索、专辑 / 歌手 / 流派与歌单、歌词、播放与下载 |
| Subsonic | subsonic | 搜索、专辑与歌单、发现、播放与下载 |
| Navidrome | navidrome | 搜索、专辑与歌单、发现、歌手、歌词、播放与下载 |
| Jellyfin | jellyfin | 搜索、专辑与歌单、发现、歌手、歌词、播放与下载 |
| Emby | emby | 搜索、专辑与歌单、发现、歌手、播放与下载 |
| Plex | plex | 搜索、专辑与歌单、发现、歌手、播放与下载 |
第三方插件（社区推荐）
来源仓库：niamadoutraore89/mio-music-plugins（AGPL-3.0-only）。它与内置插件仓库 mio-music-plugins 名称相近，但是两个互相独立的仓库。
安装方式：设置 → 插件 → 音乐列表插件 → 安装列表插件，粘贴下表中的 URL 并确认。URL 始终指向该仓库 main 分支的最新版本；需要离线安装时，可下载文件后选择本地文件。这些插件只提供列表与搜索，不返回播放或下载地址，它们列出的歌曲需要由支持同一来源的音源插件解析。
听歌识曲同样由插件提供：应用自身不带识曲服务，只有已启用的插件声明了 recognize 能力（上表的列表插件 6）时，才会显示识曲入口，否则隐藏。
| 插件 | ID | 能力 | 安装 URL |
|---|---|---|---|
| 列表插件 1 | bd | 歌单详情与封面（搜索目前返回空页） | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/bd.list.js |
| 列表插件 2 | kg | 搜索、歌单、专辑、发现、榜单、歌手、歌词、评论、封面 | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/kg.list.js |
| 列表插件 3 | kw | 搜索、歌单、发现、榜单、歌手、歌词、评论、封面 | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/kw.list.js |
| 列表插件 4 | mg | 搜索、歌单、发现、榜单、歌手、歌词、评论、封面 | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/mg.list.js |
| 列表插件 5 | tx | 搜索、歌单、专辑、发现、榜单、歌手、歌词、评论、封面 | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/tx.list.js |
| 列表插件 6 | wy | 搜索、歌单、专辑、发现、榜单、歌手、歌词、评论、封面、听歌识曲 | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/wy.list.js |
这些服务是各自独立的产品，拥有各自的条款与商标。你需要自行确保有权访问、播放和下载相关内容，并遵守所在地区的法律和各服务的条款。关于这些插件的问题请到其仓库反馈，不要提交到本项目。
由插件提供播放与下载
列表插件可以自己解析播放与下载地址。启用后，该来源的歌曲不再走音源插件，所以没有安装任何音源插件时也能搜索与播放。关闭后，该来源的歌曲会继续交给当前的音源插件解析。插件卡片上有「由本插件提供播放」与「由本插件提供下载」两个开关，分别控制播放与下载。
接入 Subsonic / Navidrome
- 找到插件
Subsonic 与 Navidrome 插件已内置，在「音乐列表插件」中找到对应卡片。
- 填写服务器
服务器地址、用户名、密码。密码只以令牌（随机盐 + MD5）的形式发送，不会明文出现在请求里。
- HTTP 服务器
非回环地址的
http://服务器需要勾选「允许 HTTP（不加密）」；localhost等回环地址无需勾选。 - 导入歌单
Subsonic 插件 1.1.0 起提供「导入歌单」：读取服务器歌单与完整的歌曲分页，再用一个事务创建本地歌单，并显示实际保存的数量。读取失败或超限时不会留下半个歌单；重复歌曲按本地约束保留首次出现。
tools/golden/subsonic_fixture.py 是只监听回环地址、数据全部合成的 Subsonic 夹具（用户名 fixture，密码 fixture-password），可在插件配置里直接联调，不需要真实服务器。
旧版 Mio 服务脚本
旧的 Mio 服务 CommonJS 脚本也可从「安装列表插件」安装，支持 pluginInfo / 注释元数据、configSchema、testConnection(config) 或 ping(config)、getPlaylists()、getPlaylistSongs(id)，以及可选的 musicUrl(source, song, quality)，同步、Promise 与 Node 风格回调都可以。兼容层经过全目标编译和独立源码复核，但目前还没有真实旧脚本的实测，不保证任意浏览器 / Node API、闭包状态或额外的服务方法都兼容。
播放与音效
- 在线与本地播放：提前准备队列中的下一曲，关闭无缝播放时也会预缓存。开启无缝播放（Gapless）或交叉淡入淡出（Crossfade）后，下一曲缓冲就绪即可在同一音频输出中交接；在线音频无需整首下载完成才开始预解码，切歌会复用已预取的文件。音频本身的静音不会被自动裁剪。
- 均衡器：10 段参数均衡器，另有环绕声等音效，在设置中调节。
- 频谱：播放器内有实时音频频谱，本地与在线音频都支持。
- 系统集成：媒体键、托盘与快捷键。
歌词
在线歌词支持逐字与 TTML，歌词页采用 Apple Music 风格（AMLL）的连续遮罩、弹簧、缩放 / 长音、模糊 / 沉浸色，以及音译、伴唱 / 对唱。macOS 上还有桌面歌词。本地歌曲可使用本地歌词文件。
歌词内容由插件的 lyrics 能力提供；插件的开发者可以返回普通 LRC，也可以直接返回带逐字时间的 TTML，见 列表插件参考。
本地音乐与歌单
- 扫描本地目录，读取标签与封面。
- 收藏、本地歌单、批量操作；播放队列管理。
- 在线歌单内搜索，以及歌手、专辑、发现等页面（数据来自插件）。
- 标签编辑与写入。
下载
下载管理支持暂停与断点续传、重试、速度显示、运行时调整并发，并在下载完成后写入标签。当某个来源由列表插件提供下载时，下载地址取自插件的 downloadUrl，插件没有实现它则使用 musicUrl。
备份、导入与更新
- S3 备份与恢复：备份到 S3 兼容存储，数据加密并受密码保护，密钥由你自己保管。
- 旧版导入：支持部分旧版数据的导入。
- 更新：带签名的自动更新器，在设置中检查。
- DLNA：设备发现与投屏。
遇到问题
- 来源菜单里没有我的来源：确认插件已启用，并且该来源要么由插件提供播放，要么也被当前音源插件支持。
- 想知道插件为什么失败：打开插件卡片上的「插件日志」。插件通过
console.log输出的内容，以及宿主记录的失败原因（被拒绝的地址、超限、返回值格式错误等）都在这里。 - 想了解还缺什么：项目仍在开发，部分功能与平台尚未完成验收，详见仓库 README；遇到缺失或异常请提交 Issue。