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

最終更新: 2026-11-07

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 の全要素を結合句つきで連結した名義（例: `MIMI feat. モーニング娘。`）。sync-discography で自動設定 */
  artist?: string;
  /** 主体のいずれかが広義のユニット（ユニットまたは音楽グループ）に解決できた場合の広義のユニット ID（units.json または groups.json の id と一致）。sync-discography で自動設定 */
  unitId?: string;
  /** MusicBrainz artist-credit の主体のうち先頭のアーティストの MBID。sync-discography で自動設定 */
  artistMbid?: string;
}

名義（artist-credit）の解釈

MusicBrainz の artist-credit は、アーティスト・クレジット表記名（name）・次の要素との結合句（joinphrase）の並びで1つの名義を表す。たとえば MIMI feat. モーニング娘。 は、MIMI（結合句 feat.）と モーニング娘。 の2要素で1つの名義である。sync-discography は結合句を読み取り、名義・主体・客演を次のとおり扱う（実装: lib/musicbrainz.ts）。

ユニット名と一致する並びのまとめ方: 客演でないアーティストの並びを先頭から見ていき、各位置から始まる連続した2人以上のアーティストのクレジット表記名を、間の結合句ごと連結する（並びの最後のアーティストの後ろの結合句は含めない）。連結した文字列がユニット名（Unit.name）と一致すれば、その並びを1つの主体にまとめ、並びの次のアーティストから続きを見る。同じ位置から始まる並びが複数一致する場合は、長い並びを採る。比較は、連結した文字列とユニット名の両方に次の正規化をしてから行う。同じ名義でも曲によって表記が異なるため（例: 「仔犬ダンの物語 オリジナルサウンドトラック」の「がんばっちゃえ!」は ＋、「がんばっちゃえ! (Symphonic Version)」は +、No.5 の「がんばっちゃえ!」は ハロー！プロジェクト・キッズ＋ と ！ も全角）。

• Unicode の NFKC 正規化で、全角の英数字・記号（！・＋・？・＆ 等）と全角スペースを半角にする
• 空白（半角スペース）を取り除く

まとめた主体のクレジット表記名は、一致したユニット名とする（ユニットへの紐づけは ユニット一覧機能 データ設計書 §6）。ソロアーティストへの紐づけでは、まとめた主体を、並びを構成する各アーティストの MBID でも照合する（ソロアーティスト データ設計書 §6-2）。

ユニット・ソロアーティストへの紐づけは主体で行う（ユニットは バッチ設計書 W2「ユニット照合」、ソロアーティストは ソロアーティスト データ設計書 §6-2）。連名の2番目以降を含む主体の全アーティストは、sync-discography の実行中にだけ保持し、Track には保存しない。

備考: 従来は結合句を読まずに先頭要素だけを artist・artistMbid として保存していたため、モーニング娘。が客演のみの名義（MIMI feat. モーニング娘。）が MIMI として保存され、モーニング娘。のリリースと区別できなかった（MorningStatusApp#1697）。

トラック単位の補正（data/inputs/track-corrections.json）

MusicBrainz は有志が登録しているデータで、このアプリにとっては収集の手段・ベースである。MusicBrainz の名義から決まるユニット（Track.unitId）が実態と異なるトラックは、補正ファイルで実態のユニットを指定する。手動登録リリース（data/inputs/manual-releases.json）と同じく、リポジトリで管理する JSON ファイルとし、いつ・何を・なぜ補正したかをコミットに残す。

{
  "corrections": [
    {
      "trackId": "<Track.id（recording UUID。手動登録リリースのトラックは手動登録の ID）>",
      "unitId": "<実態の広義のユニットの id（units.json または groups.json の id と一致）>",
      "reason": "<補正の理由（例: CD のクレジットでは〜の名義）>"
    }
  ]
}

• sync-discography は、MusicBrainz からの取得と手動登録リリースのマージの後、ユニットの照合（ユニット一覧機能 データ設計書 §6）で、補正ファイルに登録したトラックは、照合の結果と既存の unitId より優先して、補正ファイルの unitId を Track.unitId にする。実行のたびに適用するため、保存済みのトラックにも当たり、REFETCH_RELEASE_IDS 等で再取得しても補正は保たれる
• trackId に一致するトラックがない場合と、unitId が units.json にも groups.json にも存在しない場合は、警告をログに出し、その補正を適用しない
• 補正が必要なトラックは、sync-discography が出力する登録揺れの候補（バッチ設計書 W2）から見つける

トラックの保存先リリース（複数のリリースに載る曲）

同じ録音（Track.id。recording UUID）が複数のリリースに載る場合、Track はそのうち1つのリリースにだけ保存する。保存先は、リリースの形式（Release.format）の優先度が最も高いもの（single > album > ep > compilation > live > soundtrack > other）とする。シングルの曲が、ベスト盤やコレクションではなく、シングルの収録曲になるようにするため。

• 保存先にならなかったリリースは、収録曲のすべてが他のリリースに保存されることがあり、その場合は Track が0件のリリースとして保存される（ベスト盤・コレクション〈ハワイ限定盤を含む。いずれも compilation〉、サウンドトラック〈soundtrack〉等）。欠落ではなく、削除の対象でもない
• 取り込みルールで取り込まないと判定されるリリース（映像のみのライブ映像・映像作品。バッチ設計書 W2「MusicBrainz API」）とは原因が異なる。Track が0件のリリースは、MusicBrainz に収録曲があり、その曲が他のリリースに保存済みなら残す
• 再取得（REFETCH_RELEASE_IDS 等）をしても、保存先は変わらないため、0件のままになる

リリース・トラックの除外（data/inputs/discography-exclusions.json）

MusicBrainz に登録されていても、このアプリの対象外とするリリース・トラックを、除外ファイルで指定する。トラック単位の補正と同じく、リポジトリで管理する JSON ファイルとし、いつ・何を・なぜ除外したかをコミットに残す。

{
  "releases": [
    {
      "releaseId": "<Release.id（リリースグループ ID）>",
      "title": "<リリース名（ファイルを読む人のための控え）>",
      "reason": "<除外の理由（例: 歌なしの音源。MusicBrainz の注記で確認）>"
    }
  ],
  "tracks": [
    {
      "trackId": "<Track.id（recording UUID）>",
      "title": "<曲名（ファイルを読む人のための控え）>",
      "reason": "<除外の理由（例: モーニング娘。のメンバーではないアーティストの歌唱）>"
    }
  ]
}

• sync-discography は、除外ファイルに登録したリリース・トラックを、取得したデータから外してから照合・保存する（バッチ設計書 W2「リリース・トラックの除外」）。実行のたびに適用するため、REFETCH_RELEASE_IDS 等で再取得しても取り込まれない
• 項目が欠けているものは、警告をログに出し、その除外を適用しない
• 除外ファイルに登録する前から保存されているリリース・トラックは、sync-discography では消えない（保存は追加・更新だけのため）。一回限りのパッチで消す（バッチ設計書「一回限りパッチ一覧」）
• 除外するかは、登録揺れの候補（バッチ設計書 W2）を確認して判断する。対象外とする例: 歌なしの音源（オルゴール等）のリリース、正規のリリースか確認できないリリース、モーニング娘。のメンバーではないアーティストの歌唱のトラック

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 との関係

改訂履歴