# Folia 本地音乐库管理

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。播放时仍可在右侧面板的“本地”选项卡中切换本地、内嵌或在线歌词。

### 文件夹封面

每个目录可以使用以下文件作为文件夹封面：

1. `cover.png`
2. `cover.jpg`
3. `cover.jpeg`

文件夹封面的优先级高于音频文件的内嵌封面。

## 导入音乐文件夹

1. 进入首页的本地音乐区域。
2. 选择“导入文件夹”。
3. 在系统目录选择器中选择音乐库或其中一个目录。
4. 等待扫描和后台元数据读取完成。

Folia 会递归扫描所选目录及其子目录。文件夹结构用于浏览和限定管理范围，但不会因为歌曲位于同一目录，就自动把它们视为同一艺术家或专辑。

在 Web 版中，文件夹导入依赖浏览器的 File System Access API。如果页面提示当前浏览器不支持文件夹导入，请改用支持该能力的浏览器或桌面版。

## 重新导入与恢复访问权限

打开真实本地文件夹后，可以在 海报墙 的集合操作中选择“重新导入”。在“全部歌曲”中执行该操作时，会重新扫描所有已导入的根目录。

重新导入采用增量扫描：

- 新文件会加入曲库。
- 已修改的音频、歌词或封面文件会重新读取。
- 已从磁盘移除的文件会从曲库索引中移除。
- 未变化的歌曲会复用现有数据。
- 已应用的在线匹配和手工整理关系不会因为普通重扫而被直接覆盖。

重复选择已经导入的同一目录时，Folia 会更新原有目录。

浏览器或操作系统可能在重启后收回目录读取权限。出现“需要恢复本地音乐访问权限”时，按照界面提示重新授权即可。如果原目录已经移动、改名或无法访问，可以重新导入对应文件夹。

## 文件夹、专辑与艺术家

本地音乐库提供几种不同的组织方式：

- 文件夹：反映音乐文件在磁盘上的目录结构。
- 专辑：根据导入元数据、在线匹配结果和后续手工调整建立。
- 艺术家：根据歌曲的艺术家信息建立，可包含多个艺术家关系。
- 歌单：由用户在 Folia 中创建，不改变磁盘目录。

Folia 会为艺术家和专辑建立稳定的本地实体，并单独保存歌曲与实体之间的关系。因此，修改展示名称不会直接改写音频文件标签，也不会改变磁盘文件。

## 整理歌曲信息

进入一个真实本地文件夹后，可以在 海报墙 的集合操作中选择“整理歌曲信息”。

### 批量自动匹配

“批量自动匹配”会为选中的歌曲搜索在线元数据和封面：

1. 优先搜索网易云。
2. 当网易云没有标题相符的候选时，回退到 QQ 音乐。
3. 当网易云和 QQ 音乐均没有标题相符的候选时，继续回退到酷狗音乐。
3. 根据标题、艺术家、专辑和时长评估候选结果。
4. 自动应用合适的标题、艺术家、专辑和封面。

自动匹配可能存在误差。开始前可以取消不希望处理的歌曲，运行过程中也可以取消任务。

手工修改、手动匹配或拆分得到的艺术家/专辑关系会受到保护。自动匹配准备替换这些关系时，界面会要求确认。

### 手动在线匹配

对单首歌曲执行手动匹配时，可以：

- 修改检索文字。
- 在网易云、QQ 音乐与酷狗音乐之间切换。
- 查看标题和时长是否匹配。
- 预览应用后的标题、艺术家、专辑与封面。
- 分别决定是否使用在线元数据和在线封面。

在线元数据中的标题、艺术家和专辑作为一组共同应用，不能在同一次候选中只替换其中一个字段。艺术家或专辑关系需要更细的调整时，请使用后文的实体编辑功能。

在线元数据与在线封面彼此独立。例如，可以恢复本地标题、艺术家和专辑，同时继续使用手动选择的在线封面。

### 使用本地信息

选择“不使用在线数据”或“使用本地信息”后，Folia 会：

- 恢复首次导入时保存的标题、艺术家和专辑快照。
- 恢复内嵌或文件夹封面。
- 恢复自动歌词选择。
- 标记该歌曲，使后续批量自动匹配跳过它。

以后再次手动应用在线元数据或封面时，可以解除这一自动跳过状态。

## 歌词匹配与歌曲信息匹配的区别

“整理歌曲信息”主要处理标题、艺术家、专辑和封面，不会在批量匹配时立即下载并固定歌词。

播放本地歌曲时，歌词仍按歌词匹配策略选择。已选中的在线歌曲 ID 和元数据会作为更可靠的检索起点，但不会改变“最佳逐字歌词”对不同歌词来源的质量判断。

需要指定歌词时，在播放界面右侧面板打开“本地”选项卡。这里可以：

- 使用同目录歌词。
- 使用音频文件内嵌歌词。
- 搜索并保存在线歌词。
- 导入单独的歌词文件。
- 恢复自动歌词选择。
- 临时调整当前播放的歌词时间轴偏移。

## 编辑艺术家与专辑实体

打开本地艺术家或专辑集合后，在 海报墙 的集合操作中选择“艺术家信息”或“专辑信息”。

### 修改展示名称

修改展示名称只影响 Folia 中的显示结果。原始音频标签、文件名和在线来源信息会作为名称提示或别名保留。

### 合并重复实体

当同一艺术家或专辑因为命名差异被识别成多个实体时，可以搜索目标并执行合并。

合并后：

- 来源实体的成员会迁移到目标实体。
- 来源实体的名称会保留为别名。
- 已有歌曲关系会指向合并后的目标实体。

合并前请确认方向。需要时可以使用界面中的“切换合并方向”改变保留哪个实体。

### 拆分成员歌曲

当一个艺术家或专辑错误包含了不属于它的歌曲时，可以：

1. 搜索并选择需要移出的成员歌曲。
2. 输入名称创建新的艺术家或专辑；或者
3. 搜索并选择一个已有实体作为目标。

拆分艺术家时可以添加多个新建或已有歌手，并明确选择“追加歌手”或“替换全部歌手”。追加会保留歌曲当前的所有歌手关系；替换则让所选歌曲最终只关联到本次选择的目标歌手。专辑拆分仍只支持一个目标专辑。

拆分只移动选中的歌曲，不会删除原实体。手工拆分得到的关系会被标记为人工整理结果，避免被后续普通重扫直接覆盖。

## 歌单管理

本地歌曲可以加入 Folia 内部歌单，也可以把当前队列保存为歌单。

歌单只保存歌曲引用，不复制或移动磁盘文件。从曲库删除歌曲或整个文件夹时，对应歌曲也会从本地歌单中移除。

## 删除文件夹或歌曲

从本地音乐库删除文件夹时，Folia 会移除该目录及其子目录中的曲库记录，但不会删除或修改磁盘上的音乐文件。

删除后如果再次导入同一目录，Folia 会根据当前磁盘内容重新建立索引。

## 数据与缓存

本地曲库索引、导入快照、艺术家/专辑实体和歌曲关系由 Dexie 管理并保存在本地数据库中。音频文件内容不会上传到 Folia 服务。

在线封面的存储位置因运行环境而异：

- Web 版写入 OPFS。
- Electron 桌面版写入应用文件缓存。

数据库只保存在线地址和轻量缓存描述。封面缓存属于可重建数据；缓存缺失或损坏时，会依次尝试在线地址、有效的内嵌封面或占位图，不影响歌曲和实体信息。

## 常见问题

### 导入按钮不可用

当前浏览器可能不支持 File System Access API。请改用支持目录选择的浏览器或 Folia 桌面版。

### 重启后无法播放本地歌曲

先根据界面提示恢复目录访问权限。如果目录已经移动或改名，请重新导入该目录。

### 自动匹配选错了歌曲

进入对应文件夹的“整理歌曲信息”，修改检索文字并切换来源后手动选择候选；也可以选择“使用本地信息”，恢复导入快照并跳过后续自动匹配。

### 艺术家或专辑被错误合并

打开对应艺术家或专辑集合，进入实体信息面板，选择错误成员并拆分到新实体或已有实体。

### 删除曲库会不会删除音乐文件

不会。删除操作只影响 Folia 的本地曲库记录，不会删除磁盘文件。
