Skip to content

模组系统(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 的原始音频流或解密之后的原始音频文件的模组,都有极高的平台法律风险。无论采用何种实现方式,此类模组都不会上架官方模组市场。

开启和安装 ​

  1. 在「设置 → 实验室 → 模组系统」开启总开关。
  2. 在命令面板执行「模组」,打开管理面板。
  3. 从官方模组市场下载模组 zip,拖入面板安装;也可以点击「打开模组目录」,手动放入模组。
  4. 在面板中启用模组,并阅读原生确认窗口里的入口、权限、实验接口、签名与文件位置后确认。

关闭总开关会停用已启用的模组,停止加载模组代码。安装 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,此时导出结果会给出警告。

常见问题 ​

找不到「模组」命令? 先确认桌面版的「设置 → 实验室 → 模组系统」已开启。

模组安装后没有出现功能? 安装后仍是禁用状态。到面板中单独启用并确认;如果加载失败,查看面板显示的错误。

改过模组文件后突然被禁用? 内容变化会撤销上次确认。检查文件来源与改动后重新启用。

如何发布到官方模组市场? 阅读开发与贡献指南的发布流程。

Released under AGPL-3.0