トラックリスト データ設計書

最終更新: 2026-05-28

1. 概要

releases.json にアルバム収録曲・シングルカップリングのトラックリストを追加するためのデータ設計。 プレイリスト機能（#336）において楽曲とリリースを紐付ける trackId の参照先を確立することが本設計の主目的である。

2. 背景・目的

現行の releases.json はリリースのメタ情報（タイトル・日付・フォーマット）のみを保持しており、収録曲情報がない。

3. MusicBrainz API フィールドマッピング

取得エンドポイント: https://musicbrainz.org/ws/2/release/{mbid}?inc=recordings&fmt=json

レスポンス構造（関連部分）

{
  "media": [
    {
      "position": 1,
      "format": "CD",
      "tracks": [
        {
          "id": "...",
          "number": "1",
          "title": "愛の種",
          "length": 214000,
          "recording": {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          }
        }
      ]
    }
  ]
}

フィールド対応表

Track.id に recording UUID を採用する理由 同一楽曲がシングルとアルバムに重複収録される場合、track UUID はリリースごとに異なるが recording UUID は同一となる。PlaylistEntry.trackId からの参照は recording UUID の方が安定しており、クロスリリース参照（「このシングル曲はどのアルバムにも収録されている」等）が可能になる。

4. 型定義

Track インターフェース（新規追加）

export interface Track {
  /** MusicBrainz recording UUID（楽曲の安定識別子・PlaylistEntry.trackId の参照先） */
  id: string;
  /** MusicBrainz track UUID（このリリース上の出現位置の識別子）。手動登録リリースでは省略可 */
  mbTrackId?: string;
  /** ディスク内でのトラック番号（1始まり） */
  trackNumber: number;
  /** ディスク番号（1始まり。シングル等の1枚組は省略可） */
  discNumber?: number;
  /** 収録曲タイトル */
  title: string;
  /** 曲の長さ（ミリ秒。MusicBrainz に未登録の場合は省略可） */
  length?: number;
  /** 外部リンク（YouTube MV・YouTube Music・YouTube Shorts 等）。sync-discography により自動付与。未取得時は省略 */
  links?: ExternalLink[];
  /** MusicBrainz artist-credit から取得したアーティスト名。sync-discography で自動設定 */
  artist?: string;
  /** アーティストがユニットの場合のユニット ID（units.json の id と一致）。sync-discography で自動設定 */
  unitId?: string;
  /** MusicBrainz artist MBID（artist-credit から取得）。sync-discography で自動設定 */
  artistMbid?: string;
}

ExternalLink 型（Track.links の要素）

ExternalLink は { type: ExternalLinkType; url: string } の形式で定義される（types/external-link.ts）。

Release インターフェース（tracks フィールド追加）

export interface Release {
  id: string;
  title: string;
  releaseDate: string;
  format: ReleaseFormat;
  source: string;
  sourceUrl: string;
  /** トラックリスト（sync-discography による取得後に付与。未取得時は省略） */
  tracks?: Track[];
}

tracks を省略可（optional）にすることで、既存データへの後方互換を維持する。

5. ER 図

→ docs/design/er-diagram.mdx を参照すること。

本設計で追加される Track エンティティの位置づけは ER 図の「v0.5.0 完成時点」セクションに記載。 Playlist / PlaylistEntry との関係は「v0.6.0 完成時点・全体」セクションに記載。

6. releases.json スキーマ変更

変更前

{
  "releases": [
    {
      "id": "...",
      "title": "LOVEマシーン",
      "releaseDate": "1999-09-09",
      "format": "single",
      "source": "musicbrainz",
      "sourceUrl": "https://musicbrainz.org/release/..."
    }
  ]
}

変更後（tracks フィールド追加例）

{
  "releases": [
    {
      "id": "fcd58b7d-77c0-37db-9334-5f50d92b09f1",
      "title": "LOVEマシーン",
      "releaseDate": "1999-09-09",
      "format": "single",
      "source": "musicbrainz",
      "sourceUrl": "https://musicbrainz.org/release/fcd58b7d-77c0-37db-9334-5f50d92b09f1",
      "tracks": [
        {
          "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "mbTrackId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
          "trackNumber": 1,
          "title": "LOVEマシーン",
          "length": 273000
        },
        {
          "id": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
          "mbTrackId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
          "trackNumber": 2,
          "title": "ザ☆ピ〜ス！",
          "length": 262000
        }
      ]
    }
  ]
}

7. PlaylistEntry への影響

playlists.json の各エントリには既に releaseId（任意）が存在する。 tracks の追加後、trackId を追加して楽曲を一意に特定できるようにする。

{
  "memberId": "makino-maria",
  "releaseId": "fcd58b7d-77c0-37db-9334-5f50d92b09f1",
  "trackId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "songTitle": "LOVEマシーン",
  "links": []
}

trackId を任意とする理由: tracks データが未取得のリリースや、プレイリスト上の楽曲が特定リリースに紐付かないケース（ライブ音源等）に対応するため。

8. マルチディスク対応方針

アルバム等の複数ディスク構成（CD1・CD2）は discNumber フィールドで区別する。

• discNumber は省略可。省略時は 1 とみなす
• trackNumber はディスク内での連番（1始まり）
• ソート順: discNumber ASC, trackNumber ASC

9. 既存データへの影響

10. バージョン位置づけ

v0.5.0 の完成をもってプレイリスト機能（v0.6.0）の前提基盤が整う。

11. 後続 Issue との関係

改訂履歴