Folia Plain

Immersive Lyrics, Simply Music // 歌词入境，听歌归简

简体中文 | English

获取方式 · 本地运行 · 部署说明 · 开发与维护

项目简介

Folia Plain 是一个以沉浸式歌词和动态排版为核心的音乐播放器，基于 Folia / folia-major 独立维护。

保留上游丰富的歌词动效、音乐平台接入、本地曲库和主题能力，将默认视觉整理为抽象图形、几何头像与中性文案。没有内置角色立绘、拟人头像或设置页图片彩蛋，让音乐、歌词和你选择的封面成为界面的重点。

提供基于 React / Vite 的 Web 部署包，以及基于 Electron 的 Windows、macOS、Linux 桌面安装包。

本项目的上游是 chthollyphile/folia-major 音乐播放器，与 Minecraft 服务端 PaperMC/Folia 无关。

Plain 做了什么

内容	调整
群唱头像与表情	替换为几何图案和简洁反应符号；保留自定义导入。
预览封面与歌词	换成抽象封面与原创中性示例，保留逐字、翻译和背景和声演示。
界面文案	使用清晰的操作与加载提示，移除图片彩蛋。
项目身份	统一为 Folia Plain，反馈和更新指向本仓库，桌面数据目录独立。
首页与文档	去掉角色宣传素材，使用简洁排版与本分支的获取说明。
构建流程	提供自动检查和手动桌面构建，不继承上游定时发版与社区机器人。

在线曲库中的音乐分类、日文歌词、用户自己的封面和头像都可正常使用。Plain 整理的是应用自带内容，不限制你的音乐选择。

展示

原创示例 · 抽象封面 · 沉浸式歌词

核心能力

模块	说明
歌词与排版	多种全屏歌词样式，支持逐字歌词、翻译、音译和背景和声。
音乐平台	网易云、QQ 音乐、酷狗；桌面端还保留波点、YouTube Music 与 Spotify 接入。各平台需按要求配置或登录。
本地与自托管曲库	导入本地音乐，连接 Navidrome / Subsonic；可自动匹配歌词与封面。
歌词文件	保留 LRC、VTT、TTML、QRC、YRC、KRC 与 Folia 歌词格式支持。
外观与主题	封面配色、背景与字体调整，可选 AI 主题生成。
桌面集成	保留桌面歌词、Now Playing、OBS、快捷键等上游能力，依平台与配置而定。
扩展与同步	保留实验性 Folium 模组及可自行托管的 Sync Server。

获取方式

• 源码：克隆本仓库后本地运行，步骤见下文。
• Web 下载：本仓库 Releases 提供 Folia-Plain-<版本>-web.zip，内含静态网站及部署说明，在线音乐需配置对应后端。检查通过后也可在 Checks 下载前端产物。
• 桌面构建：维护者可手动运行 Build desktop，从运行页面下载对应平台的构建产物。
• Windows 下载：Releases 提供 x64 .exe 安装包与免安装 ZIP；完整解压 ZIP 后运行 Folia Plain.exe。
• macOS 下载：Releases 提供 Apple Silicon（arm64）与 Intel（x64）的 .dmg 安装包及 ZIP。应用未作开发者签名与公证。
• Linux 下载：Releases 提供 x64 .deb、.rpm 和 .tar.gz。按发行版选择安装包，便携包说明见包内 resources/linux/README-LINUX.txt。

发布附件同时提供 SHA-256 校验值；各平台以对应版本实际列出的附件为准。

上游的安装包、网盘和 AUR 包仍是原版，不能用来安装 Folia Plain。

本地运行

需要 Node.js 24+。

git clone https://github.com/ithtelab/Folia-Plain.git
cd Folia-Plain
npm ci
cp .env.example .env.local
npm run dev -- --host 127.0.0.1

Windows PowerShell 可用 Copy-Item .env.example .env.local 代替复制命令。打开终端输出的地址即可。

界面、歌词样式预览和本地音乐导入可先直接体验。在线平台需要配置相应后端或账户；AI 主题需要自行配置服务密钥。npm run dev 只启动前端，桌面开发可使用 npm run dev:electron。

npm run typecheck
npm run test:unit
npm run build
npm run preview -- --host 127.0.0.1

部署

Vercel 选择 Node.js 24+，构建命令为 npm run build，静态输出目录为 dist。参照环境变量模板按需配置音乐接口与 AI 服务。

QQ 音乐的 serverless 入口、Cloudflare 与 Docker 的平台差异可参考 QQ 音乐部署说明 和 Docker 说明。本分支暂未发布容器镜像，Docker 需要从源码构建。

桌面打包需要平台编译工具和原生依赖，详见开发与维护。跨设备同步可以自行部署 sync-server，再在设置中填写服务地址与令牌。

文档与开发

• 本分支说明、开发、打包与更新上游
• 上游 PR 筛选与移植记录
• 技术与开发说明（继承上游，下载和发版信息以本分支说明为准）
• 本地音乐库管理
• 模组开发指南 · API 参考
• 问题反馈

来源与致谢

感谢 chthollyphile/folia-major 的作者与上游贡献者。本分支从上游 0.7.21（f3a9070）开始，使用独立的提交历史，保留代码版权声明与来源记录。本分支维护者见 CONTRIBUTORS.md，原版 README 存档见 docs/upstream。

同时感谢上游使用的开源项目，包括 LDDC、AMLL TTML 歌词库、网易云音乐 API、QQ 音乐 API、酷狗音乐 API、Pretext 和 Paper Shaders。

许可证

继续使用 AGPL-3.0。本分支新增的矢量素材使用同一许可证。音乐、歌词、专辑封面及外部服务内容的权利归对应权利人所有，请遵守相关服务的使用条款并支持正版音乐。