workspace

anni workspace 提供了一系列对本地音频整理工作空间的管理命令。

术语表

名称英语简称详情
音频整理工作空间Workspace工作空间anni workspace 工作的目录
工作目录工作空间根目录下的 .anni 目录，由 anni 控制状态
用户目录用户视图中使用的，实际工作的目录
专辑目录用户目录下，实际存放专辑的子目录
受控专辑目录工作目录下，实际存放专辑的子目录
受控链接用户目录下，链接到 工作目录 的符号链接，名称为 .album
专辑状态：未跟踪Untracked未跟踪用户通过 create 创建专辑，但未将专辑跟踪时的状态
提交Commit-通过 add 将专辑从工作空间中移交到音频仓库的行为
专辑状态：已跟踪Committed已跟踪用户通过 add 将专辑结构交由 anni 托管后的状态
发布Publish-通过 publish 将专辑从工作空间中移交到音频仓库的行为
专辑状态：已发布Published已发布用户通过 publish --soft 发布专辑后的状态
专辑状态：悬垂Dangling-用户目录下存在专辑，但工作目录中不存在 AlbumID 对应目录，或符号链接错误
专辑状态：待回收Garbage-用户目录中不存在该专辑，且该专辑在工作目录中对应为空
专辑锁在对某一专辑目录进行状态变更时，为防止并行冲突放置的锁。通常为命名为 .lock 的文件

工作空间

音频整理工作空间看起来有点拗口的样子，之后我们就用工作空间来代替好了

工作空间的由来是为了替代掉原有的，没有任何约束的任意目录。工作空间的存在目的有两个：

  1. 通过固定的目录结构，防止误操作的出现。
    常见的误操作包括在保种的目录应用元数据、在保种的目录修改音频内嵌封面等修改原文件内容的行为。全是血泪史
  2. 通过一定的机制，简化音频整理的操作。
    在规定了目录结构后，音频目录就可以和元数据文件关联起来。元数据文件的品番在整理过程中可能（由于填写错误）存在变更，但 AlbumID 一般不会变化。

目录结构

工作空间的结构分为两部分：工作目录和用户目录。

工作目录

工作目录是名为 .anni 的隐藏目录，其结构如下：

├── objects
│   ├── 10
│   │   └── 77
│   │       └── 1077d96b-8fd3-4585-a6ab-8eef265a48df
│   ├── 25
│   │   └── eb
│   ├── d2
│   │   └── 74
│   ├── e
│   │   └── ff
│   └── fc
│       └── 50
├── repo
│   ├── album
│   ├── tag
│   ├── repo.toml
│   └── Readme.md
└── config.toml

该目录中保存了音频整理所需的两大元素：音频资源和元数据仓库。目前根目录下定义的内容如下：

  1. 音频资源，以严格目录格式存放于 objects 目录下，层级为 2。当专辑目录下存在 .publish 文件时，该专辑的状态为已发布。
  2. 元数据仓库，位于 repo 目录。
  3. config.toml，负责记录一些额外的配置信息。

用户目录

工作空间中除工作目录的部分都是用户目录。用户目录结构基本满足约定目录结构，但存在以下区别：

  1. 专辑目录中碟片数量的限定（[n Discs]）将不起作用
  2. 碟片目录的名称没有任何限制

示例

一个典型的用户目录结构如下：

├── [A] halca
│   ├── [210519][VVXX-01011] キミがいたしるし
│   │   ├── 01. キミがいたしるし.flac -> ./.album/1/1.flac
│   │   ├── 02. もういいや。.flac -> ./.album/1/2.flac
│   │   ├── 03. キミがいたしるし (TV Size).flac -> ./.album/1/3.flac
│   │   ├── 04. キミがいたしるし (Instrumental).flac -> ./.album/1/4.flac
│   │   ├── 05. もういいや。 (Instrumental).flac -> ./.album/1/5.flac
│   │   ├── .album -> ../../.anni/objects/10/77/1077d96b-8fd3-4585-a6ab-8eef265a48df
│   │   └── cover.jpg -> ./.album/cover.jpg
│   └── [220817][VVXX-01253] 誰彼スクランブル／あれこれドラスティック【Complete Edition】
│       ├── 01. 誰彼スクランブル.flac
│       ├── 02. あれこれドラスティック.flac
│       ├── 03. reprise.flac
│       ├── 04. あれこれドラスティック (halca Ver.).flac
│       ├── 05. 誰彼スクランブル (Remixed by Snail's House).flac
│       ├── 06. 時としてバイオレンス (Remixed by キノシタ).flac
│       ├── 07. 誰彼スクランブル (TV Size).flac
│       ├── 08. あれこれドラスティック (TV Size).flac
│       ├── 09. 誰彼スクランブル (Instrumental).flac
│       ├── 10. あれこれドラスティック (Instrumental).flac
│       ├── 11. reprise (Instrumental).flac
│       ├── .album -> ../../.anni/objects/e1/5/e1057cfd-cd38-4280-bccf-4a48d4cf39f6
│       └── cover.jpg
└── .anni
    ├── config.toml
    ├── objects
    │   └── 10
    │       └── 77
    │           └── 1077d96b-8fd3-4585-a6ab-8eef265a48df
    │               ├── 1
    │               │   ├── 1.flac
    │               │   ├── 2.flac
    │               │   ├── 3.flac
    │               │   ├── 4.flac
    │               │   ├── 5.flac
    │               │   └── cover.jpg
    │               └── cover.jpg
    └── repo

观察上述目录结构中的 [A] halca 部分。用户部分有以下几个特征：

  1. 专辑目录可以位于任意嵌套层级下。
  2. 在整理过程中，目录中所有文件都是普通文件。
    如 [220817][VVXX-01253] 誰彼スクランブル／あれこれドラスティック【Complete Edition】。
  3. 在文件基本已经确定后，可以通过 workspace add 将专辑状态更新为已跟踪。此时，所有文件都会被转移到工作目录中，原目录下仅保留符号链接。
    如 [210519][VVXX-01011] キミがいたしるし。
  4. 专辑的目录下都存在名为 .album 的符号链接，链接到工作目录中的实际专辑位置。
    因此，不存在 .album 的目录会被 anni 忽略。anni 只会处理存在专辑指向的目录。

配置文件

工作空间中的配置文件可以用于记录与整理相关的配置。一个简单的配置文件样例如下所示：

[workspace]
publish-to = ["default"]

[library.default]
path = "/home/yesterday17/Music"
layers = 2

命令

init

初始化工作空间。

  • 全新创建工作空间
  • --repo：从指定位置 clone 元数据仓库
  • --repo-config：使用元数据仓库的 repo.toml 作为工作空间的配置文件
    创建从 .anni/config.toml 到 .anni/repo/repo.toml 的符号链接。

status

查看工作空间中各专辑的状态。

  • -a, --album-id：显示完整的 Album ID，而非 8 位的 Album ID 前缀
  • -j, --json：输出当前工作空间的完整状态为 JSON 格式

create

新建专辑目录。新建的专辑目录状态为未跟踪。

  • -a, --album-id：创建专辑的 Album ID
  • -d, --disc-num：创建专辑对应的光盘数量
  • -f, --force：当创建目录的路径存在时，是否强制创建专辑目录

add

将专辑的状态变更为已跟踪。状态变更前，anni 会输出一些信息供对比。

  • -t, --tags：变更状态的同时，向元数据仓库导入音频中内嵌的元数据
  • -y, --yes：跳过信息检查
  • d, --dry-run：不实际变更专辑状态，仅运行流程。该属性搭配 -t 使用可以仅导入专辑元数据
  • e, --editor：状态变更后，打开元数据仓库中的元数据文件

rm

从工作空间中删除某一专辑。

  • -y, --yes：跳过人工确认

update

在已跟踪状态下，对音频、封面或元数据进行更新。

publish

在已跟踪状态下，将元数据和封面写入，并将专辑从工作空间中移动到音频仓库。

专辑发布后，用户目录中的专辑目录也会被删除。

当专辑目录中存在任意非符号链接的正常文件时，发布过程中止。

  • -w, --write：在发布前写入元数据和封面，效果与 update -tc 相同。
  • -u, --uuid：通过 Album ID 而非专辑路径发布专辑
  • -s, --soft：在专辑发布时，采用移动+软删除的方式替代直接移动目录。发布结束后，专辑状态变更为已发布。工作目录中仍然会保留专辑信息，但用户目录中的专辑会被移除。

fsck

修复一些常见的工作空间问题。

  1. -d, --fix-dangling：修复状态为悬垂的专辑目录
  2. --gc：清除状态为待回收的专辑目录

serve

启动工作空间的服务端环境，包括：

  • 一个基于严格目录格式的 Annil 服务端
  • 一个基于 GraphQL 的元数据服务端
  • 一个基于 WebSocket 的终端转发服务