_
________________( )_____
.-' o `-.
.' . \
/ | ,-"
| ____.'--'
\ __.-'
`.| |`----------'| |'
|__| |__|
一支住在終端機裡的音樂 CLI。搜尋、遙控播放,把 Spotify、Apple Music 與 YouTube Music 的播放清單同步到你自己的 Google Drive。
三個步驟,由下而上:先讓 capy 能碰到你的音樂平台,再決定要不要把清單同步到雲端。capy 的介面預設是英文;要中文的話,先執行 capy config set language zh-TW。
capy 不代持任何人的憑證,所以 Spotify 那一半要用你自己的 app。到 Spotify Developer Dashboard 建一個,把 redirect URI 設成 http://127.0.0.1:8888/callback。這裡必須是 127.0.0.1,寫 localhost Spotify 會拒絕。
$ capy auth login spotify
# 精靈會問 client ID,然後開瀏覽器完成授權
不需要其他設定就能開始用。搜尋會直接印出結果,在終端機裡是對齊的表格,在管線裡是乾淨的 TSV。
$ capy search 派對動物
$ capy play 五月天 # 藝人:播熱門歌曲
$ capy now # 現在在播什麼
播放清單的正本存在你自己 Google Drive 的應用程式資料夾裡(只有 capy 看得到,你隨時可以清空)。只有這一步需要登入 Google,而且權限只有三個:身分、電子郵件、應用程式資料夾。
$ capy auth login google
$ capy pl link 通勤 spotify:通勤 # 把平台清單連上來
$ capy pl sync 通勤 # 雙向同步
在終端機裡直接輸入 capy,不帶任何參數。開場的水豚會轉轉耳朵、眨眨眼、把嘴邊的牧草吃短再叼一根。終端機夠大(至少 30 行高)的話牠就留在畫面底部繼續過日子——偶爾眨眼、撥耳朵,隔一陣子吃一根草;打 / 開選單時牠先讓位,執行命令時牠也先讓開。終端機比較小的話,牠大約三秒後定格(按任何鍵可以跳過),之後畫面只有底部四行會變動。不想要任何動畫的話設 CAPY_MOTION=never,牠直接定格、之後一格都不動。不管哪一種,上面那一整片都是終端機自己的捲動區——你打過的命令、它們的輸出、發生過的錯誤都留在那裡,可以往回捲、可以複製。放進管線或 cron 時它仍然只印說明,不會變成一個等你按鍵的程式。
_
________________( )_____
.-' o `-.
.' . \
/ | ,-"
| ____.'--'
\ __.-'
`.| |`----------'| |'
|__| |__|
capy · spotify
> pl list
ID NAME TRACKS
p.b16G4rbSY0DzME 日本都會之聲 -
p.JL68l7EhogEeXd 冬日暖調 -
------------------------------------------------------
▶ 派對動物 · 1:23 / 4:09 · MacBook Pro · 音量 50
> _
space 播放/暫停 · ←→ ±10 秒 · / 命令 · ? 按鍵 · q 離開
capy wiki setup)「現在在播什麼」那一行跟網頁的正在播放列一樣,跟著真正在播的平台走(只有正在播的平台能把它拉走,暫停中的不會;預設平台沒登入或這台電腦不支援播放時,改顯示第一個能用的平台),播放鍵與命令列打的播放命令(pause、next、prev、seek、vol、不帶參數的 play、now)都送給它顯示的那個平台;capy --provider X 把它釘在一個平台。
> pl show 顯示清單內容(不帶參數且在終端機裡會開挑選器)
pl sync 先 pull 再 push 的一輪:一張表、一次確認
------------------------------------------------------
▶ 派對動物 · 1:23 / 4:09 · MacBook Pro · 音量 50
> /pl s_
↑↓ 選 · Tab/⏎ 補齊 · Esc 收起
按 / 開命令選單:打字即時過濾,Tab 或 ⏎ 把命令帶進輸入行讓你補參數。打到完整命令(例如 /pl show 冬日暖調)選單就收起,⏎ 直接執行,開頭的 / 會自動拿掉。選單向上長、壓在捲動區前面,不會插進你的歷程。清單是直接從命令樹長出來的,不是另外維護的一份。
在那一行輸入的命令會重新執行 capy 自己,不是在同一個行程裡跑。所以每個子命令都保有它原本的樣子:該有表格的有表格,該問你確認的會問。清單名有空白時用雙引號,例如 pl show "上班 通勤"。
讀不到播放狀態時,完整的錯誤會印進捲動區留著,底下那行只留一句短的;連續五次讀不到就停止輪詢,按 r 重新連上。命令列在任何情況下都能用——連不上的時候,你最需要的正是它(doctor、auth login)。
capy --web 在你這台電腦上起一個只綁 127.0.0.1 的網頁介面,啟動時印一行帶一次性 token 的網址,在終端機裡會順便替你開瀏覽器(放進管線或背景執行時只印網址)。
打開就是「搬家」:把一個平台的播放清單搬到另一個平台,三步做完。選來源與目的地(每個平台的連接狀態一眼看得到,沒連的可以當場連)→ 挑一個清單、決定建新的還是加進既有的 → 看過要搬哪些歌、確認了才寫入。比對每一首歌的時候有真的進度,搬不過去的歌會逐首列出來。不刪來源、只新增、順序不動;不用付費、沒有曲數上限,因為它在你自己的電腦上用你自己的帳號跑。
先說限制:搬進本機曲庫只能加進既有的 M3U 檔(Spotify、Apple Music 與 YouTube Music 都能建新清單);搬進 Apple Music 的歌會不會同時加進你的資料庫,看你的 Apple Music 設定,而且只能搬進你自己建的清單;搬進 YouTube Music 也只能進你自己建的清單,而且那裡沒有 ISRC,歌只能靠歌名、歌手、時長比對;第一次連接帳號要花幾分鐘(Spotify 要用你自己建的 app、Apple 要自己複製權杖、YouTube Music 要自己複製登入 cookie),換來的是沒有人替你代管憑證。硬碟裡的 M3U 播放清單也可以搬到 Spotify、Apple Music 或 YouTube Music。
其他頁面:我的清單、同步、搜尋、歌曲 wiki(正在播那首歌背後的故事,由你自己的 AI 端點用你的母語寫;見下面「歌曲 wiki」)、帳號;「進階」裡是主控台(跟終端機一樣可以打任何子命令)、ISRC 查詢(一次問三個平台)與診斷。每一頁的底部一直有正在播放列(播放狀態面板):現在放什麼、進度、播放控制,capy now 的內容都在那裡。它跟著真正在播的平台走(只有正在播的平台會把它拉走,暫停中的不會;預設平台沒登入或這台電腦不支援播放時,改顯示第一個能用的平台),控制鈕作用在它顯示的那個平台上;capy --web --provider X 可以把它釘在一個平台。頁面上的每一個動作背後都是一條 capy 命令,主控台留著完整紀錄;要確認的事一律由命令自己問,頁面不會替你按。導覽列裡的語言選單可以切換介面語言:它跑的就是 capy config set language,跟終端機是同一個設定(終端機也會跟著換),換好之後頁面會重新載入。
「我的清單」是你存在 Google Drive 的清單正本:左邊挑一份,右邊是它的歌曲表(高度固定,歌多的時候在表格裡捲,也能在清單裡找歌)。有那個平台對應的歌可以直接用 Spotify 或 Apple Music(macOS;只在你資料庫裡、Apple Music 目錄查不到的歌標「只在資料庫」,不能從這裡播)播放、在 YouTube Music 開啟;這台有資料的歌都可以按「Wiki」在同一頁問這首歌的故事。表格上方畫出這份正本連到哪幾個平台的清單:「同步這份清單」把兩邊的新增、刪除與順序帶過去;還沒連的平台可以「在 Spotify 建一份」或「連到 Spotify 上已經有的清單」(兩份合併,見下面;其他平台同理),對不到的歌可以「找對應」或「逐首決定」。頁面下方按「讀取各平台的清單」,會列出你在這台登入的各平台(不含本機曲庫;M3U 請到主控台用 pl link)上的清單、標出哪幾份已經連著正本,還沒交給 capy 的可以「納入 capy」。同步、找對應、逐首決定,以及加歌、把歌拉進來這幾步,寫入前都由命令列出變更、問你確認,頁面不會替你按;只有兩個第一步不另外問:「在 Spotify 建一份」會先說明要做什麼,按「開始」就直接在那個平台建一份空清單並連上,「納入 capy」一按就直接在 Drive 建一份空的正本並連上。
「同步」從平台上的一份清單出發。最上面常駐三則說明:正本在你的 Google Drive、從哪一份開始都可以、名字只在連的那一刻能不同。「在同步的清單」列出這台電腦上已經連著平台的正本,每一份一顆「同步」,也可以「全部同步」;有連著的平台在這台沒登入時,頁面會先說明,再改成一個平台一個平台同步。下面先挑平台(Spotify、Apple Music、YouTube Music 或本機曲庫),capy 才去讀你在那裡的清單;挑一份就看得到它現在的歌,再依它的狀態給下一步:還沒交給 capy 的可以「納入 capy」,已經連著正本的可以「在 Spotify 建一份」、「連到 Spotify 上已經有的清單」或「同步這份清單」(其他平台同理),跟某份正本同名的可以「連到正本」。「看看這份有沒有重複」只檢查、不改任何東西。第二台電腦還沒有正本的副本時,按「讀回正本」。最下面的「進階」可以直接用正本名稱跑 pull、push、sync、dedup。
連到已經有的清單(合併):先比對兩邊的歌,把那份清單有、正本沒有的歌照它的順序接在正本最後面(正本原有的一首都不動),再把那份清單排成正本的樣子:加歌、換位置、拿掉多出來的份、改成正本的名字。這些改動列成一張表一次確認,取消就什麼都不寫、也不連上;沒把握是不是同一首的,會先問你要不要逐首決定。接著替新接的歌在其他平台找對應,再同步過去。終端機裡是 capy pl link --merge 通勤 apple:<清單 ID>,接著 capy resolve 通勤 與 capy pl sync 通勤。
網頁只在你這台電腦上:只綁 127.0.0.1、不是區網服務,每次啟動產生一次性 token,行程結束網址就失效。憑證不會經過頁面 —— 精靈輸入的 secret 只從瀏覽器送進行程再進 keychain,命令回聲裡的 token 值一律遮成 ***。
一次跑一個命令(第二個會被擋),因為它跟終端機共用同一份 Drive 與本機資料。跑著的時候底部多一列執行狀態:現在在做什麼、跑了多久、它最新印的那一行(比對歌曲時是做到第幾首),旁邊的「中止」隨時可以停(在主控台的命令列按 Ctrl-C 也行);已經答應寫入的命令要按兩次,停在一半可能只寫了一部分。有幾個命令在網頁上不提供:debug 群組、三個 secret flag(請走精靈)、now --watch(看面板就好);capy update 可以跑,但更新完這個網頁行程還是舊版,會要你重啟。
終端機的互動式介面是重新執行 capy 自己,所以每個子命令都保有它原本的樣子;網頁介面則在同一個行程裡跑並由頁面回答提示。兩條路不同是因為終端機已經有 TTY 可以讓給子行程,瀏覽器沒有。
下面按主題分組。每個命令在終端機裡是給人看的表格(放不下時儲存格換行、不截斷,ID 永遠完整;比終端機還寬時先開一個檢視窗格:每列一行,← → 橫向、↑ ↓ 上下、g G 頭尾、q 離開,Ctrl-C 則是中止整個命令;離開後表格以換行的形式留在捲動區。帶 --yes 的命令不開窗格,CAPY_PAGER=never 一律不開),在管線裡是 TSV,可以直接餵給 cut 與 awk。
--provider apple 或 --provider youtube 換平台,--limit 控制筆數。artist: pl: track: 三種,等同 --type。1:05:30,腳本裡用純秒數 83 也可以。--watch 會持續更新並顯示進度條,而且跟著正在播的平台走(--provider 釘住一個)。play --device 指定。apple --create、youtube --create)建一個跟正本同名的私人空清單,直接連上。把清單從別的平台複製過來時用它,不必先去 app 裡建。平台上已經有你自己的同名清單時會擋下,改成告訴你怎麼連它。capy pl dedup apple:冬日暖調 則直接讀平台清單、只印報告(不碰 Drive、不需要連結);要由 capy 去掉,把清單連到正本再用前一種寫法。這一組命令不帶清單名字直接打,在終端機裡會開挑選器讓你選:pl link 問三次(平台 → 那個平台上的哪個清單,在 Spotify、Apple Music 與 YouTube Music 也可以選「建一個新的空清單」 → 連到哪個正本,這一步也可以當場建一個新的),pl unlink 問兩次。接在管線後面或放進 cron 時不會問,照舊要求你把參數寫齊。
none 表示這首在那個平台沒有。--refresh 再問一次;capy wiki 歌名 --artist 歌手 問別的歌;--json 給腳本。結尾一定有一行提醒:AI 產生、可能有錯。網頁裡是「歌曲 wiki」那一頁(「我的清單」裡這台有資料的歌也有一顆「Wiki」,問的是那一首,歌名與歌手取自你 Drive 上的清單正本),互動式介面裡按 w。play --pick 用的)與同步記下的清單曲目也一起刪掉。language):介面預設是英文,capy config set language zh-TW 換成繁體中文,en 換回英文。能力差異來自平台本身,不是 capy 偷懶。差在哪裡,命令會直接告訴你,而不是靜靜跳過。
| 能力 | Spotify | Apple Music | YouTube Music | 本機曲庫 |
|---|---|---|---|---|
| 搜尋 | 可以 | 可以 | 可以 | 曲庫內比對 |
| 播放遙控 | Connect | 只有 macOS;不在資料庫的歌只會在 Music.app 打開 | 不支援 | 不支援 |
| 讀取清單 | 可以 | 可以 | 可以 | M3U 檔案 |
| 寫回清單 | 可以 | 只寫你自己建的清單 | 只寫你自己建的清單 | 可以 |
| 建立清單 | 可以 | 可以 | 可以 | 自己建檔 |
| 憑證來源 | 你自建的 app | 你從網頁播放器複製的權杖 | 你從網頁播放器複製的登入 cookie | 不需要 |
一個命令就好。以 Apple Music 的「公路旅行」複製到 Spotify 為例;來源與目標兩個平台加上 Google 都要先登入(YouTube Music 也能當來源或目標)。
$ capy migrate 公路旅行 --from apple --to spotify # 在 Spotify 建一個同名的私人清單,把曲目搬過去
$ capy migrate 公路旅行 --from apple --to spotify:開車歌單 # 或加進既有的清單:接在它原本的曲目後面
$ capy migrate 公路旅行 --from spotify --to apple # 反方向:在 Apple Music 建一個同名清單,把 Spotify 的曲目搬過去
$ capy migrate 公路旅行 --from spotify --to youtube # 搬到 YouTube Music:在那裡建同名清單;沒有 ISRC,靠歌名、歌手、時長對應
$ capy migrate # 不帶參數:逐段挑選來源、清單、目標
它先列出要搬什麼,你確認後才動手;需要新清單時也是確認之後才建。目標原本的順序是前綴,來源的曲目依來源的順序接在後面;來源裡目標已經有的(同一首歌,或同一個 ISRC)略過。永遠不動來源,對目標也只新增:目標有還沒同步的移除、換序或改名時會先擋下來,請你先 capy pl sync。沒在目標平台找到的歌這次不推,終端機裡可以當場一首一首裁決,否則結尾會給你補上的命令。完成後只有目標連著正本(來源不連結,一次性複製);想之後跟著來源的變動,結尾會給 pl link --merge 加 pl sync 的命令,把正本連到來源那份(來源會排成正本的樣子,先列表給你確認);網頁上是「同步」頁的「連到 X 上已經有的清單」。例外:正本本來就連著來源(手動流程做到一半)時,來源那半也一起拉進正本、以正本為準,結尾會說兩邊都連著。搬進 Apple Music 的曲目會不會同時加進你的 Apple Music 資料庫,看你的 Apple Music 設定(Apple 的行為),而且只能搬進你自己建的清單。
背後在做什麼:讓兩個平台連到同一個正本,再推過去。想讓兩邊持續同步的話,照下面手動做一次,之後就 capy pl sync。
先連 Apple 的清單,正本不存在會自動建立。再用 --create 在 Spotify 建一個同名的私人空清單,連到同一個正本。
$ capy pl link 公路旅行 apple:公路旅行
$ capy pl link 公路旅行 spotify --create
不要帶 --provider:Apple 那邊把曲目拉進正本;Spotify 那邊是空的,只記下這台裝置看過它的樣子。少了這一步,後面的 push 會被擋下來。
$ capy pl pull 公路旅行
有 ISRC 的曲目直接精準比對;沒有的靠標題、藝人、時長模糊比對,分數不夠的排進佇列等你裁決。
$ capy resolve 公路旅行 --provider spotify
$ capy resolve --review # 上一步有列出佇列才需要
表裡的 skip 列是這次複製不過去的曲目:還沒對應到 Spotify 的歌,通常是你自己上傳到 Apple 的,或 Spotify 上根本沒有的。
$ capy pl push 公路旅行 --provider spotify --dry-run
$ capy pl push 公路旅行 --provider spotify
整個過程不會刪到任何東西:Spotify 那邊是第一次拉,推過去的全是新增。之後兩邊保持連結,任一邊有變動時跑 capy pl sync 公路旅行 就會帶過去;只想複製一次的話,用上面的 capy migrate,或完成後 capy pl unlink 公路旅行 apple 解開。反方向(Spotify 到 Apple)一樣:capy migrate 公路旅行 --from spotify --to apple,或把上面的兩個平台對調(capy pl link 公路旅行 apple --create)。
建清單與推曲目是照 Spotify 2026 年 2 月的官方文件實作的,還沒有在真的帳號上跑過。遇到 404,或建出來的清單在 app 裡是公開的,請回報。
硬碟裡的 M3U 檔案也可以當成一個平台,跟 Spotify 雙向同步。它綁在這台機器上:換一台電腦,那邊的 capy 會跳過這個連結,不會把它當成清單被刪掉了。
$ capy config set local_root ~/Music/playlists
$ capy pl link 通勤 local:通勤.m3u8
$ capy pl sync 通勤
曲目的中繼資料放在同一個目錄的 library.json 裡,由你自己維護。有填 ISRC 的曲目才能跟串流平台上的同一首歌自動對上,沒填的就是各自獨立的一首。寫回時是整檔重寫,別的工具寫在 M3U 裡的註解與 #EXTINF 會被蓋掉。
不是在我們的伺服器上,因為沒有伺服器。本機的 SQLite 只是快取:刪掉它,下一次執行會從 Drive 完整重建。
任何會刪掉清單曲目的操作都會先列出來讓你確認,而且超過門檻時會直接擋下來,要加 --force 才放行。--dry-run 可以只看不做。
capy 沒有任何路徑會排序或打亂清單:同步只在平台自己重排時才跟著動,去重只拿掉後出現的那份,沒動到的曲目相對順序永遠不變。唯一的例外是你確認過的 capy pl link --merge 那一張表:把正本連到一份已經有歌的清單時,那份清單會排成正本的順序;正本原有的歌不動,之後任何同步都不會因為合併而重排。
那不是 Apple 官方支援的用法:權杖會過期,這個方法也隨時可能失效,風險由你自己承擔。capy 只會指導你怎麼複製,不會去讀你的瀏覽器 cookie,也不會注入任何指令碼。
加歌走 Apple 文件化的端點;移除、換序、改名走網頁播放器自己用的端點,Apple 沒有正式承諾,哪天改了就會壞。Apple 精選、喜好歌曲、已購買的音樂不能寫,capy 會擋下、零寫入;協作播放清單目前 capy 完全不寫(Apple 對它的整批取代回 500),同步時會跳過那一格並說明;先複製成一般清單再連結通常可以(未實測)。加進清單的曲目會不會同時加進你的 Apple Music 資料庫,看你在 Apple Music 裡的設定,這是 Apple 的行為。移除與換序是整批取代:清單順序一定照正本,Mac 版 Music app 顯示的「加入日期」會不會被重設還沒驗證。
Music app 的腳本介面只能播資料庫裡的曲目,所以你播 Apple Music 的歌時(capy play,或網頁介面的搜尋頁),capy 會先用歌名、歌手、時長在你電腦上的 Music 資料庫裡找,有好幾份時再比專輯。找到唯一一首就直接播,並確認真的開始播了;否則會在 Music app 打開那首歌並標出來,請你在那裡對它點兩下(按播放鍵會播回原本的那首):這時命令一樣回結束碼 0,但不會印 ▶;網頁搜尋頁上 Apple Music 那一列的按鈕叫「在 Music.app 開啟」。capy 不會為了能播而把歌加進你的資料庫。
那不是 Google 官方支援的用法:你貼上的是 Google 帳號在 YouTube 的登入 session(capy 只留三個 session cookie,存在鑰匙圈),拿到它的人能以你的身分操作整個 YouTube;用自動化工具存取 YouTube 也違反它的服務條款,風險由你自己承擔。要撤銷就到 Google 帳號 → 安全性 → 登出所有裝置;Google 也隨時可能讓它失效,失效就再登入一次。capy 只指導你複製,不會讀你的瀏覽器。YouTube Music 的帳號可以跟 Google Drive 用的不同,capy auth status 兩個都會顯示;清單的 id 帶著帳號的頻道 id,換帳號登入後,舊帳號的連結只會被跳過、不會被解除。
喜歡的音樂、自動清單、從別的頻道存進來的清單都只讀。一輪變更就是一個請求:只有新增時接在尾端,否則整份取代(先移除每一列,再照正本的順序加回去;改名也在同一個請求裡),驗到 YouTube 的 5000 首上限;請求是原子的,被拒就是原封不動,但整份取代會重設「加入日期」。YouTube Music 沒有 ISRC,跨平台對應只靠歌名、歌手、時長;同一首歌的純音訊版與 MV 是兩個 id,只有人工決定(capy resolve --review 或 capy resolve pin)能把它們併起來。capy 不會替你播 YouTube Music(網頁搜尋頁那一列只有「在 YouTube Music 開啟」的連結),也絕不刪除 YouTube Music 的清單。
不在終端機的時候一律輸出純文字 TSV,沒有顏色也沒有互動提示。結束碼有意義:0 成功,1 錯誤,2 需要你介入,3 是安全閥擋下來了。pl pull / push / sync、migrate、dedup、resolve 的 TSV 裡,reason 欄是給人看的、跟著介面語言;腳本請看最後一欄 reason_code,它在每種語言都一樣。