设置说明

Folia 的设置中心把播放行为、视觉风格、外部集成、缓存、桌面特性和实验性选项拆成了几组独立页面。实际使用时，建议先把常用项配顺，再慢慢深入细调。

如果你现在最需要的是“这个开关到底在界面的哪里”，建议先配合阅读 功能地图与 GUI 位置。

设置入口

通常可以从主页或播放页打开设置。桌面版和 Web 版共用大部分设置结构，但有些能力只会在桌面端出现，例如：

• 更新检查与自动更新
• 托盘与任务栏行为
• Stage API 本机服务
• OBS Browser Source
• 系统级 AI 代理与缓存目录

设置弹窗本身还有两个一级标签：

• 帮助：快捷键、用户指引、版本信息、AI 求助提示词
• 选项：真正的设置中心

视觉设置

这一页主要影响播放页观感、主题风格和首页布局。

主题与配色

• 默认主题：回到项目内置的明暗主题。
• AI 主题：根据歌词或歌曲标题生成双主题配色。
• 自定义主题：手动保存一套自己的主题颜色。
• 优先使用自定义主题：切歌后仍尽量保留你保存的自定义主题。
• 主题自动切换：当某首歌已经生成过 AI 主题时，切歌时自动恢复它。

歌词与播放页

• 歌词动画：切换不同 visualizer 模式，例如 流光、心象、云阶、浮名、群唱、倾诉、莫奈。
• 透明播放页背景：把播放页切换成透明窗口，更适合 OBS 抠像或桌面叠加。
• 自动隐藏控制栏：在播放页里自动收起进度条和右侧按钮，减少干扰。
• 歌词动画样式：进入更细的 visualizer 调参面板，调节不同模式的布局、镜头、背景与文字表现。

如果你想逐项了解这些参数的作用，可以查看 歌词动画参数说明。

首页布局与风格

• 经典：旧版首页布局，更接近传统入口页。
• 万象：新版透明桌面风格首页，更强调沉浸感和 3D 网格展示。
• 3D 网格卡片样式：在万象布局下，可选 纯图片封面 或 拍立得卡片。

备份与导入

视觉设置支持导出和导入：

• 标准 JSON
• folia-theme 文本配置码

适合备份主题、跨设备同步，或把某一套 visualizer 调参分享给别人。

播放控制

这一页更偏向“播放器行为”。

播放队列

• 加入队列默认位置：可选 追加到末尾 或 追加到下一首。
• 如果你经常边听边插歌，建议改成 追加到下一首。

歌词来源

• 更多歌词源：启用备选歌词源，如 QQ 音乐、酷狗音乐。
• 自动使用最佳歌词：自动比较多个来源，优先采用更完整、更适合逐字展示的版本。

这部分会直接影响本地音乐、Navidrome 和部分在线歌曲的歌词效果。

播放设备

• 当前播放声卡：切换当前播放器使用的音频输出设备。
• 系统默认：跟随操作系统当前默认输出。
• 刷新：重新枚举可切换设备。

桌面版优先支持这一能力；浏览器环境只有在宿主支持 setSinkId 时才能切换。

集成设置

这一页负责和外部程序打通。

Discord Rich Presence

开启后，桌面版会把当前播放状态显示到 Discord 桌面客户端。

OBS Browser Source

开启后会提供一个本机 URL 和 Token，供 OBS 以浏览器源方式接入 Folia 的歌词动画。

它的特点是：

• 只负责渲染画面，不负责音频
• 接入后主窗口会停掉较重的可视化渲染，降低重复负担
• 更适合直播和录制场景

Stage API / Now Playing

• Stage API：桌面版暴露本机 HTTP 接口，供外部程序读取或推送播放、歌词与点歌信息。
• Now Playing：连接本机的 Now Playing 服务，把其他播放器的进度、歌词和暂停状态同步进 Folia。

开启 Stage 相关能力后，设置页里会显示：

• 本机地址
• Bearer Token
• 模式来源
• 清空状态或重新生成 Token 的操作

Navidrome

这一页也负责保存 Navidrome 的服务地址、用户名和密码，并提供连接测试。

存储与缓存

这一页适合排查空间占用或清理数据。

可查看的缓存分类

• 播放列表数据
• 歌词缓存
• 封面缓存
• 媒体文件缓存

媒体缓存

• 缓存歌曲：播放后把音频缓存到本地，方便离线再次播放。
• 缓存目录：桌面版可指定大体积缓存文件写入的位置。
• 已缓存歌曲数：方便判断缓存是否在持续增长。

如果你主要把 Folia 当播放器而不是展示工具，这一页会很实用。

桌面端设置

这一页只在桌面版真正有意义。

窗口行为

• 最小化到托盘：点最小化时不退出，而是收进系统托盘。
• 启动后直接进入播放页：打开应用后直接进入大屏歌词界面。
• 隐藏任务栏图标：只保留托盘图标，适合常驻后台或桌面陪伴式使用。

更新检查

• 启用更新检查：启动时检查 GitHub Releases。
• 启用自动更新：发现新版本后自动下载。
• 下载更新 / 重启安装：在支持的平台上直接完成更新流程。
• CN Download：网络不方便访问 GitHub 时可改走国内下载入口。

桌面 AI 配置

桌面版可直接在应用里保存：

• Gemini API Key
• OpenAI API Key
• OpenAI API URL
• OpenAI Model
• 是否对 AI 请求强制使用系统代理

如果你使用兼容 OpenAI 的服务，很多时候模型名需要手动填写，例如 deepseek-v4-flash。

实验性设置

这一页放的是对体验影响比较大、但不一定适合所有人的选项。

性能与动画

• Static Mode：关闭几何背景，保留歌词文本动画。
• 关闭主页动态背景：减少首页 GPU 占用。
• 动画帧率限制：限制 requestAnimationFrame 驱动的动画帧率，适合性能排查，但可能带来兼容问题。

播放页 UI 精简

• 隐藏底部控制条
• 隐藏翻译字幕
• 隐藏右侧按钮
• 保留面板关闭按钮
• 开启播放页原生毛玻璃背景

这些选项特别适合录屏、投屏、桌面叠加或做装饰性播放窗口。

歌词过滤正则

这里可以写正则表达式来过滤不想显示的歌词内容，例如：

• 制作人员信息
• 冗余标注
• 某些固定格式的提示语

如果你对歌词展示纯净度要求很高，这个能力很好用，但建议先少量测试再长期启用。

建议的起手顺序

如果你是第一次接触 Folia，推荐按这个顺序设置：

1. 在 快速开始 完成安装或部署。
2. 在视觉设置里选一个喜欢的歌词动画和首页布局。
3. 在播放控制里开启适合自己的歌词源和队列行为。
4. 桌面用户再决定是否启用托盘、OBS、Stage API 或 Now Playing。
5. 最后再进入实验性设置做录屏或性能相关微调。