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 的终端转发服务