playlist-sync

Apple Music ↔ YouTube Music 雙向播放清單差異同步工具。

功能

• 支援 Apple Music → YT Music 和 YT Music → Apple Music 兩個方向
• 差異同步（只新增/刪除差異部分，不重建清單）
• ISRC 精確比對 + title/artist 模糊比對 fallback
• --dry-run 模式：只顯示差異，不執行任何寫入

---

環境需求

• Python 3.10+
• uv 套件管理器

---

安裝

git clone <repo-url>
cd playlist-sync
uv sync

---

設定

複製範本並填入你的金鑰：

cp .env.example .env

Apple Music 設定

需要兩個憑證：

1. Developer Token（JWT）

1. 登入 Apple Developer Portal
2. 前往 Certificates, Identifiers & Profiles → Keys
3. 建立新 Key，勾選 MusicKit
4. 下載 .p8 私鑰檔案（只能下載一次）
5. 記下 Key ID 和你的 Team ID（右上角帳號頁面可查到）

填入 .env：

APPLE_KEY_ID=你的 Key ID（10 位英數字）
APPLE_TEAM_ID=你的 Team ID（10 位英數字）
APPLE_PRIVATE_KEY_PATH=/絕對路徑/AuthKey_XXXXXXXXXX.p8

2. Music User Token（MUT）

MUT 代表使用者對 Apple Music 個人資料庫的授權，無法由程式自動取得，需手動從瀏覽器擷取。

取得步驟：

1. 打開瀏覽器，前往 music.apple.com 並登入
2. 開啟開發者工具（F12）→ Application 標籤 → Cookies
3. 找到 music.apple.com 的 cookie，尋找名為 media-user-token 的值

或使用 MusicKit JS（較可靠）：

1. 打開開發者工具 Console
2. 執行：

MusicKit.getInstance().musicUserToken

3. 複製回傳的 token 字串

填入 .env：

APPLE_MUSIC_USER_TOKEN=你取得的 token

⚠️ MUT 有效期約數個月，過期後需重新取得。

---

YouTube Music 設定

使用 ytmusicapi OAuth 認證：

uv run ytmusicapi oauth

依照指示完成授權後，會在當前目錄產生 oauth.json。

預設路徑即為 oauth.json，若需自訂：

YTMUSIC_OAUTH_JSON_PATH=/你的路徑/oauth.json

---

使用方式

列出播放清單

# 列出兩個平台的播放清單
uv run python main.py list-playlists --platform both

# 只列 Apple Music
uv run python main.py list-playlists --platform apple

# 只列 YouTube Music
uv run python main.py list-playlists --platform ytmusic

同步播放清單

# 先用 dry-run 預覽差異（不執行寫入）
uv run python main.py sync \
  --direction apple-to-yt \
  --source "我的最愛" \
  --target "My Favorites" \
  --dry-run

# 確認無誤後執行真實同步
uv run python main.py sync \
  --direction apple-to-yt \
  --source "我的最愛" \
  --target "My Favorites"

# 只新增不刪除
uv run python main.py sync \
  --direction apple-to-yt \
  --source "我的最愛" \
  --target "My Favorites" \
  --no-remove

同步方向

--direction 值	說明
apple-to-yt（預設）	Apple Music → YouTube Music
yt-to-apple	YouTube Music → Apple Music
bidirectional	雙向同步

---

開發

執行單元測試

uv run pytest tests/

執行整合測試（會打真實 API）

⚠️ 需先在兩個平台手動建立名為 [TEST] playlist-sync 的測試清單

INTEGRATION_TEST=1 uv run pytest tests/ -m integration

---

已知限制

• Apple Music 刪除功能：Apple Music REST API 無官方的刪除播放清單歌曲端點，此功能行為需實測確認。若不支援，刪除操作將回報於同步報告的 Failed 區段。
• ISRC 可用性：部分歌曲（獨立廠牌、地區限定）可能無 ISRC，將 fallback 至模糊比對。
• ytmusicapi 非官方：YouTube Music 無官方 API，ytmusicapi 可能因 YT Music 更新而失效。