你的第一场
歌词音乐会。

从安装到第一首歌，跟着这份手册，
把 Folia 变成你喜欢的样子。

第一次使用 Folia 音乐播放器

1. 先到 下载页 选择桌面版本并安装。桌面版内置运行环境，无需自行搭建后端。
2. 启动后进入资料库。在线音乐可从账户入口选择音源；本地音乐从「本地」入口导入。
3. 在 Bravais 界面中，点击歌曲海报展开大卡，再点击播放按钮。
4. 进入可视化播放页，打开右侧面板选择歌词模式；将音量调到适合的大小。

安装与设备使用

Windows

1. 在下载页选择 Windows 入口，获取适用的 x64 .exe 安装包。
2. 运行安装程序并按提示完成安装，然后从开始菜单或桌面启动 Folia。
3. 若安装或启动被拦截，先确认文件来自原项目发行渠道，再按系统提示查看文件或应用权限。

macOS

1. 在「关于本机」确认处理器：Apple 芯片选择 arm64，Intel 选择 x64。
2. 打开 .dmg，将 Folia 拖入「应用程序」并启动。
3. 若系统阻止首次启动，检查「系统设置 → 隐私与安全性」的允许打开选项。若提示文件损坏，先重新下载并核实来源，再查阅 本页问题排查。

Linux

Debian / Ubuntu / Linux Mint 选择 .deb；Fedora / RHEL / openSUSE 选择 .rpm；其他发行版可查看 tar.gz。Arch / Manjaro 可在了解软件包来源后使用 AUR 的 folia-major-bin。

移动设备安装

Android：社区 APK 移植版

从下载页获取 Android 社区 APK。安装前确认来源为 folia-sonnet 或 folia-android 社区项目，下载到设备后按照 Android 系统提示安装。社区版非官方正式版，由各自维护者独立维护，功能与桌面版存在差异。

Android 也可以用 Chrome 打开已部署的 Folia Web，通过浏览器菜单添加到主屏幕。

iOS：Safari 添加到主屏幕

iPhone / iPad 暂无官方原生 IPA 安装版，请使用 Web/PWA。

1. 准备一个已部署且可访问的 Folia Web 实例。
2. iPhone / iPad：用 Safari 打开实例，点击「分享」，选择「添加到主屏幕」，确认名称并添加。
3. 从主屏幕启动。首次播放需要手动点击；本地文件访问与音频解码需要浏览器支持。

把收藏，带进 Folia。

推荐导入包含音乐的整个文件夹。Folia 会递归扫描子目录，读取歌曲标题、艺术家、专辑、封面和歌词，不要求上传原始音频。

第一步：进入本地音乐

在首页中央信息条点击「本地」。如果信息条处于折叠状态，先点侧边标题标签展开。

第二步：导入音乐文件夹

点击信息条底部的「⋯」，选择「导入文件夹」。在系统选择器中选中音乐目录，并授予访问权限。

第三步：等待扫描并检查歌曲

扫描完成后，打开文件夹或专辑，点击歌曲展开大卡并播放。可在「⋯ → 目录」查看导入的目录与曲目。文件增删后可以重新导入或检查文件夹，进行增量扫描。

歌词与格式

把歌词放在音频同目录并保持基础文件名一致，例如 track.flac 与 track.lrc。也支持 TTML、VTT、QRC、YRC、KRC 等歌词，具体效果取决于歌词数据。

常见 MP3、FLAC、WAV 等可直接播放；APE、ALAC 等格式可在桌面版通过兼容转换播放。Web 版文件夹导入依赖 File System Access API，建议使用兼容的 Chrome / Edge；权限失效时按提示重新授权。

接入常用的在线曲库

1. 在资料库首页点击账户入口，展开音源列表，选择网易云、酷狗或 QQ 音乐等可用来源。
2. 按该平台提供的方式登录。可播放内容取决于账号权限、版权区域、会员状态及接口可用性。
3. 点击信息条底部的放大镜，输入歌曲、歌手或专辑，再提交搜索。
4. 打开搜索结果，选择歌曲并播放。若无声音，先检查音量与音源登录状态。

注意区分「过滤当前页」和「搜索在线平台」：直接在墙面输入文字通常只过滤眼前的收藏。在线搜索请使用首页放大镜入口。

桌面端内置部分在线接口；自行部署 Web 版时，还需按原项目文档配置所需的音乐 API 服务。

选一座属于你的歌词舞台

1. 开始播放一首歌曲，进入可视化播放页并展开右侧面板。
2. 选择视觉模式，或从「设置 → 界面 → 外观 → 歌词动画样式」进入。
3. 先试试流光、心象、浮名与群唱，再按需要调整字号、背景与该模式支持的动画参数。
4. 逐字高亮需要逐字时间轴。如果只有逐行歌词，先检查歌词来源或更换匹配结果。

歌词不对或不同步？

先在右侧歌词面板查看当前来源并手动重新匹配。单首歌曲不同步时调整单曲偏移；蓝牙等固定输出延迟可用「设置 → 音乐 → 歌词 → 全局时间偏移」补偿。不要用全局偏移修正一首歌词文件本身的错误。

为每首歌，生成一种情绪。

AI 主题会根据歌词或纯音乐标题生成视觉配色，包括背景、主文本、强调色和次级文本等。它需要你配置支持的 AI 服务。

1. 桌面端进入「设置 → 界面 → 外观 → AI 主题设置」。
2. 选择 Google Gemini 或 OpenAI 兼容服务，填写该服务的 API Key；兼容服务还需填写接口地址与模型名。
3. 播放一首已有歌词的歌曲，或有明确标题的纯音乐，使用主题生成功能。
4. 生成完成后应用主题，观察背景与歌词颜色。结果不满意可以重新生成、切回默认主题或保存自定义主题。

自行部署 Web 版时，应由部署者配置对应 AI 环境变量。API 的可用模型、计费和权限由服务提供方决定；主题生成会将所需歌词或标题发送至配置的服务。

连接你的私人曲库

准备好可访问的 Navidrome / Subsonic 兼容服务器、用户名和密码。建议使用 HTTPS 及单独的普通账号。

1. 进入「设置 → 应用 → 连接与集成 → 服务 → Navidrome」；也可以在命令面板搜索「Navidrome 服务器」。
2. 启用连接，填写完整的服务器地址（包含协议、端口及必要路径）、用户名和密码。
3. 点击「测试连接」。成功后查看服务器信息与可访问音乐库，再保存配置。
4. 返回首页，在「Navi」入口浏览专辑、歌手和歌单，选择歌曲播放。

连接不成功时

先确认同一设备能访问服务器；再检查地址、账号权限和音乐库扫描状态。Web 版需留意跨域配置，以及 HTTPS 页面访问 HTTP 服务器导致的混合内容限制。服务端歌词与其他扩展能力取决于服务端实现。

Bravais 与 Lattice

Bravais：浏览整个资料库

歌单、专辑、文件夹与歌手铺在可拖动的海报墙上。拖动空白区域平移，点击集合浏览曲目，点击歌曲展开大卡，再点击播放。想切回经典布局，可到「设置 → 界面 → 主页与歌单 → 资料库界面」选择「网格」。

Lattice：浏览当前播放队列

按 Ctrl / Cmd + B 进入或退出 Lattice。每张海报对应队列中的一首歌；点击展开，按 Enter 可播放。它展示当前队列，增删或排序请通过队列管理进行。

在「设置 → 界面 → 播放页 → 播放后进入的视图」可选择可视化播放页、Lattice 或留在原处。私人 FM 期间 Lattice 不可用。

常见问题与排查