JSON 交换格式

用于描述仓库元数据的 TOML 格式便于书写和阅读，但受到各语言实现的限制，解析可能存在一些问题。

本文定义了 JSON 格式的同义替代，以规范各实现对仓库元数据进行交换时的信息格式。

标识符

数据交换中通过以下两种标识符指代光盘和音轨。

// 专辑标识符
type AlbumIdentifier = string; // UUID

// 光盘标识符
interface DiscIdentifier {
  // 专辑 ID
  album_id: AlbumIdentifier;
  // 光盘 ID
  disc_id: number;
}

// 音轨标识符
type TrackIdentifier = DiscIdentifier & {
  // 音轨 ID
  track_id: number;
}

专辑信息

// 专辑信息
interface AlbumInfo {
  // 专辑 ID
  album_id: AlbumIdentifier;
  // 专辑名称
  title: string;
  // 专辑类型
  edition?: string;
  // 专辑品番
  catalog: string;
  // 专辑艺术家
  artist: string;
  // 专辑的发行日期
  date: string;
  // 音乐类型
  type: TrackType;
  // 光盘信息
  discs: DiscInfo[];
}

// 专辑详细信息
type AlbumDetail = AlbumInfo & {
  // 专辑详细艺术家
  artists?: Artists;
  // 专辑标签
  tags?: string[];
  // 光盘信息
  discs: DiscDetail[];
}

// 光盘信息
interface DiscInfo {
  // 光盘名称
  title?: string;
  // 光盘品番
  catalog: string;
  // 光盘艺术家
  artist?: string;
  // 音乐类型
  type?: TrackType;
  // 音轨信息
  tracks: TrackInfo[];
}

// 光盘详细信息
type DiscDetail = DiscInfo & {
  // 光盘详细艺术家
  artists?: Artists;
  // 光盘标签
  tags?: string[];
  // 音轨信息
  tracks: TrackDetail[];
}

// 音轨信息
interface TrackInfo {
  // 音轨标题
  title: string;
  // 音轨艺术家
  artist?: string;
  // 音乐类型
  type?: TrackType;
}

// 音轨详细信息
type TrackDetail = TrackInfo & {
  // 音轨详细艺术家
  artists?: Artists;
  // 音轨标签
  tags?: string[];
}

// 详细艺术家
type Artists = ExtendedArtists & Record<string, string>;

// 详细艺术家的预定义字段
interface ExtendedArtists {
  // 歌手
  vocal?: string;
  // 作曲
  composer?: string;
  // 作词
  lyricist?: string;
  // 编曲
  arranger?: string;
}

// 音乐类型
type TrackType = "normal" | "instrumental" | "absolute" | "drama" | "radio" | "vocal";

专辑标签

// 标签简介
interface TagInfo {
  // Tag 名称
  name: string;
  // Tag 类型
  type: TagType;
}

// 标签详细信息
type TagDetail = TagInfo & {
  // Tag 本地化名
  names?: Record<string, string>;
  // 父级 Tag
  included_by?: string[];
  // 子 Tag
  includes?: Record<TagType, string[]>;
}

// 标签类型
type TagType = "artist" | "group" | "animation" | "radio" | "series" | "project" | "game" | "organization" | "category" | "unknown";