chthollyphile / folia-major

# Folia
Lyrics Reimagined // 辞曲新境
简体中文 | English
获取方式
·
Vercel 部署
·
使用指南
·
技术说明
## 项目简介
Folia是一个以全屏沉浸式歌词播放为核心的在线音乐播放器，支持网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库，桌面端还支持波点音乐、YouTube Music 和 Spotify，通过智能歌词匹配，AI生成配色主题，以及多种全屏歌词动画为用户提供独特的听歌体验。
提供基于Electron的 windows/ macOS/ Linux 桌面端版本与基于 Node.js 的 Web 版本，支持多平台部署。
如果希望能够在移动设备上使用，或在浏览器上体验，可以选择一键部署到 Vercel 的 Web 版本，或自行部署到其他支持 Node.js 的平台。
## 快速下载
> [!TIP]
> - **GitHub**：Latest Release，提供 Windows / macOS / Linux 全平台安装包。
> - **网盘**：夸克网盘 · 百度云（提取码 `flia`），适合国内网络，仅提供 Windows 与 Apple silicon 的正式版安装包。
>
> 更多获取方式（Web 部署、Docker、AUR、Flatpak、移动端）见下方 获取方式。
## 展示
### 演示视频
https://github.com/user-attachments/assets/af806cf1-f67f-4b88-b2e7-57db507e9e81
https://github.com/user-attachments/assets/fd27f4f0-64b9-4c57-8c3b-10df767f934b
https://github.com/user-attachments/assets/704f195a-2194-434b-86e8-8f36290e5cc4
### 部分主题预览
 浮名 
 流光 
 心象 
 云阶 
 群唱 
 倾诉 
 镜台 
 时计 
不同的歌词动画具有不同的排版氛围和可调参数，让全屏歌词拥有如同文字PV般的丰富视觉效果，同时又能兼顾响应式布局，自动适配不同窗口尺寸。
## 核心能力
| 模块 | 说明 |
| --- | --- |
| 在线搜索与播放 | 搜索歌曲、歌手或专辑后即可播放，并自动加载相关封面与歌词。 |
| 本地音乐支持 | 可导入本地音频文件，在本地安全保存索引信息，不上传文件内容。详细用法见 本地音乐库管理。 |
| 智能歌词匹配 | 本地歌曲可自动匹配在线歌词与封面，也支持手动修正匹配结果。 |
| 本地歌词文件识别 | 自动加载同目录同名 `.lrc`、`.vtt`、`.ttml`、`.qrc`、`.yrc`、`.krc` 歌词文件，或歌词文件内嵌 LRC 歌词。适配 LDDC 生成的增强型逐字歌词格式。 |
| Now Playing 接入 | 支持通过本机 Now Playing 服务接入外部播放器的歌曲、时间轴与歌词信息，并驱动 Folia 的舞台视图与全屏歌词渲染。 |
| AI 主题生成 | 基于歌曲情绪与歌词内容生成沉浸式背景与视觉参数。 |
| 多端体验 | 提供 Web 部署方式，同时支持桌面端打包分发。 |
| 模组系统（实验性） | 桌面版可通过 Folium 模组添加歌词动画、背景、播放页图层、命令等，并从 模组市场 安装官方认证的模组。详见 模组系统。 |
## 获取方式
桌面版内置前后端运行环境，适合希望即装即用的用户。
### 一键部署
如果你希望快速上线 Web 版本，请阅读 Vercel 一键部署指南 来创建项目
项目也支持一键部署到 Cloudflare，请参考 Vercel 的部署教程进行相应调整。
Vercel 与 Cloudflare 上的 QQ 音乐不再需要额外部署一个常驻 API 实例：把 `VITE_QQ_API_BASE` 填成 `/api/qq`，再配一个 `QQ_SESSION_SECRET`（服务端密钥，**不加 `VITE_` 前缀**）即可。这种形态支持微信扫码和手机 QQ 扫码登录（手机 QQ 扫码要 qq-music-api 3.3.3 或更高版本），且播放前必须先登录；Cloudflare 上可以再绑定一个 Durable Object，让 QQ 扫码改走长连接，并多一个 QQ 音乐 App 扫码。完整步骤、平台差异和排错方法见 QQ 音乐部署指南。
自托管用户可以使用 Docker Compose 全栈部署。本地音乐目录访问依赖可信 HTTPS 安全上下文，部署文档包含 NAS 反向代理和证书要求。
### 直接下载
- **Windows / macOS / Linux**: 最新版本的安装包请前往 Releases 页面 下载。
- **Arch Linux**: 可通过 AUR 获取 folia-major-bin。
- **Flatpak**: 社区提供的第三方 flatpak，详情见 Flatpark。
- **Android**: 社区第三方移植版见下方 移动端。
> [!IMPORTANT]
> 如果国内网络从 GitHub Releases 下载较慢，可以使用 夸克网盘 或 百度云 下载。网盘链接仅提供 Windows 与 Apple silicon 的正式版安装包.
Linux 包、Wayland / Hyprland 遥控窗和桌面端细节见 技术与开发说明。
### 移动端
| 方式 | 说明 |
| --- | --- |
| **PWA（推荐）** | 部署 Web 版本或自托管版本后，在 Chrome for Android / iOS Safari 中将网页添加到主屏幕，即可作为 PWA 应用使用。 |
| **社区移植版（Android）** | maimai993/folia-sonnet · whycfawa/folia-android |
| **自行打包（Android）** | 有一定技术基础的用户可以用 Capacitor 将 Web 版本打包为可安装的 APK，参考示范仓库 chthollyphile/folia-sonnet。 |
> [!NOTE]
> 社区移植版均为第三方项目，由社区自发维护，功能会与官方 PC 版存在差异。使用中遇到问题请反馈到对应的社区仓库。
## 文档与开发
更完整的使用说明请访问 Folia Guide。
部署、环境变量、本地开发、Stage API、常用脚本和技术栈见 技术与开发说明。
## 模组系统（Folium v1.x）
> [!NOTE]
> 模组系统是实验性功能，仅桌面版可用，默认关闭，需要在「设置 → 模组 → 模组系统」中开启。
Folium 是 Folia 的模组平台。模组可以添加新的歌词动画模式和背景类型、在播放页上叠加内容、给进度条加按钮和标记、注册命令与设置分区、在歌词显示前改写歌词，也可以通过 Node 入口调用 ffmpeg 等本地能力。模组以可信代码运行，每个模组在启用前都要在原生窗口