设置说明

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

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

设置入口

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

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

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

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

选项 下按四组排列，左侧导航默认展开：

分组	包含的页面
外观	视觉设置、界面设置
控制	播放控制、交互控制
连接与数据	连接与集成、存储与同步
系统	桌面端设置（仅桌面版）、实验室、开发者

每个页面下还有若干小节，左侧导航会把小节一并列出。命令面板里有一批命令可以直接跳到具体小节，不用自己找——搜索小节名即可，例如网格卡片样式、队列行为、Navidrome 服务器、媒体缓存。

界面设置

• 语言：可手动指定为简体中文、English、Indonesian，或跟随浏览器 / 系统语言。
• 顶部胶囊入口：控制首页顶部是否显示歌单、电台、专辑、本地几个入口，用不到的可以关掉。
• 播放后进入的视图：点击播放后默认打开哪个视图，可选可视化（播放页）或 Lattice（队列拼贴）。首次使用时 Folia 会主动问一次，之后随时可以回来改。由于 Lattice 不支持私人 FM，启动私人 FM 时仍会进入标准播放器。详见 Lattice。
• 底部界面 > 调整底部控制条位置：统一移动底部控制、歌曲卡片、字幕与面板按钮的基线。
• 底部界面 > 进度条按钮槽位：自定义进度条右侧两个按钮，默认是循环模式和歌词时间轴，也可换成上一首、下一首、打乱、收藏、队列、音量、歌曲墙（Lattice）或睡眠定时。这两个槽位同时决定 Lattice 展开卡片上中间两个按钮的功能。
• 快捷命令：最多选三个命令固定显示在命令面板底部。

视觉设置

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

主题与配色

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

歌词与播放页

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

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

首页布局与风格

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

网格卡片

控制首页网格卡片的绘制方式，命令面板搜索网格卡片外观可以直接打开一个带滑块的调节界面。

• 全画幅封面：让封面铺满整张卡片，歌名和歌手改为叠在封面上的渐变遮罩里显示，做法和队列拼贴一致。
• 正方形卡片：只在全画幅封面开启时可用。让卡片高宽相等，方形封面完整显示不再被上下裁掉；卡片面积不变，变矮的同时会变宽。
• 卡片最小尺寸：远离中心的卡片最多缩小到多少。调高外围更好辨认，调低纵深感更强。
• 卡片最小透明度：远离中心的卡片最多淡到多少。
• 恢复默认衰减：把上面两个滑块还原。

队列拼贴设置

Lattice 的外观开关，完整说明见 Lattice（队列拼贴）。

• 边缘暗角：在队列拼贴页面四周加一层淡暗角。
• 海报聚焦叠色：给普通海报加颜色叠层，突出正在播放、选中或悬停的海报。可强制使用自定义颜色，并调节叠层颜色与叠色强度。

歌曲信息卡片

播放器和播放队列左下角的“正在播放”卡片：

• 显示方式：限时显示 / 常驻显示 / 不显示。
• 显示时长：限时显示时的停留时间。
• 在首页显示：关闭时只在播放器和播放队列出现。

备份与导入

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

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

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

播放控制

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

播放队列

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

听歌打卡

• 上报播放记录（仅网易云）：在线网易云歌曲真实播放满 30 秒后，向你的网易云账号上报一次听歌记录。需要先登录网易云账号。

本地文件、云盘歌曲和其他音乐平台一律不上报。这个功能会写入你的真实账号、用于网易云的推荐计算，有一定风险，默认关闭，请自行判断是否开启。

Folia 智能过渡

• Folia Crossfade：使用固定的淡出淡入。
• Folia Automix：分析相邻歌曲并自动选择混音过渡；桌面版可下载分析模型（约 249 MB）以获得完全体的节拍对齐和音轨分离能力，未安装时进入兼容模式。
• 表现模式：提供更激进的过渡，需要桌面端和音轨分离模型。
• 过渡最长时长：只在 Folia Crossfade 模式下出现，决定固定淡化的时长上限；Automix 自己决定每次的过渡长度。
• 过渡动画：可用屏幕圆环或歌曲卡片描边显示过渡进度；短于 5 秒的过渡不会显示动画。

在线歌曲要被 Automix 提前分析，需要开启歌曲缓存。完整说明见 Folia 智能过渡。

音频增益

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

歌词

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

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

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

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

歌词过滤

从 v0.7.2 起，歌词过滤从实验室移到了这里（播放控制 > 歌词 > 歌词过滤，命令面板搜索歌词过滤可直达）。它分两部分：

逐行过滤

• 启用逐行过滤：开关。
• 正则表达式：按整首歌的正文歌词逐行匹配，命中的整行会被删除。
• 面板里可以直接预览当前歌曲的过滤结果，并显示已过滤 N / 总计 M。
• 关闭开关不会清空你写好的正则，下次开启时还在原处。

开头制作人员信息

识别歌词开头的署名块（作词、作曲、编曲这一段），处理方式三选一：

处理方式	行为
始终显示	完全按歌词文件里的时间轴显示
按前奏长度	前奏够长就显示（必要时摊开到整段前奏），不够就整块隐藏
始终隐藏	总是去掉开头的署名块

配套选项：

• 每行最少停留：判断“够不够长”的单行最低持续时间。
• 吸收相邻行：关闭 / 向前吸收 / 前后吸收。开启后，署名块相邻、单行耗时短于上面阈值的行会一起并入块处理。
• 自定义识别规则：留空使用内置署名词表；填写后整体替换内置规则，但仍然只作用于开头那一块。
• 面板会实时显示当前歌曲的判定，写明识别到几条署名、前奏多少秒、完整显示需要多少秒。

这两组命令在命令面板里也有：开头制作人员信息、开头制作人员信息：吸收相邻行，按一次轮换一档。

播放设备

• 自动转换无法播放的音频（仅桌面端）：遇到 Chromium 解不了的本地或 Navidrome 歌曲时，用内置 FFmpeg 转换后原位恢复播放，不修改原文件。转换结果进缓存目录，Automix 的节拍分析也会走转换后的音频。
• 当前播放声卡：切换当前播放器使用的音频输出设备。
• 系统默认：跟随操作系统当前默认输出。
• 刷新：重新枚举可切换设备。

桌面版优先支持这一能力；浏览器环境只有在宿主支持 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 / OpenSubsonic

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

Folia 走的是标准的 Subsonic / OpenSubsonic API，所以能连的不只是 Navidrome。连接成功后，这里还会显示服务端类型、版本、OpenSubsonic 是否可用、支持哪些扩展，以及这个账号能访问哪些音乐库——排查问题时先看这块。完整说明见 Navidrome / OpenSubsonic。

存储与同步

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

可查看的缓存分类

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

媒体缓存

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

本地文件夹监视

• 自动扫描已导入文件夹：监视你导入过的本地文件夹，文件增删改时自动做一次增量扫描，不用手动重新导入。默认关闭。
• 下方会逐个列出已导入的文件夹和它们的监视状态：正在监视、只监视这一层、正在扫描、监视失败、访问权限已失效，以及上次自动扫描的时间。
• 重新检查文件夹：立刻跑一次检查。

部分环境（受浏览器 / 系统 API 限制）只能监视文件夹本层，子文件夹的变化不会被发现，状态里会写明。访问权限失效时需要重新导入这个文件夹。

同步服务

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

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

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

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

交互控制

• 海报墙操作按钮：设置右下角按钮向左滑动时打开过滤搜索还是命令窗口；点击仍然打开歌曲列表。这个按钮在 Lattice 里也在，向左滑动同样打开命令面板。
• 海报墙上用 S 键打开命令窗口：默认关闭，此时首页网格上的任意单字符（含 S）都是筛选输入。打开后 S 改为打开命令窗口，其余字符仍进筛选框。这个开关只影响首页网格——播放页和 Lattice 里 S 本来就直接可用。
• 自定义快捷键：把一个全局命令绑定到 Alt + A–Z 中的一个字母。Alt 那一半是固定的；候选里只列出在任何界面都能执行的命令，与已占用按键冲突时会被拒绝。

固定在命令面板底部的快捷命令（最多三个）在界面设置里配置。

命令搜索、队列批量语法、执行模式等完整说明见命令面板用户指南。

桌面端设置

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

窗口行为

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

壁纸模式

把应用窗口沉到桌面最底层，作为常驻的歌词壁纸。Windows 和 macOS 都支持，无需重启应用即可原地切换，也可以从系统托盘和命令面板切换。

• 该模式下键盘不可用，鼠标事件由 Folia 转发。
• macOS 需要先在系统设置 → 隐私与安全性 → 输入监控中勾选 Folia，然后重启应用，否则无法转发鼠标。
• macOS 可选壁纸模式下自动隐藏 Dock 栏（仅底部 Dock 生效）。
• 壁纸模式下，窗口级的开关（全屏、置顶）没有意义，会自动停用。

配合界面设置 > 底部界面 > 调整底部控制条位置可以把进度条挪到合适的高度。

更新检查

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

平台差异：Windows 支持自动更新；macOS 与 Linux 会检查新版本并提示，但受平台限制不做自动更新，需要手动下载完整安装包覆盖，或用包管理器（Arch 用户可走 AUR）升级。

Folia 崩溃时会保存一份诊断日志，并可以从这里打开日志所在目录。Windows 卸载程序还可以选择是否一并清除用户数据。

桌面 AI 配置

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

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

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

实验室

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

性能与背景

• 静态模式：关闭几何背景以节省资源，不影响歌词文本效果。
• 关闭主页动态背景：主页不再继续播放背景动画，可降低 GPU 占用。
• 实验性动画帧率限制：限制 requestAnimationFrame 驱动的动画帧率，适合性能排查，但可能带来兼容问题。
• 修复 Linux 歌词动画卡死：改变部分歌词动画的发光绘制方式，修复 Linux 下长时间播放后偶发的卡死问题。Linux 下默认开启，其他平台默认关闭。详见 Chromium FD 耗尽问题。

播放页界面

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

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

窗口与工具

• 模组系统：仅桌面端生效。开启后模组命令与模组管理面板才会出现，加载器也才会扫描并加载模组；关闭时不加载任何模组代码。模组以应用的完整权限运行，启用单个模组时还需逐一确认。详见 模组系统（Folium 1.3）。
• 进入应用后自动播放：桌面端和已安装的 PWA 可直接续播上次歌曲；普通浏览器标签页可能受自动播放策略限制，需要先点击页面。
• 始终显示标题栏控制按钮：让最小化、最大化和关闭按钮保持显示，但不显示整条标题栏。
• 播放时阻止休眠：仅桌面端生效，播放期间保持显示器唤醒，暂停或停止后恢复系统原有行为。
• 开启播放页原生毛玻璃背景：改用系统原生毛玻璃，此时主题、图片和 Monet 等背景不再显示。仅在非透明模式和桌面端生效，性能开销更大。
• 语音输入时暂停播放：检测到系统语音输入或其他应用占用麦克风时自动暂停，结束后恢复。仅 Windows 桌面端生效。

建议的起手顺序

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

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