Annim 元数据服务草案 #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft

Yesterday17 wants to merge 13 commits into master from refactor/metadata

src/02.metadata-repository/00.readme.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -2,7 +2,7 @@ @@
     > ⚠️️目前的元数据仓库标准仍处于 `Draft` 状态，尚未完全定稿。欢迎随时提出意见或建议。
-    > ⚠️️目前的元数据仓库标准版本（`edition`）为 `1.0+alpha.1.5.1`。
+    > ⚠️️目前的元数据仓库标准版本（`edition`）为 `1.0+alpha.2.0.0`。
     尽管 `Anni` 约定对音频文件内嵌的标签有了严格的约束，但从实现的角度来看，如果所有的元数据都从音乐文件中获取，那么势必会导致如下问题：
@@ Expand Down @@

src/02.metadata-repository/01.folder-structure.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -4,13 +4,16 @@ @@
     ```
     ├── album
-    │   ├── KSLA-0178.toml
-    │   └── @META-DUPLICATED
-    │     ├── @META-DUPLICATED.0.toml
-    │     └── @META-DUPLICATED.1.toml
+    │   └── dc
+    │     └── 0d
+    │       └── dc0d9856-3345-4a25-acb8-fccc7b959e3e.toml
     └── tag
     │ └── [Anime] 神様になった日.toml
     ├── repo.toml
     ```
-    专辑存放的目录由 repo.toml 指定。
+    基本规则如下：
+    - 专辑存放在 `album` 目录下，通过 `Album ID` 两级索引的方式管理。
+    - 标签存放在 `tag` 目录下，文件名不限。
+    - 仓库元数据存放在 `repo.toml` 文件中。

src/02.metadata-repository/05.repo-metadata.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -9,11 +9,5 @@ @@
     # 仓库名
     name = "Yesterday17's Metadata Repo"
     # 仓库使用的元数据仓库描述版本
-    edition = "1.0"
-    # 存放专辑的子目录，默认为 ['album']
-    albums = ['album-beta', 'album']
+    edition = "1.0+alpha.2.0.0"
     ```
-    ## 专辑子目录
-    专辑可以存放在任意指定的子目录中，方便整理者以目录为单位对专辑信息进行分类。

src/06.anniv/03.playlist.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -127,7 +127,7 @@ interface BasePlaylistItem<Info> { @@
     }
     // 普通音轨
-    interface PlaylistItemTrack extends BasePlaylistItem<TrackInfoWithAlbum> {
+    interface PlaylistItemTrack extends BasePlaylistItem<TrackIdentifier> {
       type: "normal";
     }
@@ Expand Down @@

src/06.anniv/08.meta.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -2,14 +2,6 @@ @@
     `Anniv` 提供对元数据仓库中元数据进行索引的能力。
-    ## 结构定义
-    ```ts
-    type AlbumTitle = { album_title: string };
-    type TrackInfoWithAlbum = TrackIdentifier & Required<TrackInfo> & AlbumTitle;
-    ```
     ## 获取 Tag 列表
     `GET /api/meta/tags`
@@ Expand Down @@

src/06.anniv/09.search.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -22,7 +22,7 @@ @@
     ```ts
     interface SerachResult {
       albums?: AlbumDetail[];
-      tracks?: TrackInfoWithAlbum[];
+      tracks?: TrackIdentifier[];
       playlists?: PlaylistInfo[];
     }
     ```

src/06.anniv/10.favorite.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -10,7 +10,7 @@ @@
     #### 返回参数
-    返回 `TrackInfoWithAlbum[]` ，按照添加时间倒序排序。
+    返回 `TrackIdentifier[]` ，按照添加时间倒序排序。
     ### 添加单曲
@@ Expand Down @@

src/08.annim/00.readme.md

-Original file line number
+Diff line change
@@ -0,0 +1,32 @@
+    # Annim
+    > ⚠️️ 目前的 `Annim` 仍处于 `Draft` 状态，尚未完全定稿。欢迎随时提出意见或建议。
+    ## 背景
+    在 `Annim` 提出之前，我们已经拥有了用于储存元数据的[元数据仓库（`repo`）](../02.metadata-repository/00.readme.md)，以及用于针对性获取元数据的 [`Anniv` 元数据接口](../06.anniv/08.meta.md)。
+    但在实践中，我们发现：
+. 元数据仓库本身的维护成本较高，以 `Git` 仓库的形式组织虽然降低了协作成本，提供了版本控制的能力，但本质上仍然是一套兼容性的方案，具有一定的学习成本。
+. 将 `Anniv` 和元数据绑定的行为背离了元数据仓库建立的初衷。我们希望元数据是去中心化的，而 `Anniv` 却只能基于单一的元数据仓库进行元数据的分发。这导致了目前 `Project Anni` 中事实性地只存在一套元数据仓库，且新仓库的引入存在一定的难度。
+. 「音频仓库」和「元数据」之间的关联被耦合成了「音频仓库」与「Anniv」之间的耦合。但由于设计上的非耦合性，导致 `Anniv` 无法获取一些直接的上下文。以搜索为例，`Anniv` 无法得知用户使用的 `Annil` 中拥有哪些专辑，因此也无法提供合理意义上的搜索结果。
+. 目前单一元数据仓库的设计导致元数据的更新成本较高，无法较快地响应新内容的加入。
+    由此，我们提出 `Annim` 的概念，作为上述问题的一种解决方案。
+    ## 设计理念
+    `Annim` 围绕这以下几个核心理念展开：
+. 「元数据」与「音频仓库」绑定，与 `Anniv` 解耦。
+    `Annim` 的第一个任务就是将元数据相关的能力从 `Anniv` 中剥离。我们计划在 `Annim` 中提供一套 `GraphQL` 接口供客户端使用，以增加客户端获取元数据的灵活度。
+    在这一套纯查询接口的之上，未来我们还可以基于这一套接口定义，增加与元数据编辑、修改相关的能力，最终实现元数据的动态管理能力。
+. 多级元数据。
+    `Project Anni` 的核心目标之一是提供准确、完整的元数据。但无法忽略的是，整理获得完善的元数据需要大量的人力与时间成本，而听歌这件事情本身也是 `Project Anni` 的核心目标之一。因此，我们希望在获得准确无误的元数据之前，也能够存在一套「不完全正确但可用」的元数据，以达到最基本的使用目的。
+    为此，我们在 `Annim` 中提出了多级元数据的概念。它允许多个声明兼容的元数据源通过一定的形式共存，对客户端以单一元数据源的形式呈现。

src/08.annim/01.definition.md

-Original file line number
+Diff line change
@@ -0,0 +1,5 @@
+    # 术语与定义
+    - Anni 元数据协议：`Project Anni` 中客户端用于获取元数据的协议。
+    - 元数据源：符合 Anni 元数据协议，即上述协议的元数据提供方。
+    - 元数据仓库：元数据源的文本化存储形式，通常以 `Git` 仓库的形式存在。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Annim 元数据服务草案 #81

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Annim 元数据服务草案 #81

Are you sure you want to change the base?

Uh oh!

Annim 元数据服务草案 #81

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!