プレイリストリンク修正 運用ドキュメント

概要

scripts/playlist-link.ts は、プレイリスト楽曲の YouTube・YouTube Music リンクを手動で確認・修正するための CLI スクリプト。 自動取得（sync-playlist-links / sync-discography）が誤ったリンクを設定した場合や、リンク未取得のままになっている楽曲に手動で正しいリンクを設定する際に使用する。

前提条件

必要な環境変数

ローカル実行時は .env.local に設定する。

注意: --search は YouTube を検索するだけで書き込みは行わない。YOUTUBE_API_KEY のみ必要。 リンクの修正（--video-id）を行うと Neon の TrackLink テーブルが上書きされる（同タイプの既存リンクを削除してから新規作成）。

使い方

ヘルプを表示する

bun scripts/playlist-link.ts --help

プレイリスト一覧を表示する

プレイリスト ID・名前・楽曲数・trackId 設定済み数を一覧表示する。

PLAYLISTS_BLOB_URL=<url> bun scripts/playlist-link.ts --list

出力例:

プレイリスト一覧 (3 件):

  ID: playlist-abc123
  名前: 山田花子 選曲プレイリスト
  楽曲数: 10 件 (trackId 設定済み: 8 件)

  ID: playlist-def456
  名前: 鈴木一花 選曲プレイリスト
  楽曲数: 5 件 (trackId 設定済み: 5 件)

プレイリストの楽曲とリンクを確認する

指定プレイリストの全楽曲と現在設定されているリンク（Track.links から解決）を表示する。

PLAYLISTS_BLOB_URL=<url> DATABASE_URL=<neon-connection-string> \
  bun scripts/playlist-link.ts --playlist <playlist-id> --show

出力例:

山田花子 選曲プレイリスト (playlist-abc123)

  LOVEマシーン
    [youtube-music] https://music.youtube.com/watch?v=XXXXXXXXX
    [youtube] https://www.youtube.com/watch?v=XXXXXXXXX
  ダイナマイト
    リンクなし
  青春Night
    リンクなし（trackId 未設定）

trackId 未設定 の場合は sync-playlist-track-ids で紐付けを先に行うこと。紐付け済みでリンクのみ未設定の場合は --search → --video-id で手動設定できる。

YouTube を検索して候補を確認する

YouTube を検索して上位 5 件の動画タイトルと video ID をクリッカブルリンクで表示する。Blob への書き込みは行わない。

YOUTUBE_API_KEY=<key> bun scripts/playlist-link.ts --search "LOVEマシーン モーニング娘。"

出力例:

YouTube を検索中: "LOVEマシーン モーニング娘。"

  LOVEマシーン (MV)
  video-id: XXXXXXXXX  https://www.youtube.com/watch?v=XXXXXXXXX

  モーニング娘。'24 LOVEマシーン（ライブ映像）
  video-id: YYYYYYYYY  https://www.youtube.com/watch?v=YYYYYYYYY

リンクを修正する

指定楽曲の Track.links を video ID で上書き修正し、Neon の TrackLink テーブルに保存する。

PLAYLISTS_BLOB_URL=<url> DATABASE_URL=<neon-connection-string> \
  bun scripts/playlist-link.ts \
    --playlist <playlist-id> \
    --song "LOVEマシーン" \
    --video-id XXXXXXXXX \
    [--type youtube-music]   # 省略時は youtube-music

--type には youtube-music（デフォルト）または youtube を指定する。

出力例:

プレイリスト: 山田花子 選曲プレイリスト (playlist-abc123)
楽曲: "LOVEマシーン"
タイプ: youtube-music
  変更前: (未設定)
  変更後: https://music.youtube.com/watch?v=XXXXXXXXX

Neon への書き戻しが完了しました。

典型的な修正フロー

ケース1: リンクが誤って設定されている

1. --list でプレイリスト ID を確認する
2. --playlist <id> --show で現在のリンクを確認し、誤っている楽曲を特定する
3. --search "<楽曲タイトル> モーニング娘。" で正しい video ID を探す
4. --playlist <id> --song "<タイトル>" --video-id <ID> --type <タイプ> で修正する
5. 再度 --show で修正結果を確認する

ケース2: リンクが未設定のまま

1. --list で trackId 設定済み 数と 楽曲数 を比較し、差がある場合は先に sync-playlist-track-ids を実行する
2. --show でリンクなし（ただし trackId 設定済み）の楽曲を確認する
3. --search で video ID を探して --video-id で設定する

データの反映について

修正コマンド（--video-id）を実行すると Neon の TrackLink テーブルが即時更新される。ランタイムのリリース詳細・曲詳細画面は lib/releases.ts の fetchReleasesFromDB() / getReleases() 経由で Neon を参照するため、追加のコミット・デプロイは不要。

関連ファイル