folia-major README

The project's README from github.com/chthollyphile/folia-major. As one markdown file: README.md.

Folia

chthollyphile%2Ffolia-major | Trendshift

Folia

Lyrics Reimagined // 辞曲新境

GitHub release License GitHub stars Node.js Ask DeepWiki Discord

All Contributors

获取方式 · Vercel 部署 · 使用指南 · 技术说明

项目简介

Folia是一个以全屏沉浸式歌词播放为核心的在线音乐播放器，支持网易云、酷狗、Navidrome 和本地音乐库，通过智能歌词匹配，AI生成配色主题，以及多种全屏歌词动画为用户提供独特的听歌体验。

提供基于Electron的 windows/ macOS/ Linux 桌面端版本与基于 Node.js 的 Web 版本，支持多平台部署。

如果希望能够在移动设备上使用，或在浏览器上体验，可以选择一键部署到 Vercel 的 Web 版本，或自行部署到其他支持 Node.js 的平台。

展示

visualizer

演示视频

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

部分主题预览

Fume 主题预览 Lumi 主题预览
浮名 流光
Cad 主题预览 Pat 主题预览
心象 云阶
群唱 主题预览 Tilt 主题预览
群唱 倾诉
镜台 主题预览 时计 主题预览
镜台 时计

不同的歌词动画具有不同的排版氛围和可调参数，让全屏歌词拥有如同文字PV般的丰富视觉效果，同时又能兼顾响应式布局，自动适配不同窗口尺寸。

核心能力

模块 说明
在线搜索与播放 搜索歌曲、歌手或专辑后即可播放，并自动加载相关封面与歌词。
本地音乐支持 可导入本地音频文件，在本地安全保存索引信息，不上传文件内容。详细用法见 本地音乐库管理。
智能歌词匹配 本地歌曲可自动匹配在线歌词与封面，也支持手动修正匹配结果。
本地歌词文件识别 自动加载同目录同名 .lrc、.vtt、.ttml、.qrc、.yrc、.krc 歌词文件，或歌词文件内嵌 LRC 歌词。适配 LDDC 生成的增强型逐字歌词格式。
Now Playing 接入 支持通过本机 Now Playing 服务接入外部播放器的歌曲、时间轴与歌词信息，并驱动 Folia 的舞台视图与全屏歌词渲染。
AI 主题生成 基于歌曲情绪与歌词内容生成沉浸式背景与视觉参数。
多端体验 提供 Web 部署方式，同时支持桌面端打包分发。
模组系统（实验性） 桌面版可通过 Folium 模组添加歌词动画、背景、播放页图层、命令等，并从 模组市场 安装官方认证的模组。详见 模组系统。

获取方式

桌面版内置前后端运行环境，适合希望即装即用的用户。

一键部署

如果你希望快速上线 Web 版本，请阅读 Vercel 一键部署指南 来创建项目

Deploy with Vercel

项目也支持一键部署到 Cloudflare，请参考 Vercel 的部署教程进行相应调整。

Deploy to Cloudflare

Vercel 与 Cloudflare 上的 QQ 音乐不再需要额外部署一个常驻 API 实例：把 VITE_QQ_API_BASE 填成 /api/qq，再配一个 QQ_SESSION_SECRET（服务端密钥，不加 VITE_ 前缀）即可。这种形态默认只支持微信扫码登录，且播放前必须先登录；Cloudflare 上可以再绑定一个 Durable Object，增加 QQ 扫码登录方式。完整步骤、平台差异和排错方法见 QQ 音乐部署指南。

自托管用户可以使用 Docker Compose 全栈部署。本地音乐目录访问依赖可信 HTTPS 安全上下文，部署文档包含 NAS 反向代理和证书要求。

关于移动端：

目前推荐移动端用户部署 Web 版本/自托管版本之后，通过chrome for android / iOS Safari 创建 PWA应用（也就是将网页应用添加到桌面，Folia web版本支持安装为PWA应用）来使用。

有一定技术的用户可以使用 capacitor 将本项目的web版本打包成为可安装的安卓apk，具体方法可参考示范仓库：chthollyphile/folia-sonnet

直接下载

[!IMPORTANT] 如果国内网络从 GitHub Releases 下载较慢，可以使用 夸克网盘 或 百度云 下载。网盘链接仅提供 Windows 与 Apple silicon 的正式版安装包.

Linux 包、Wayland / Hyprland 遥控窗和桌面端细节见 技术与开发说明。

文档与开发

更完整的使用说明请访问 Folia Guide。

部署、环境变量、本地开发、Stage API、常用脚本和技术栈见 技术与开发说明。

模组系统（Folium v1.x）

[!NOTE] 模组系统是实验性功能，仅桌面版可用，默认关闭，需要在「设置 → 实验室 → 模组系统」中开启。

Folium 是 Folia 的模组平台。模组可以添加新的歌词动画模式和背景类型、在播放页上叠加内容、给进度条加按钮和标记、注册命令与设置分区、在歌词显示前改写歌词，也可以通过 Node 入口调用 ffmpeg 等本地能力。模组以可信代码运行，每个模组在启用前都要在原生窗口中确认，文件变化后需要重新确认。

Sync Server

Folia 提供了可选的官方同步服务端 sync-server，用于在多个设备之间同步外观设置与 AI 主题库。服务端由用户自行托管，适合希望跨设备同步配色主题的用户。

支持以下部署方式：

详细的环境变量、Token 配置与部署步骤请参阅 Sync-Server 部署指南。部署完成后，在 Folia 的“存储设置”中填写服务端地址和 SYNC_TOKEN 即可启用同步。

本地音乐与匹配说明

Folia 会读取音频文件元数据、同目录歌词和封面，并可通过网易云、QQ 音乐或酷狗音乐补全歌曲信息。自动匹配按网易云、QQ、酷狗依次回退；匹配不准确时，可以手动选择候选、恢复首次导入的本地信息，或进一步合并、拆分艺术家与专辑实体。

完整的导入、重扫、匹配、实体编辑、歌单、缓存和故障排查说明见 本地音乐库管理。

Community

加入discord社群，共同交流，获得帮助

Discord

贡献者

感谢所有为本项目进行 Issue 提交、Bug 报告、想法建议、测试与代码编写的贡献者，均依据 all-contributors 规范进行统计

由于列表过长，贡献记录请见 贡献者名单。

法律与免责声明

本项目在 AI 的广泛协助下开发，因此仍可能存在细微或不易察觉的问题。若给你带来不便，敬请理解。

本项目主要用于展示播放动效、界面设计与相关工程实现。应用中涉及的在线音乐流媒体、歌词、专辑封面及其他内容，其版权均归对应权利人所有。

本仓库及其源代码仅供个人学习、技术交流与非营利测试使用。请勿将其用于商业盈利用途。若因对在线资源的传播、加工或再分发而引发版权纠纷或其他责任，均由使用者自行承担，项目开发者不承担相关责任。

请始终尊重数字版权，并在条件允许时通过官方平台支持正版音乐。

致谢

特别感谢以下项目和资源：

本项目接入了 Apple Music-like Lyrics TTML 逐词歌词库 以提供高质量的歌词文件，感谢此歌词库的作者和贡献者们。

许可证

本项目基于 AGPL-3.0 许可证开源。

folia-major (chthollyphile/folia-major)

Searching Database…

8.5K ·GitHub
Folia-major
这是什么？Folia 是一个以全屏沉浸式歌词播放为核心的在线音乐播放器，支持网易云音乐、酷狗、Navidrome 和本地音乐库，带智能歌词匹配和 AI 生成的配色主题。
这是桌面应用还是网页应用？两者都是——它既有面向 Windows/macOS/Linux 的 Electron 桌面应用，也有基于 Node.js、可自托管或部署的网页版，网页版还能作为 PWA 安装。
怎么把它跑起来？桌面应用从 Releases 页面下载预编译安装包；网页版可一键部署到 Vercel 或 Cloudflare，也可以用 Docker Compose 自托管整套服务。
用本地音乐文件夹需要什么特殊条件吗？需要——访问本地音乐文件夹要求处于受信任的 HTTPS 环境，所以自托管部署需要带有效证书的反向代理（NAS 设置说明在部署文档里）。
有原生移动应用吗？没有官方的——官方推荐在手机上通过 Android 版 Chrome 或 iOS Safari 把网页版作为 PWA 安装；用 Capacitor 打包成 Android APK 只在文档里作为社区变通方案提及。
AGPL-3.0 许可证有什么限制？项目采用 AGPL-3.0，README 明确把用途限定在个人学习、技术交流和非营利测试——声明不要把它用于商业盈利。
Folia 的歌词和一般音乐播放器有何不同？每个主题都把全屏歌词动画风格与根据歌曲情绪调配的 AI 生成配色和布局相结合，追求歌词 MV 的感觉，而不是单纯滚动的歌词条。
Folium mod 系统是什么？Folium 是 Folia 实验性的、仅限桌面的插件平台。Mod 可以添加歌词动画模式、背景、覆盖层和命令，由于它们以受信任代码的身份执行，运行前必须在原生窗口里手动确认。
我的主题能在多台设备间同步吗？可以，通过可选的自托管同步服务器实现，它能跑在 Cloudflare Workers/D1、Docker 或带 SQLite 的 Node.js 上，在设备之间同步外观设置和 AI 主题库。
它支持哪些歌词文件格式？Folia 会自动加载音轨同目录下匹配的 .lrc、.vtt、.ttml、.qrc、.yrc 和 .krc 文件，以及内嵌 LRC 歌词，包括 LDDC 的增强逐字歌词格式。
What are similar projects?YesPlayMusic, edgeever, AlgerMusicPlayer, TREK, Minke, Termix, go-music-dl, omnivore
Which topics is it in?vercel-deployment, archlinux, player, flatpak, music-player, pwa, serverless, discord, music, cloudflare, plugin-system, electron
Creator
chthollyphile
Size
52.5 MB
Stars
8.5K
Updated
CommitOct 20Releasev0.7.21Oct 18
Age
10mo
Commits · 90 Days