Folia 可以扫描本机音乐文件，在浏览器或桌面端建立本地曲库，并在不上传音频文件内容的前提下管理歌曲、文件夹、艺术家、专辑、歌单、歌词和封面。
本文说明当前 Grid3D / 海报墙 本地音乐库的使用方式。旧版列表式本地音乐页面已经进入弃用流程，不再作为新功能入口。
当前支持以下音频格式：
- MP3
- FLAC
- M4A
- WAV
- OGG
- Opus
- AAC
导入时，Folia 会读取音频文件中的标题、艺术家、专辑、曲号、碟号、时长、ReplayGain、内嵌歌词和内嵌封面等信息。缺少标题或艺术家标签时，会尝试从文件名中提取基础信息。
Folia 会识别与音频文件位于同一目录、基础文件名相同的歌词文件：
.lrc.vtt.ttml.qrc.yrc.krc
支持 track.lrc 和 track.mp3.lrc 两种命名方式。翻译歌词可以使用 track.t.lrc 或 track.t.vtt。
同一首歌存在多个歌词文件时，优先顺序为 LRC、VTT、TTML、QRC、YRC、KRC。播放时仍可在右侧面板的“本地”选项卡中切换本地、内嵌或在线歌词。
每个目录可以使用以下文件作为文件夹封面：
cover.pngcover.jpgcover.jpeg
文件夹封面的优先级高于音频文件的内嵌封面。
- 进入首页的本地音乐区域。
- 选择“导入文件夹”。
- 在系统目录选择器中选择音乐库或其中一个目录。
- 等待扫描和后台元数据读取完成。
Folia 会递归扫描所选目录及其子目录。文件夹结构用于浏览和限定管理范围，但不会因为歌曲位于同一目录，就自动把它们视为同一艺术家或专辑。
在 Web 版中，文件夹导入依赖浏览器的 File System Access API。如果页面提示当前浏览器不支持文件夹导入，请改用支持该能力的浏览器或桌面版。
打开真实本地文件夹后，可以在 海报墙 的集合操作中选择“重新导入”。在“全部歌曲”中执行该操作时，会重新扫描所有已导入的根目录。
重新导入采用增量扫描：
- 新文件会加入曲库。
- 已修改的音频、歌词或封面文件会重新读取。
- 已从磁盘移除的文件会从曲库索引中移除。
- 未变化的歌曲会复用现有数据。
- 已应用的在线匹配和手工整理关系不会因为普通重扫而被直接覆盖。
重复选择已经导入的同一目录时，Folia 会更新原有目录。
浏览器或操作系统可能在重启后收回目录读取权限。出现“需要恢复本地音乐访问权限”时，按照界面提示重新授权即可。如果原目录已经移动、改名或无法访问，可以重新导入对应文件夹。
本地音乐库提供几种不同的组织方式：
- 文件夹：反映音乐文件在磁盘上的目录结构。
- 专辑：根据导入元数据、在线匹配结果和后续手工调整建立。
- 艺术家：根据歌曲的艺术家信息建立，可包含多个艺术家关系。
- 歌单：由用户在 Folia 中创建，不改变磁盘目录。
Folia 会为艺术家和专辑建立稳定的本地实体，并单独保存歌曲与实体之间的关系。因此，修改展示名称不会直接改写音频文件标签，也不会改变磁盘文件。
进入一个真实本地文件夹后，可以在 海报墙 的集合操作中选择“整理歌曲信息”。
“批量自动匹配”会为选中的歌曲搜索在线元数据和封面：
- 优先搜索网易云。
- 当网易云没有标题相符的候选时，回退到 QQ 音乐。
- 当网易云和 QQ 音乐均没有标题相符的候选时，继续回退到酷狗音乐。
- 根据标题、艺术家、专辑和时长评估候选结果。
- 自动应用合适的标题、艺术家、专辑和封面。
自动匹配可能存在误差。开始前可以取消不希望处理的歌曲，运行过程中也可以取消任务。
手工修改、手动匹配或拆分得到的艺术家/专辑关系会受到保护。自动匹配准备替换这些关系时，界面会要求确认。
对单首歌曲执行手动匹配时，可以：
- 修改检索文字。
- 在网易云、QQ 音乐与酷狗音乐之间切换。
- 查看标题和时长是否匹配。
- 预览应用后的标题、艺术家、专辑与封面。
- 分别决定是否使用在线元数据和在线封面。
在线元数据中的标题、艺术家和专辑作为一组共同应用，不能在同一次候选中只替换其中一个字段。艺术家或专辑关系需要更细的调整时，请使用后文的实体编辑功能。
在线元数据与在线封面彼此独立。例如，可以恢复本地标题、艺术家和专辑，同时继续使用手动选择的在线封面。
选择“不使用在线数据”或“使用本地信息”后，Folia 会：
- 恢复首次导入时保存的标题、艺术家和专辑快照。
- 恢复内嵌或文件夹封面。
- 恢复自动歌词选择。
- 标记该歌曲，使后续批量自动匹配跳过它。
以后再次手动应用在线元数据或封面时，可以解除这一自动跳过状态。
“整理歌曲信息”主要处理标题、艺术家、专辑和封面，不会在批量匹配时立即下载并固定歌词。
播放本地歌曲时，歌词仍按歌词匹配策略选择。已选中的在线歌曲 ID 和元数据会作为更可靠的检索起点，但不会改变“最佳逐字歌词”对不同歌词来源的质量判断。
需要指定歌词时，在播放界面右侧面板打开“本地”选项卡。这里可以：
- 使用同目录歌词。
- 使用音频文件内嵌歌词。
- 搜索并保存在线歌词。
- 导入单独的歌词文件。
- 恢复自动歌词选择。
- 临时调整当前播放的歌词时间轴偏移。
打开本地艺术家或专辑集合后，在 海报墙 的集合操作中选择“艺术家信息”或“专辑信息”。
修改展示名称只影响 Folia 中的显示结果。原始音频标签、文件名和在线来源信息会作为名称提示或别名保留。
当同一艺术家或专辑因为命名差异被识别成多个实体时，可以搜索目标并执行合并。
合并后：
- 来源实体的成员会迁移到目标实体。
- 来源实体的名称会保留为别名。
- 已有歌曲关系会指向合并后的目标实体。
合并前请确认方向。需要时可以使用界面中的“切换合并方向”改变保留哪个实体。
当一个艺术家或专辑错误包含了不属于它的歌曲时，可以：
- 搜索并选择需要移出的成员歌曲。
- 输入名称创建新的艺术家或专辑；或者
- 搜索并选择一个已有实体作为目标。
拆分艺术家时可以添加多个新建或已有歌手，并明确选择“追加歌手”或“替换全部歌手”。追加会保留歌曲当前的所有歌手关系；替换则让所选歌曲最终只关联到本次选择的目标歌手。专辑拆分仍只支持一个目标专辑。
拆分只移动选中的歌曲，不会删除原实体。手工拆分得到的关系会被标记为人工整理结果，避免被后续普通重扫直接覆盖。
本地歌曲可以加入 Folia 内部歌单，也可以把当前队列保存为歌单。
歌单只保存歌曲引用，不复制或移动磁盘文件。从曲库删除歌曲或整个文件夹时，对应歌曲也会从本地歌单中移除。
从本地音乐库删除文件夹时，Folia 会移除该目录及其子目录中的曲库记录，但不会删除或修改磁盘上的音乐文件。
删除后如果再次导入同一目录，Folia 会根据当前磁盘内容重新建立索引。
本地曲库索引、导入快照、艺术家/专辑实体和歌曲关系由 Dexie 管理并保存在本地数据库中。音频文件内容不会上传到 Folia 服务。
在线封面的存储位置因运行环境而异：
- Web 版写入 OPFS。
- Electron 桌面版写入应用文件缓存。
数据库只保存在线地址和轻量缓存描述。封面缓存属于可重建数据；缓存缺失或损坏时，会依次尝试在线地址、有效的内嵌封面或占位图，不影响歌曲和实体信息。
当前浏览器可能不支持 File System Access API。请改用支持目录选择的浏览器或 Folia 桌面版。
先根据界面提示恢复目录访问权限。如果目录已经移动或改名，请重新导入该目录。
进入对应文件夹的“整理歌曲信息”，修改检索文字并切换来源后手动选择候选；也可以选择“使用本地信息”，恢复导入快照并跳过后续自动匹配。
打开对应艺术家或专辑集合，进入实体信息面板，选择错误成员并拆分到新实体或已有实体。
不会。删除操作只影响 Folia 的本地曲库记录，不会删除磁盘文件。