模组系统(Folium 1.3)
Folium 是 Folia 桌面版的模组平台。模组可以添加歌词动画和背景、扩展播放页与进度条、注册命令和设置,也可以通过 Node 入口使用 ffmpeg 等本地能力。网页版和 PWA 不支持模组。
想制作模组,请从完整开发与贡献指南开始;接口细节见 Folium 规范和 API 参考。
启用前请确认来源
模组以可信代码运行,并非沙箱。client 入口可以访问主界面,main 入口拥有完整 Node.js 权限。清单里的权限声明不是安全边界。模组系统默认关闭,每个模组也默认禁用;启用时会出现原生确认窗口。请只启用你信任来源的模组。
开发与上架边界
Folium 1.3 是首个稳定版本,目前仅开放 UI 相关的稳定扩展接口。其他部分,尤其是 Omni provider 接口,仍属实验接口,尚不具备应用内置 Omni provider 的对等能力。在 Folium v2 发布前,请绝对不要尝试制作超出当前实验接口能力的完整音源模组;接口缺口必然导致问题,浪费开发者和维护者的时间。
任何尝试导出 provider 的原始音频流或解密之后的原始音频文件的模组,都有极高的平台法律风险。无论采用何种实现方式,此类模组都不会上架官方模组市场。
开启和安装
- 在「设置 → 实验室 → 模组系统」开启总开关。
- 在命令面板执行「模组」,打开管理面板。
- 从官方模组市场下载模组 zip,拖入面板安装;也可以点击「打开模组目录」,手动放入模组。
- 在面板中启用模组,并阅读原生确认窗口里的入口、权限、实验接口、签名与文件位置后确认。
关闭总开关会停用已启用的模组,停止加载模组代码。安装 zip 时会检查清单与入口文件,拒绝不安全路径。压缩包和解压后内容各不能超过 64 MB,单文件不能超过 32 MB,条目不能超过 2000;安装失败时保留旧版本。同 id 的 zip 可以覆盖安装,但内容变化后需要重新确认。
签名与文件变动
模组市场收录官方模组和通过审查的社区模组,均带 Folium 签名。签名用于识别审查过的文件内容,启用时仍需确认。
| 面板状态 | 含义 |
|---|---|
| 官方认证 | 签名有效,文件未在签名后改变 |
| 未验证 | 没有官方签名;仍可安装和启用 |
| 签名不匹配 | 有签名,但校验失败,例如文件在签名后被修改;会显示警告 |
启用确认与模组目录的文件内容绑定。文件发生变化后,Folia 会撤销确认并禁用模组;检查变化后,在面板中重新启用并确认。开发版中放在主仓库 mods/ 目录下的模组有专门的调试豁免,详情见调试循环。
透明歌词视频导出
导出类模组可调用宿主的视频导出服务,输出当前歌曲的歌词动画。需要安装完整的 ffmpeg;Folia 自带的 ffmpeg-audio/ 只用于音频转码,不能用于视频导出。查找顺序为 FOLIA_FFMPEG_PATH、应用目录下的 ffmpeg-8.1.2/ffmpeg(.exe)、打包资源目录下的 ffmpeg/ffmpeg(.exe)、系统 PATH。
导出文件保存到「视频/Folia Exports」。当前上限为 3840×2160、60 fps、15 分钟,同时只能运行一个导出任务。透明通道在 Windows 上完整支持;Linux 和 macOS 的输出可能不含 Alpha,此时导出结果会给出警告。
常见问题
找不到「模组」命令? 先确认桌面版的「设置 → 实验室 → 模组系统」已开启。
模组安装后没有出现功能? 安装后仍是禁用状态。到面板中单独启用并确认;如果加载失败,查看面板显示的错误。
改过模组文件后突然被禁用? 内容变化会撤销上次确认。检查文件来源与改动后重新启用。
如何发布到官方模组市场? 阅读开发与贡献指南的发布流程。