设置说明

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

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

设置入口

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

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

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

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

选项 下当前分为通用、视觉设置、播放控制、集成设置、存储与缓存、桌面端设置、常驻命令和实验室几组。

通用

• 界面语言：可手动指定为简体中文、English、Indonesian，或跟随浏览器 / 系统语言。
• 顶部胶囊入口：控制首页顶部是否显示歌单、电台、专辑、本地几个入口，用不到的可以关掉。

视觉设置

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

主题与配色

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

歌词与播放页

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

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

首页布局与风格

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

备份与导入

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

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

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

播放控制

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

播放队列

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

音频增益

• ReplayGain 模式：检测到增益数据时，按单曲或专辑 ReplayGain 统一播放响度，避免歌单里忽大忽小。

歌词

• 自动使用最佳歌词：自动检索网易云、AMLLDB、QQ 和酷狗歌词，若存在完美匹配的逐字歌词则自动优先采用。
• 本地歌曲歌词优先级：本地歌曲同时存在在线匹配歌词时，选择优先使用本地歌词还是在线优先。手动指定的歌词来源不受影响。
• 歌词匹配优先级：多个歌词源都有满足匹配度的结果时，优先采用哪一个来源，可选 netease、amll、qq、kugou。
• 全局时间偏移：为本设备的所有歌曲整体平移歌词时间轴，用来补偿蓝牙耳机等输出延迟。点开后可以在实时预览中微调。

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

全局偏移和单曲偏移的区别

全局时间偏移作用于这台设备上的所有歌曲，适合补偿固定的输出延迟；某一首歌自身对不齐时，仍然应该用歌词面板里的单曲偏移。

播放设备

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

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

音频效果器

音频效果器不在设置页里，而是从右侧面板控制标签的音量行按钮打开，也可以在命令面板里搜索音频效果器或 eq。它包含两部分：

• 频段增益：十段均衡器，内置水平、Lo-Fi、收音机、大厅、人声、低音增强几个预设，另有两个自定义栏位。
• 效果链：在频段处理之后串接的后处理效果，包括低频截止、高频截止、饱和失真、比特降质、抖晃、黑胶噪声、立体声宽度、空间混响、动态压缩。

命令面板里也可以直接切换预设，或用水平一键清空均衡器和所有效果。窗口可以按 Esc 关闭。

集成设置

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

Discord Rich Presence

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

OBS 浏览器源

开启后会提供一个本机 URL 和 Token，供 OBS 以浏览器源方式接入 Folia 的歌词动画，页面里还会显示当前连接数。

它的特点是：

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

可以随时复制 OBS 地址或重新生成 Token。

歌词接口

启用后，Folia 会在固定端口 32109 上提供一个无需鉴权的本机接口，外部程序可以读取当前歌曲的精简歌词数据。

• 只监听 127.0.0.1，局域网和公网访问不到
• 设置页会显示接口地址和运行中 / 不可用状态；端口被占用时会显示不可用
• 也可以从命令面板切换

omarchy / quickshell 用户可以直接用现成的顶栏歌词插件 lia.lines。要自己对接的话，字段说明见歌词接口文档。

舞台模式与 Now Playing

• 舞台模式（Stage API）：桌面版暴露本机 HTTP 接口，供外部程序读取或推送播放、歌词与点歌信息。Web 版开启后首页会出现舞台入口。
• Now Playing：固定连接 ws://localhost:9863/api/ws/lyric，需要先在本机启动 now-playing 服务，之后可把其他播放器的进度、歌词和暂停状态同步进 Folia。
• Nexus PlayerCap：填写 PlayerCap 地址（留空默认 localhost:8765），可以选择跟随的播放器、时间轴基准（play_time 提前显示 / timestamp 原始时间轴），以及是否忽略播放器的清除事件。

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

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

需要完整接口说明时看 Stage API。

Navidrome

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

存储与缓存

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

可查看的缓存分类

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

媒体缓存

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

同步服务

这一页也负责多端同步的客户端配置：

• 启用同步服务：通过你自己的 Cloudflare D1 Worker 或自托管服务同步外观设置与 AI 主题。
• Sync Server 地址与 Bearer Token：Token 就是服务端配置的 SYNC_TOKEN，填完可以先点测试。
• 同步视觉设置：决定是否把视觉配置一并纳入同步范围。
• 同步 AI 主题：手动触发一次主题同步。
• 导出 zip / 导入 zip：整库备份与迁移。导入会覆盖本地同步缓存，已启用同步服务时还会推送到服务端。

服务端怎么部署见部署同步服务。

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

常驻命令

• 快捷命令：最多选择三个命令固定显示在命令面板下方，适合把最常用的操作放在手边。

桌面端设置

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

窗口行为

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

更新检查

• 启用更新检查：启动时检查 GitHub Releases。
• 更新通道：选择这台设备跟随的发布通道，可选 Realeco · 正式版、Limo · Nightly、Cielo · Canary；自行构建的版本会显示为内部构建且不支持自动更新。通道差异见桌面版功能。
• 启用自动更新：发现新版本后自动下载。自动更新需要能直连 GitHub。
• 下载更新 / 重启安装：在支持的平台上直接完成更新流程。macOS 与 Linux 目前仍需下载安装包手动覆盖。
• 国内下载：网络不方便访问 GitHub 时改走国内下载入口。

桌面 AI 配置

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

• AI 供应商
• Gemini 密钥
• OpenAI 接口链接
• 模型
• 密钥
• 温度：范围 0–2，留空时使用默认值 0.7
• 是否为 AI 请求使用系统代理

如果你使用兼容 OpenAI 的服务，很多时候模型名需要手动填写，例如 deepseek-v4-flash。部分模型对温度有硬性要求，填错会直接报错。

实验室

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

性能与背景

• 静态模式：关闭几何背景以节省资源，不影响歌词文本效果。
• 关闭主页动态背景：主页不再继续播放背景动画，可降低 GPU 占用。
• 实验性动画帧率限制：限制 requestAnimationFrame 驱动的动画帧率，适合性能排查，但可能带来兼容问题。

播放页界面

• 隐藏底部控制条
• 隐藏底部字幕层
• 隐藏右侧按钮：隐藏后仍可用 P 键开关右侧面板
• 显示信息卡片关闭按钮：歌曲信息卡片打开后，右下角出现浮动关闭按钮
• 始终显示播放页左上角返回按钮
• 始终显示切歌按钮：让进度条标题两侧的上一首 / 下一首箭头常驻，不再需要悬停才浮出

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

窗口与工具

• 始终显示标题栏控制按钮：让最小化、最大化和关闭按钮保持显示，但不显示整条标题栏。
• 播放时阻止休眠：仅桌面端生效，播放期间保持显示器唤醒，暂停或停止后恢复系统原有行为。
• 开启播放页原生毛玻璃背景：改用系统原生毛玻璃，此时主题、图片和 Monet 等背景不再显示。仅在非透明模式和桌面端生效，性能开销更大。
• 语音输入时暂停播放：检测到系统语音输入或其他应用占用麦克风时自动暂停，结束后恢复。仅 Windows 桌面端生效。

歌词过滤正则

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

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

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

建议的起手顺序

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

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