From 09edac8cc9fa36f783a6634278516deae3f21a2e Mon Sep 17 00:00:00 2001 From: SeraphJACK Date: Fri, 14 Apr 2023 08:52:40 +0800 Subject: [PATCH 1/7] annim --- src/05.audio-library/01.protocol.md | 4 +- src/06.anniv/09.search.md | 12 ++-- src/08.annim/00.readme.md | 7 ++ src/08.annim/01.protocol.md | 103 ++++++++++++++++++++++++++++ src/08.annim/02.backend.md | 7 ++ 5 files changed, 126 insertions(+), 7 deletions(-) create mode 100644 src/08.annim/00.readme.md create mode 100644 src/08.annim/01.protocol.md create mode 100644 src/08.annim/02.backend.md diff --git a/src/05.audio-library/01.protocol.md b/src/05.audio-library/01.protocol.md index a567f21..468a057 100644 --- a/src/05.audio-library/01.protocol.md +++ b/src/05.audio-library/01.protocol.md @@ -105,7 +105,9 @@ Access-Control-Allow-Origin: * "protocol_version": "0.2.1", // 音频仓库最近一次数据更新时间 // 用于客户端缓存 `/albums` 请求结果 - "last_update": 1639631487 + "last_update": 1639631487, + // 用于提供元数据的 `Annim` 服务器 URL + "meta_server": "https://annim.example.com" } ``` diff --git a/src/06.anniv/09.search.md b/src/06.anniv/09.search.md index 32da524..867de08 100644 --- a/src/06.anniv/09.search.md +++ b/src/06.anniv/09.search.md @@ -6,12 +6,12 @@ ## 请求参数 -| 参数名 | 类型 | 说明 | -| ------------------ | -------- | ---------------- | -| `search_albums` | `bool` | 是否搜索专辑 | -| `search_tracks` | `bool` | 是否搜索音轨 | -| `search_playlists` | `bool` | 是否搜索播放列表 | -| `keyword` | `string` | 搜索关键字 | +| 参数名 | 类型 | 说明 | +| ------------------ | -------- | ------------------------ | +| `search_albums` | `bool` | **已弃用**，是否搜索专辑 | +| `search_tracks` | `bool` | **已弃用**，是否搜索音轨 | +| `search_playlists` | `bool` | 是否搜索播放列表 | +| `keyword` | `string` | 搜索关键字 | ## 返回 diff --git a/src/08.annim/00.readme.md b/src/08.annim/00.readme.md new file mode 100644 index 0000000..06f6317 --- /dev/null +++ b/src/08.annim/00.readme.md @@ -0,0 +1,7 @@ +# Annim + +> ⚠️️ 目前的 `Annim` 仍处于 `Draft` 状态，尚未完全定稿。欢迎随时提出意见或建议。 + +> ⚠️️ 目前 `Annim` 协议的版本为 `1`。 + +`Annim` 是独立的元数据服务，每一个 `Annil` 都需要指定一个对应的 `Annim` 服务提供元数据。 diff --git a/src/08.annim/01.protocol.md b/src/08.annim/01.protocol.md new file mode 100644 index 0000000..ee59dc2 --- /dev/null +++ b/src/08.annim/01.protocol.md @@ -0,0 +1,103 @@ +# Annim 元数据协议 + +Annim 元数据协议用于向客户端提供元数据服务。所有接口均使用 [Anni 信息导出格式](../06.anniv/07.export-format.md)。 + +## 元数据 + +### 获取 Tag 列表 + +`GET /tags` + +#### 返回 + +返回包含所有 `Tag` 的数组，类型为 `TagInfo[]` 。 + +### 专辑信息 + +通过 `album_id` 获得专辑元数据的接口。支持同时获取多张专辑的元数据信息。 + +#### Endpoint + +`GET /albums` + +#### 请求参数 + +| 参数名 | 说明 | +| ------ | ---------------------------- | +| `id[]` | 待获取元数据的专辑 `ID` 列表 | + +#### 返回 + +返回以 `album_id` 为键，专辑元数据或空为值的 `Object`。 + +当查询成功时，值为专辑的 `AlbumDetail`，否则为 `null`。 + +### 按 Tag 检索专辑 + +通过 Tag 检索归属于该 Tag 下的专辑列表。 + +该接口属于检索接口，标签使用「向上合并」的语义。即计算专辑标签时，需要取专辑内所有专辑标签、光盘标签和音轨标签的**并集**。具体定义见 [专辑信息 - 标签](../02.metadata-repository/02.album-information.md#标签)。 + +#### Endpoint + +`GET /albums/by-tag` + +### 参数 + +| 参数名 | 类型 | 说明 | +| ----------- | --------- | ----------------------------- | +| `tag` | `string` | Tag 名 | +| `recursive` | `boolean` | 是否递归检索子 Tag 所包含专辑 | + +#### 返回 + +`AlbumDetail[]` + +#### 错误列表 + +| 错误代码 | 详情 | +| -------- | ------------ | +| `902000` | `Tag` 不存在 | + +### 获取 Tag 关系 + +`GET /tag-graph` + +#### 返回 + +返回 `tag` 依赖关系的邻接表，类型表示为 `Record` 。 + +`Key-Value` 对应的是标签与其所包含的子标签。字符串格式为 `:`，标签类型不可省略。 + +## 搜索 + +### Endpoint + +`GET /search` + +### 请求参数 + +| 参数名 | 类型 | 说明 | +| --------------- | -------- | ------------ | +| `search_albums` | `bool` | 是否搜索专辑 | +| `search_tracks` | `bool` | 是否搜索音轨 | +| `keyword` | `string` | 搜索关键字 | + +### 返回 + +返回 `SearchResult` 。 + +#### 参数列表 + +```ts +interface Result { + content: T; + // 归一化的 score ，必须为属于 [0, 100] 的浮点数 + score: number; +} + +interface SerachResult { + albums?: Result[]; + tracks?: Result[]; +} +``` diff --git a/src/08.annim/02.backend.md b/src/08.annim/02.backend.md new file mode 100644 index 0000000..eb611df --- /dev/null +++ b/src/08.annim/02.backend.md @@ -0,0 +1,7 @@ +# Annim 元数据后端 + +Annim 不仅需要与客户端约定提供元数据的协议，也需要关于元数据来源的约定，这就是 Annim 元数据后端。 + +## Git repo 后端 + +使用 git 仓库作为元数据来源，仓库结构应符合[Anni 元数据仓库](../02.metadata-repository/00.readme.md)标准。 From 60edbe92baeaa57d455f1bd55ff68d6f4956b413 Mon Sep 17 00:00:00 2001 From: SeraphJACK Date: Fri, 14 Apr 2023 09:06:13 +0800 Subject: [PATCH 2/7] Update --- src/08.annim/01.protocol.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/08.annim/01.protocol.md b/src/08.annim/01.protocol.md index ee59dc2..5794fc5 100644 --- a/src/08.annim/01.protocol.md +++ b/src/08.annim/01.protocol.md @@ -77,11 +77,13 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 ### 请求参数 -| 参数名 | 类型 | 说明 | -| --------------- | -------- | ------------ | -| `search_albums` | `bool` | 是否搜索专辑 | -| `search_tracks` | `bool` | 是否搜索音轨 | -| `keyword` | `string` | 搜索关键字 | +| 参数名 | 类型 | 说明 | +| --------------- | -------- | ------------------------ | +| `search_albums` | `bool` | 是否搜索专辑 | +| `search_tracks` | `bool` | 是否搜索音轨 | +| `keyword` | `string` | 搜索关键字 | +| `limit` | `number` | 最多返回条目数 | +| `offset` | `number` | 跳过多少条记录，缺省为 0 | ### 返回 From 822344ca7898f0487e0527d9f632fdb05230c36c Mon Sep 17 00:00:00 2001 From: SeraphJACK Date: Fri, 14 Apr 2023 09:38:15 +0800 Subject: [PATCH 3/7] Update --- src/08.annim/01.protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/08.annim/01.protocol.md b/src/08.annim/01.protocol.md index 5794fc5..f53a6e2 100644 --- a/src/08.annim/01.protocol.md +++ b/src/08.annim/01.protocol.md @@ -87,7 +87,7 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 ### 返回 -返回 `SearchResult` 。 +返回 `SearchResult` ，结果按 `score` 降序排序。 #### 参数列表 From c8f03f564c457f9d28727c8294dce35db8069da0 Mon Sep 17 00:00:00 2001 From: SeraphJACK Date: Fri, 14 Apr 2023 17:25:20 +0800 Subject: [PATCH 4/7] Requested changes --- src/06.anniv/03.playlist.md | 20 ++++++++++++++++++++ src/06.anniv/09.search.md | 28 ---------------------------- src/SUMMARY.md | 4 +++- 3 files changed, 23 insertions(+), 29 deletions(-) delete mode 100644 src/06.anniv/09.search.md diff --git a/src/06.anniv/03.playlist.md b/src/06.anniv/03.playlist.md index 7dcfa17..ffb5814 100644 --- a/src/06.anniv/03.playlist.md +++ b/src/06.anniv/03.playlist.md @@ -307,3 +307,23 @@ type PatchedPlaylistInfo = Partial>; | -------- | -------------- | | `103002` | 播放列表不存在 | | `103003` | 非法修改类型 | + +## 搜素播放列表 + +### Endpoint + +`GET /api/playlist/search` + +### 请求 + +#### 请求参数 + +| 参数名 | 详情 | +| --------- | -------------- | +| `keyword` | 搜索关键词 | +| `limit` | 最多返回条目数 | +| `offset` | 跳过条目数 | + +### 响应 + +返回一个 `PlaylistInfo[]` ，按相关程度降序排序。 diff --git a/src/06.anniv/09.search.md b/src/06.anniv/09.search.md deleted file mode 100644 index 867de08..0000000 --- a/src/06.anniv/09.search.md +++ /dev/null @@ -1,28 +0,0 @@ -# 搜索 - -## Endpoint - -`GET /api/search` - -## 请求参数 - -| 参数名 | 类型 | 说明 | -| ------------------ | -------- | ------------------------ | -| `search_albums` | `bool` | **已弃用**，是否搜索专辑 | -| `search_tracks` | `bool` | **已弃用**，是否搜索音轨 | -| `search_playlists` | `bool` | 是否搜索播放列表 | -| `keyword` | `string` | 搜索关键字 | - -## 返回 - -返回 `SearchResult` 。 - -### 参数列表 - -```ts -interface SerachResult { - albums?: AlbumDetail[]; - tracks?: TrackInfoWithAlbum[]; - playlists?: PlaylistInfo[]; -} -``` diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d1a1ed0..d0f8b8d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -52,7 +52,6 @@ - [Annil Token 管理](./06.anniv/04.credential.md) - [信息导出格式](./06.anniv/07.export-format.md) - [专辑元数据](./06.anniv/08.meta.md) - - [搜索](./06.anniv/09.search.md) - [分享管理](./06.anniv/05.share.md) - [播放统计](./06.anniv/06.statistics.md) - [喜欢](./06.anniv/10.favorite.md) @@ -62,6 +61,9 @@ - [两步验证（2fa）](./06.anniv/features/02.2fa.md) - [禁止注册（close）](./06.anniv/features/03.close.md) - [预构建数据源（metadata-db）](./06.anniv/features/04.metadata-db.md) +- [Annim 元数据服务](./08.annim/00.readme.md) + - [协议](./08.annim/01.protocol.md) + - [元数据后端](./08.annim/02.backend.md) - [Annisonic](./07.annisonic/00.readme.md) - [实现的 API](./07.annisonic/01.apis.md) - [已测试的客户端](./07.annisonic/02.clients.md) From da005e3191859a60433139ebc35a8a6ecd0809d4 Mon Sep 17 00:00:00 2001 From: SeraphJACK Date: Fri, 21 Apr 2023 13:12:18 +0800 Subject: [PATCH 5/7] Requested changes --- src/08.annim/01.protocol.md | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/src/08.annim/01.protocol.md b/src/08.annim/01.protocol.md index f53a6e2..f4ed297 100644 --- a/src/08.annim/01.protocol.md +++ b/src/08.annim/01.protocol.md @@ -40,14 +40,14 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 #### Endpoint -`GET /albums/by-tag` +`GET /tags/:tag/albums` ### 参数 -| 参数名 | 类型 | 说明 | -| ----------- | --------- | ----------------------------- | -| `tag` | `string` | Tag 名 | -| `recursive` | `boolean` | 是否递归检索子 Tag 所包含专辑 | +| 参数名 | 类型 | 说明 | +| ----------- | --------- | -------------------------------- | +| `tag` | `string` | 路径中的 `tag` 参数，表示 Tag 名 | +| `recursive` | `boolean` | 是否递归检索子 Tag 所包含专辑 | #### 返回 @@ -77,29 +77,23 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 ### 请求参数 -| 参数名 | 类型 | 说明 | -| --------------- | -------- | ------------------------ | -| `search_albums` | `bool` | 是否搜索专辑 | -| `search_tracks` | `bool` | 是否搜索音轨 | -| `keyword` | `string` | 搜索关键字 | -| `limit` | `number` | 最多返回条目数 | -| `offset` | `number` | 跳过多少条记录，缺省为 0 | +| 参数名 | 类型 | 说明 | +| --------- | -------- | ------------------------------------------- | +| `type` | `string` | `album` 或 `track` ，分别代表搜索专辑或单曲 | +| `keyword` | `string` | 搜索关键字 | +| `limit` | `number` | 最多返回条目数 | +| `offset` | `number` | 跳过多少条记录，缺省为 0 | ### 返回 -返回 `SearchResult` ，结果按 `score` 降序排序。 +返回 `ScoredEntry[]` ，结果按 `score` 降序排序，`T` 为 `AlbumDetail` 或 `TrackInfoWithAlbum` 。 #### 参数列表 ```ts -interface Result { +interface ScoredEntry { content: T; // 归一化的 score ，必须为属于 [0, 100] 的浮点数 score: number; } - -interface SerachResult { - albums?: Result[]; - tracks?: Result[]; -} ``` From ddd9276fc8733b597be3d0e8224753fcde72e591 Mon Sep 17 00:00:00 2001 From: SeraphJACK Date: Thu, 11 May 2023 12:57:13 +0800 Subject: [PATCH 6/7] Some requested changes --- src/08.annim/01.protocol.md | 40 +++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/src/08.annim/01.protocol.md b/src/08.annim/01.protocol.md index f4ed297..022bd85 100644 --- a/src/08.annim/01.protocol.md +++ b/src/08.annim/01.protocol.md @@ -4,27 +4,19 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 ## 元数据 -### 获取 Tag 列表 - -`GET /tags` - -#### 返回 - -返回包含所有 `Tag` 的数组，类型为 `TagInfo[]` 。 - ### 专辑信息 通过 `album_id` 获得专辑元数据的接口。支持同时获取多张专辑的元数据信息。 #### Endpoint -`GET /albums` +`GET /album/:id` #### 请求参数 | 参数名 | 说明 | | ------ | ---------------------------- | -| `id[]` | 待获取元数据的专辑 `ID` 列表 | +| `id` | 待获取元数据的专辑 `ID` 列表 | #### 返回 @@ -32,6 +24,14 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 当查询成功时，值为专辑的 `AlbumDetail`，否则为 `null`。 +### 获取 Tag 列表 + +`GET /tags` + +#### 返回 + +返回包含所有 `Tag` 的数组，类型为 `TagInfo[]` 。 + ### 按 Tag 检索专辑 通过 Tag 检索归属于该 Tag 下的专辑列表。 @@ -42,7 +42,7 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 `GET /tags/:tag/albums` -### 参数 +#### 参数 | 参数名 | 类型 | 说明 | | ----------- | --------- | -------------------------------- | @@ -59,8 +59,26 @@ Annim 元数据协议用于向客户端提供元数据服务。所有接口均 | -------- | ------------ | | `902000` | `Tag` 不存在 | +### 获取 Tag 详细 + +#### Endpoint + +`GET /tags/:tag/detail` + +#### 参数 + +| 参数名 | 类型 | 说明 | +| ------ | -------- | -------------------------------- | +| `tag` | `string` | 路径中的 `tag` 参数，表示 Tag 名 | + +#### 返回 + +`TagDetail` + ### 获取 Tag 关系 +#### Endpoint + `GET /tag-graph` #### 返回 From ac00aac5e7fd94571dd52178e66cc3195db143b8 Mon Sep 17 00:00:00 2001 From: Seraph_JACK Date: Mon, 1 Jan 2024 19:34:55 +0800 Subject: [PATCH 7/7] Update src/06.anniv/03.playlist.md Co-authored-by: Yesterday17 --- src/06.anniv/03.playlist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/06.anniv/03.playlist.md b/src/06.anniv/03.playlist.md index ffb5814..a169d6f 100644 --- a/src/06.anniv/03.playlist.md +++ b/src/06.anniv/03.playlist.md @@ -308,7 +308,7 @@ type PatchedPlaylistInfo = Partial>; | `103002` | 播放列表不存在 | | `103003` | 非法修改类型 | -## 搜素播放列表 +## 搜索播放列表 ### Endpoint