Lyrc

在桌面上即時顯示 Spotify 同步歌詞的透明覆蓋視窗。專為 Fedora + KDE Plasma（Wayland） 設計，Python + PyQt6 實作。

特色

• 雙行同步歌詞：目前唱到的一行（白邊黑字、較大）+ 下一行預覽（白邊灰字、較小）
• 描邊字渲染：卡拉OK 式白色外輪廓文字，無底框、無視窗感 — 桌面上只看得到浮動的字
• 點擊穿透：平常視窗完全不攔截滑鼠，點擊直接落到下層視窗
• 拖移模式：從系統匣切換後可拖曳移動、縮放視窗，關閉後自動記住位置
• 雙歌詞來源 + 自動備援：
  • Spotify（預設）— 與 Spotify App 內完全一致的官方同步歌詞，需要 sp_dc cookie
  • lrclib.net — 免費開放的歌詞資料庫，無需任何認證
  • 偏好來源找不到歌詞時自動切換到另一個；換歌後自動回到偏好來源
  • 系統匣選單可切換偏好來源，並即時顯示「目前使用」哪個來源
• 系統匣整合：透明度、字級、歌詞來源、開機自動啟動、登入/登出都在 tray 選單
• 繁體中文優先：明確指定 Noto Sans CJK TC 字型
• Token 自動更新：登入一次後自動續期

執行環境

目前僅在 Linux（Fedora 44 + KDE Plasma + Wayland）上實際測試。

理論上可支援其他 Linux 桌面環境，但需符合以下條件：

• 安裝 XWayland
  • 程式啟動時會設定 QT_QPA_PLATFORM=xcb，強制使用 XWayland。
  • Overlay 視窗的 Always-on-top、Click-through、視窗定位與拖曳 等功能皆依賴 X11 Window Manager 行為，因此需要 XWayland。
• 支援標準 X11/Qt Window Flags 的 Window Manager
  • KDE Plasma 已驗證可正常運作。
  • GNOME、XFCE、i3、Sway 等理論上可使用，但不同 Window Manager 對 Always-on-top、Click-through 等功能的實作可能略有差異。
• 若需要系統匣圖示
  • 桌面環境需支援 StatusNotifierItem (SNI) / QSystemTrayIcon
  • KDE、XFCE 可直接使用。
  • GNOME 需額外安裝 AppIndicator / KStatusNotifierItem 擴充套件。
• 若需要開機自動啟動
  • 系統需支援標準 XDG Autostart
  • 程式會建立 ~/.config/autostart/*.desktop

安裝

sudo dnf install python3-pip python3-pyqt6 python3-pyqt6-base

或用 pip 安裝 requirements.txt（PyQt6、requests）：

pip install -r requirements.txt

設定

1. Spotify API 憑證（Required — 用於讀取播放狀態）

1. 到 https://developer.spotify.com/dashboard 建立 App
2. 複製 Client ID（32 碼十六進位）與 Client Secret
3. 在 App 設定加入 Redirect URI：http://127.0.0.1:8888/callback
4. 寫入 ~/.config/lyrc/config.json：

{
  "client_id": "你的_CLIENT_ID",
  "client_secret": "你的_CLIENT_SECRET",
  "redirect_uri": "http://127.0.0.1:8888/callback"
}

或者複製 .env.example 為 .env 並填入同樣的值——.env 已被 .gitignore 排除，且會覆蓋 config.json 對應欄位，適合當作機密的權威來源。

2. sp_dc cookie（Optional — 用於 Spotify 歌詞來源）

預設歌詞來源是 Spotify 內部歌詞 API，需要你瀏覽器的登入 cookie：

1. 用瀏覽器登入 https://open.spotify.com
2. 開發者工具（F12）→ Storage/應用程式 → Cookies → 複製 sp_dc 的值
3. 加入 config.json 或 .env：SPOTIFY_SP_DC=AQB...你的cookie值

沒設定 sp_dc 也能用：Spotify 來源會靜默失敗，自動改用 lrclib.net。cookie 過期時同理，重新複製一次即可。

執行

python3.14 main.py

首次執行會開啟瀏覽器進行 Spotify OAuth 授權，之後 token 自動快取與續期。

系統匣選單

項目	說明
允許拖移	開：可拖曳/縮放（顯示虛線邊界與縮放把手）；關：點擊穿透
字級 +/-	調整歌詞字體大小
透明度	25% / 50% / 75% / 100%
歌詞來源	切換偏好來源（Spotify / lrclib.net）
目前使用：…	顯示當前曲目實際使用的來源（含自動備援結果）
開機自動啟動	寫入/移除 ~/.config/autostart/ 的 .desktop 檔
登入 Spotify / 登出	OAuth 管理
結束	離開程式

運作原理

1. 每 1.5 秒輪詢 Spotify API 取得目前曲目與播放進度
2. 換歌時在背景執行緒抓取歌詞（偏好來源 → 失敗自動備援）
3. 每 100ms 在本地內插播放進度，平滑推進歌詞行
4. 以 QPainterPath 描邊繪字（白輪廓 + 黑/灰填色），畫布完全透明

專案結構

main.py             # 程式入口
overlay_window.py   # 歌詞覆蓋視窗
spotify_client.py   # Spotify API 與 OAuth
lyrics_provider.py  # 歌詞取得與 LRC 解析
tray_icon.py        # 系統匣與開機自動啟動
config.py           # 設定檔讀寫

建立桌面捷徑（Optional）

建立 ~/.local/share/applications/lyrc.desktop：

[Desktop Entry]
Type=Application
Name=Lyrc
Exec=python3.14 /path/to/lyrics/main.py
Icon=music
Categories=Utilities;
Terminal=false

之後可從應用程式選單啟動。

致謝與技術來源

Spotify 歌詞取得技術參考自開源專案 lyricstify，詳細的技術講解（它如何透過 sp_dc cookie 呼叫 Spotify 內部 color-lyrics API、我們採用與未採用的部分）請見 CREDITS.md。備援歌詞由 lrclib.net 提供。

⚠️ Spotify color-lyrics API 為非公開 API，使用屬個人風險，僅供個人用途。詳見 CREDITS.md。

疑難排解

問題	解法
No module named 'PyQt6'	sudo dnf install python3-pyqt6 python3-pyqt6-base
「Spotify credentials not configured」	檢查 config.json / .env 的 client_id、client_secret
Spotify 來源一直沒歌詞	sp_dc 未設定或已過期，重新從瀏覽器複製；期間會自動改用 lrclib.net
歌詞完全找不到	冷門/純音樂曲目兩個資料庫都可能沒有，會顯示「♪ 找不到歌詞」
登入頁面沒開啟	查看終端輸出的授權 URL 手動開啟
視窗位置/大小無法保存	檢查 ~/.config/lyrc/config.json 的檔案權限（應為 0600）

授權

MIT License — 詳見 LICENSE。可自由使用、修改、散布，但不提供任何擔保。