folia-major

项目简介

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 等本地能力。模组以可信代码运行，每个模组在启用前都要在原生窗口中确认，文件变化后需要重新确认。

• 模组市场：folium-compound.cielaniska.top 提供官方模组和经过审查的社区模组，下载 zip 后拖进模组面板即可安装。
• 官方认证：市场里的模组都带有 Folium 签名，安装后显示「官方认证」；只通过安全审查的先行测试模组显示「先行测试」；没有签名的第三方模组显示「未验证」，同样可以使用。
• 开发与贡献：模组开发与贡献指南，从写第一个模组、本地调试，到提交到模组市场、审查与签名、发布更新。
• API 参考：Folium API 参考，由契约文件生成的完整接口文档，按注册表、上下文、事件、服务等分类查询。
• 平台规范：Folium 规范，包括清单字段、权限、注册表语义、事件、安全模型与版本策略。
• 示范模组：仓库的 mods/ 目录，覆盖歌词动画、调参、进度条、播放页图层与透明视频导出。

Sync Server

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

支持以下部署方式：

• Cloudflare Workers / D1：免服务器运维的 Serverless 部署，推荐使用。
• Docker：镜像与 Compose 入口见 Docker 部署目录。
• Node.js 自托管：使用 SQLite，适合本地或不方便使用 Docker 的环境。

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

本地音乐与匹配说明

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

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

Community

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

贡献者

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

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

法律与免责声明

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

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

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

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

致谢

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

• chenmozhijin/LDDC
• NeteaseCloudMusicApiEnhanced
• chenglou/pretext
• MakcRe/KuGouMusicApi
• paper-design/shaders
• yakult-green-tea/qq-music-api

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

许可证

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

About

Folia is an online music player built around full-screen, immersive lyrics. It supports NetEase Cloud Music, Kugou, QQ Music, Navidrome, and local music libraries; the desktop app also supports Bodian Music, YouTube Music, Spotify, and Qishui Music. Smart lyric matching, AI-generated color themes, and a range of full-screen lyric animations make listening feel different.

Folia ships as an Electron desktop app for Windows, macOS, and Linux, and as a Node.js web app you can deploy to many platforms.

To use Folia on a phone or in a browser, deploy the web app to Vercel in one click, or deploy it yourself to any platform that runs Node.js.

Quick download

[!TIP]

• GitHub: Latest Release has installers for Windows, macOS, and Linux.
• Cloud drives (faster in mainland China): Quark · Baidu (code flia). Stable installers for Windows and Apple silicon only.

For other options (web deployment, Docker, AUR, Flatpak, mobile), see Get Folia below.

Showcase

Demo videos

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

Selected styles

Fume	Luminous
Mindscape	Partita
Cappella	Tilt
Diorama	Pendolo

Each lyric animation has its own typography, mood, and tunable parameters, giving full-screen lyrics the richness of a lyric video while staying responsive to any window size.

Features

Feature	Description
Online search and playback	Search for songs, artists, or albums and play them; covers and lyrics load automatically.
Local music	Import local audio files. Folia stores the index locally and never uploads file contents. See Local Library Management (Chinese).
Smart lyric matching	Local songs are matched to online lyrics and covers automatically; you can correct matches by hand.
Local lyric files	Loads .lrc, .vtt, .ttml, .qrc, .yrc, and .krc files with the same name in the same folder, as well as embedded LRC lyrics. Supports the enhanced word-by-word formats produced by LDDC.
Now Playing integration	Connects to a local Now Playing service to take song, timeline, and lyric data from external players and drive Folia's stage view and full-screen lyrics.
AI themes	Generates immersive backgrounds and visual parameters from a song's mood and lyrics.
Multi-platform	Deploy as a web app or install the packaged desktop app.
Mods (experimental)	On desktop, Folium mods can add lyric animations, backgrounds, player-page layers, commands, and more. Install officially verified mods from the mod market. See Mods.

Get Folia

The desktop app bundles both frontend and backend, so it works right after install.

One-click deployment

To put the web app online quickly, follow the Vercel deployment guide.

Folia also deploys to Cloudflare in one click; adapt the Vercel guide accordingly.

On Vercel and Cloudflare, QQ Music no longer needs a separate, always-on API instance: set VITE_QQ_API_BASE to /api/qq and add a QQ_SESSION_SECRET (a server-side secret, without the VITE_ prefix). This setup supports login by scanning a QR code with WeChat or mobile QQ (mobile QQ requires qq-music-api 3.3.3 or later), and you must log in before playback. On Cloudflare you can also bind a Durable Object so QQ QR login uses a long-lived connection and gains QR login with the QQ Music app. For full steps, platform differences, and troubleshooting, see the QQ Music deployment guide (Chinese).

Self-hosters can use the Docker Compose full-stack deployment. Access to local music folders requires a trusted HTTPS secure context; the deployment docs cover NAS reverse proxies and certificate requirements.

Direct download

• Windows / macOS / Linux: Download the latest installers from the Releases page.
• Arch Linux: Install folia-major-bin from the AUR.
• Flatpak: A community-maintained third-party Flatpak is available on Flatpark.
• Android: Third-party community ports are listed under Mobile below.

[!IMPORTANT] If GitHub Releases is slow from mainland China, download from Quark or Baidu instead. These links host stable installers for Windows and Apple silicon only.

For Linux packages, the Wayland / Hyprland remote control window, and other desktop details, see Technical Notes (Chinese).

Mobile

Option	Details
PWA (recommended)	Deploy the web or self-hosted version, then add it to your home screen from Chrome for Android or iOS Safari to use it as a PWA.
Community ports (Android)	maimai993/folia-sonnet · whycfawa/folia-android
Build it yourself (Android)	If you are comfortable with the tooling, package the web version as an installable APK with Capacitor. See the example repository chthollyphile/folia-sonnet.

[!NOTE] Community ports are third-party projects maintained independently by the community, and their features differ from the official desktop version. Please report any issues to the corresponding repository.

Documentation and development

For the full user guide, visit Folia Guide.

Deployment, environment variables, local development, the Stage API, common scripts, and the tech stack are covered in Technical Notes (Chinese).

Before contributing, read the Contributing Guide.

Mods (Folium v1.x)

[!NOTE] Mods are experimental, available in the desktop app only, and off by default. Turn them on in Settings → Mods → Mod system.

Folium is Folia's mod platform. Mods can add lyric animation modes and background types, overlay content on the player page, add buttons and markers to the progress bar, register commands and settings sections, rewrite lyrics before they are displayed, and use native capabilities such as ffmpeg through a Node entry point. Mods run as trusted code: you confirm each mod in a native window before it is enabled, and confirm again after its files change.

• Mod market: folium-compound.cielaniska.top hosts official mods and reviewed community mods. Download the zip and drag it into the Mods panel to install.
• Verification: Every mod in the market carries a Folium signature and shows as Verified after install. Early-access mods that passed only the security review show as Preview. Third-party mods without a signature show as Unverified and still work.
• Developing and contributing: The mod development and contribution guide walks from your first mod and local debugging through submitting to the market, review and signing, and publishing updates.
• API reference: The Folium API reference is generated from the contract file and organized by registries, contexts, events, and services.
• Platform spec: The Folium spec covers manifest fields, permissions, registry semantics, events, the security model, and versioning.
• Example mods: The repository's mods/ folder covers lyric animations, tuning, the progress bar, player-page layers, and transparent video export.

Sync Server

Folia offers an optional official sync server, sync-server, that syncs appearance settings and the AI theme library across devices. You host it yourself; it suits anyone who wants their color themes on every device.

Deployment options:

• Cloudflare Workers / D1: Serverless, no servers to maintain. Recommended.
• Docker: See the Docker deployment folder for the image and Compose setup.
• Self-hosted Node.js: Uses SQLite; suits local machines or environments where Docker is inconvenient.

For environment variables, token setup, and deployment steps, see the Sync Server deployment guide. Once deployed, enter the server URL and SYNC_TOKEN in Settings → Connections to turn on sync.

Local music and matching

Folia reads audio metadata plus lyrics and covers from the same folder, and can fill in song details from NetEase Cloud Music, QQ Music, or Kugou. Automatic matching tries NetEase, then QQ, then Kugou. When a match is wrong, you can pick another candidate, restore the local data from the first import, or merge and split artist and album entries.

For importing, rescanning, matching, entry editing, playlists, caching, and troubleshooting, see Local Library Management (Chinese).

Community

Join the Discord to chat and get help.

Contributors

Thanks to everyone who has filed issues, reported bugs, suggested ideas, tested, or written code. Contributions are tracked under the all-contributors specification.

The list is long, so see Contributors.

Legal and disclaimer

This project was developed with extensive AI assistance and may still contain subtle or hard-to-spot problems. We apologize for any inconvenience.

The project mainly showcases playback animation, interface design, and the engineering behind them. Copyright in the online streams, lyrics, album art, and other content shown in the app belongs to the respective rights holders.

This repository and its source code are for personal study, technical exchange, and non-profit testing only. Do not use them for commercial purposes. Users bear sole responsibility for any copyright dispute or other liability arising from distributing, modifying, or redistributing online resources; the developers accept no liability.

Please respect digital rights and support licensed music through official platforms whenever you can.

Acknowledgements

Special thanks to these projects and resources:

• chenmozhijin/LDDC
• NeteaseCloudMusicApiEnhanced
• chenglou/pretext
• MakcRe/KuGouMusicApi
• paper-design/shaders
• yakult-green-tea/qq-music-api

Folia uses the Apple Music-like Lyrics TTML word-by-word lyrics database for high-quality lyric files. Thanks to its authors and contributors.

License

Folia is open source under the AGPL-3.0 license.