播放列表

播放列表是顺序的歌曲列表，用户可以通过播放列表对零散的歌曲进行整理。

播放列表相关的功能有获取、创建、修改、删除。

错误一览

获取播放列表

获取指定播放列表

Endpoint

GET /api/playlist

请求

请求参数

返回

请求成功时，返回播放列表的全部信息。

返回参数

PlaylistItem 可以为 PlaylistItemTrack、PlaylistItemDummyTrack 或 PlaylistItemAlbum，分别表示歌曲、占位歌曲和专辑，详见下方类型定义。

每种 PlaylistItem 类型均含有：

PlaylistItem & Id 类型在各 PlaylistItem 的基础上增加了：

示例

{
  "id": "3",
  "name": "测试",
  "description": "测试",
  "owner": "3",
  "is_public": true,
  "cover": {
    "album_id": "cfbde6ad-e365-4435-bfda-5a475899fb6b",
    "disc_id": 1
  },
  "items": [
    {
      "id": "3",
      "type": "normal",
      "description": "interesting",
      "info": {
        "album_id": "cfbde6ad-e365-4435-bfda-5a475899fb6b",
        "disc_id": 1,
        "track_id": 1,
        "title": "ハルノヘッドフォン",
        "artist": "春日部ハル（篠田みなみ）",
        "album_title": "t7s Longing for summer"
      }
    }
  ],
  "last_modified": 1145141919810
}

参数表示

interface PlaylistInfo {
  // 播放列表 ID
  id: string;
  // 播放列表标题
  name: string;
  // 播放列表说明
  description?: string;
  // 播放列表创建者
  owner: string;
  // 是否公开
  is_public: boolean;
  // 封面
  cover: PlaylistCover;
}

type PlaylistCover = DiscIdentifier | null; // 专辑/光盘封面

// 表示无封面的结构
type EmptyPlaylistCover = { album_id?: "" };

interface BasePlaylistItem<Info> {
  // 内容类型
  type: string;
  // 内容说明
  description?: string;
  // 内容附加信息
  info: Info;
}

// 普通音轨
interface PlaylistItemTrack extends BasePlaylistItem<TrackInfoWithAlbum> {
  type: "normal";
}

// 普通音轨（无元数据）
export interface PlaylistItemPlainTrack
  extends BasePlaylistItem<TrackIdentifier> {
  type: "normal";
}

// 占位音轨
interface PlaylistItemDummyTrack extends BasePlaylistItem<Required<TrackInfo>> {
  type: "dummy";
}

// 普通专辑
interface PlaylistItemAlbum extends BasePlaylistItem<AlbumIdentifier> {
  type: "album";
}

type PlaylistItem =
  | PlaylistItemDummyTrack
  | PlaylistItemTrack
  | PlaylistItemAlbum;
type PlaylistPatchItem =
  | PlaylistItemDummyTrack
  | PlaylistItemPlainTrack
  | PlaylistItemAlbum;

错误列表

获取指定用户播放列表

Endpoint

GET /api/playlists

请求参数

返回

若指定用户为自己，则返回所有播放列表。否则仅返回公开的播放列表。

返回 PlaylistInfo[] 。

创建播放列表

Endpoint

PUT /api/playlist

请求

请求参数

返回

处理完成后，返回新创建的播放列表信息（Playlist）。

参数表示

interface CreatePlaylistBody extends Omit<PlaylistInfo, "id" | "owner"> {
  items: PlaylistPatchItem[];
}

错误列表

修改播放列表

Endpoint

PATCH /api/playlist

请求

对播放列表的修改分为三个部分：增加歌曲、删除歌曲和排列歌曲。

请求参数

返回

修改成功后，返回修改后的播放列表信息（Playlist）。

参数表示

export type PatchPlaylistRequestBody =
  | PatchPlaylistInfoBody
  | AppendPlaylistBody
  | RemovePlaylistItemBody
  | ReorderPlaylistBody
  | ReplacePlaylistItemBody;

// 修改 Playlist 本身信息
export type PatchPlaylistInfoBody = PatchPlaylistBodyType<
  "info",
  PatchedPlaylistInfo
>;
// 在 Playlist 末尾增加音乐
export type AppendPlaylistBody = PatchPlaylistBodyType<
  "append",
  PlaylistPatchItem[]
>;
// 通过 ID 从 Playlist 中删除音乐
export type RemovePlaylistItemBody = PatchPlaylistBodyType<"remove", string[]>;
// 通过 ID 对 Playlist 重排序
export type ReorderPlaylistBody = PatchPlaylistBodyType<"reorder", string[]>;
// 修改 Playlist 中部分内容
export type ReplacePlaylistItemBody = PatchPlaylistBodyType<
  "replace",
  (PlaylistPatchItem & Id)[]
>;

type PatchPlaylistBodyType<K, P> = Id & {
  command: K;
  payload: P;
};

type PatchedPlaylistInfo = Partial<Omit<PlaylistInfo, "id" | "owner">>;

错误列表

删除播放列表

Endpoint

DELETE /api/playlist

请求

请求参数

错误列表