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

## 概要

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

---

## 前提条件

### 必要な環境変数

| 環境変数 | 用途 | 必須モード |
| -------- | ---- | ---------- |
| `PLAYLISTS_BLOB_URL` | プレイリストデータの取得元 Blob URL | `--list` / `--show` / 修正（`--video-id`） |
| `DATABASE_URL` | リリースデータの取得元 Neon 接続文字列（`lib/prisma.ts` 経由） | `--show` / 修正（`--video-id`） |
| `YOUTUBE_API_KEY` | YouTube Data API v3 キー | `--search` のみ |

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

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

---

## 使い方

### ヘルプを表示する

```bash
bun scripts/playlist-link.ts --help
```

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

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

```bash
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` から解決）を表示する。

```bash
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 への書き込みは行わない。

```bash
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` テーブルに保存する。

```bash
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 を参照するため、追加のコミット・デプロイは不要。

---

## 関連ファイル

| ファイル | 説明 |
| -------- | ---- |
| `scripts/console/playlist-link.ts` | スクリプト本体 |
| `scripts/workflow/sync-playlist-links.ts` | YouTube リンク自動取得スクリプト |
| `.github/workflows/sync-playlist-links.yml` | 自動リンク取得ワークフロー |
| `lib/releases.ts` | Neon からのリリース取得（`fetchReleasesFromDB()`） |