chthollyphile/folia-major：一款专注于绚丽歌词动画的本地音乐/第三方网易云播放器

这是什么

Folia 是一个以全屏沉浸式歌词播放为核心的在线音乐播放器，主语言 TypeScript，GitHub 星标 911。它同时支持网易云音乐、Navidrome 自建音乐库以及本地音乐文件三种音乐源，在播放全屏歌词时提供多种动画效果、AI 自动生成的配色主题，以及类似文字 PV 的视觉体验。项目提供了基于 Electron 的桌面端（Windows / macOS / Linux）和可一键部署到 Vercel 的 Web 版本，后者也能在移动设备的浏览器上使用。桌面版内置前后端运行环境，开箱即用；Web 版则依赖 Node.js 运行时，适合在云端多平台访问。

解决的问题

传统音乐播放器在歌词展示上往往停留在“跟唱提示”层面——歌词列表滚动、高亮当前行，视觉上单调且浪费屏幕空间。Folia 瞄准的核心痛点是：如何让歌词本身成为音乐欣赏的一部分，而不仅是辅助工具。它解决了以下具体问题：

• 屏幕利用率低：多数播放器歌词占据播放界面的一小部分，大量空间被专辑封面、控制按钮或无关信息占据；Folia 将歌词铺满全屏，环境光、配色、动画全部围绕歌词展开。
• 歌词来源单一且匹配粗糙：本地音乐常缺少歌词文件，在线平台又可能因版权限制无法获取歌词。Folia 内置三层补全机制（文件元数据 → 同目录同名歌词文件 → 在线匹配），并在匹配不准时提供手动搜索与指定歌词、封面、元数据的入口。
• 多音乐源管理割裂：用户在不同平台（网易云、Navidrome、本地）之间切换体验不一致。Folia 在一个界面内统一调度这些音乐源，无需切换应用。

核心功能

• 全屏沉浸式歌词播放：歌词动画包括多种排版氛围和可调参数，自动适配不同窗口尺寸（响应式布局）。动画效果如同文字 PV，支持逐词高亮、渐变、位移、缩放等。
• AI 生成配色主题：根据当前歌曲的封面或风格，自动生成一套符合氛围的配色方案，覆盖背景、文字高亮、环境光等元素，无需手动调色。
• 多音乐源整合：
  • 网易云（在线流媒体）
  • Navidrome（自建音乐库服务）
  • 本地音乐文件（通过文件系统读取）
• 智能歌词匹配与补全：
  • 优先从音频文件自身元数据获取歌词；
  • 其次搜索同目录下的同名 .lrc 或 .ttml 歌词文件；
  • 最后尝试在线匹配；
  • 用户可在播放界面右侧面板的“本地”选项卡内手动搜索并指定更合适的歌词、封面或元数据来源，也可关闭在线匹配结果只使用本地信息。
• Apple Music-like Lyrics TTML 逐词歌词支持：接入高质量逐词歌词库，实现字级时间轴同步。
• 跨平台支持：
  • 桌面端（Electron）：直接下载 Release 包，内置前后端，即装即用；
  • Web 端：一键部署到 Vercel，也支持自部署到其他 Node.js 平台；
  • 移动端：通过浏览器访问 Web 版本即可体验。
• Linux 窗口管理特殊支持：提供 Wayland / Hyprland 遥控窗支持。

亮点 / 与同类相比

• 视觉沉浸感远强于主流播放器：同类应用（如网易云桌面版、Spotify、Apple Music）的歌词模式通常只是“大字号歌词滚动”，Folia 则把全屏动画、AI 配色、环境光和排版融为一体，观赏性接近专业的文字 MV（音乐视频）。
• 响应式全屏动画：不固定分辨率或比例，动画会自动适配从手机竖屏到 4K 横屏的任何窗口尺寸，这在同类歌词工具中少见。
• 开源且版权友好：AGPL-3.0 许可证，源代码透明；项目明确声明仅供学习、技术交流与非营利测试使用，不鼓励对在线资源的非法传播。这种清晰的版权立场在歌词相关的开源项目中并不多见。
• 多生态整合而非绑定：不像网易云仅支持自家音乐，Folia 同时覆盖网易云、Navidrome、本地文件，用户可混合使用，不被单一服务锁定。
• AI 辅助开发但并非核心卖点：项目在 AI 广泛协助下开发，但最终体验中的 AI 体现在“生成配色主题”和“歌词匹配”上，并非空洞的“AI 赋能”。

适合谁用 / 上手

• 音乐重度用户 & 沉浸式聆听爱好者：喜欢一边听歌一边看歌词，且希望获得富有情绪感的视觉体验的人。
• 本地音乐收藏者 & Navidrome 用户：拥有大量本地音乐文件或自建 Navidrome 服务，希望获得更精致的播放界面和歌词匹配体验。
• 前端 / 桌面端开发者：TypeScript 项目，可学习全屏动画实现、Electron 集成、多音乐源统一抽象、歌词元数据处理等技术点。
• 想快速部署个人音乐面板的用户：Web 版本可一键部署到 Vercel（免费），只需要 Git Clone + 配置环境变量（如网易云 API 地址、Navidrome 服务器信息）即可上线，无需自己搭建后端。
• Linux 桌面用户：支持 Wayland / Hyprland 的遥控窗，适合 WM 环境。

上手路径：

• 立即体验：下载桌面端 Release（Windows / macOS / Linux）双击运行；或访问 Web 版（自行部署或使用演示链接）。
• 本地开发：克隆仓库，配置 .env 文件（网易云 API 地址、Navidrome 地址等），执行 npm install && npm run dev。
• 配置音乐源：首次启动后进入设置，添加网易云账号或 Navidrome 服务器地址，或直接扫描本地音乐文件夹。
• 歌词优化：如果自动匹配不准确，右键播放界面 → 右侧面板“本地”选项卡 → 手动搜索歌词或指定本地文件。