Nightingale — Karaoke from your music library
Nightingale 是一款開源的 AI 卡拉 OK 應用程式，只要丟入任何歌曲，它就能自動分離人聲與伴奏、產生逐字歌詞，變成一個完整的卡拉 OK 體驗。
Rust + Bevy 遊戲引擎作為前端，Python + PyTorch 作為 AI 後端，兩者透過 JSON IPC 溝通。
主要功能
- AI 人聲分離 — 使用 UVR Karaoke 模型或 Meta 的 Demucs 自動將歌曲拆成伴奏與人聲，可調整導唱音量
- 自動歌詞產生 — 透過 WhisperX 逐字轉錄並對齊時間戳，或從 LRCLIB 線上歌詞庫抓取現成歌詞，不過WhisperX對歌詞的效果說不上好，最好還是LRCLIB 上有timestamp的歌詞檔
- 即時音高評分 — 麥克風收音即時與原唱音高比對，給予星級評分
- 多人檔案系統 — 支援建立多個使用者檔案，各自追蹤每首歌的最佳成績與排行榜
- 影片與動態背景 — 支援 MP4 等影片作為背景，另有 7 種 GPU 著色器特效（Plasma、Aurora、Waves、Nebula、Starfield 等）
- 遊戲手把支援 — 用手把就能操作所有功能
- 單一執行檔部署 — 下載一個 exe，首次啟動自動安裝所有依賴，理論上是這樣，但我失敗了
- 廣泛格式支援 — MP3、FLAC、OGG、WAV、M4A、AAC、WMA，以及 MP4、MKV、AVI、WebM 等影片格式
- 跨平台 — Windows、macOS、Linux 都能用
運作原理
┌─────────────────────────────────────────┐
│ Rust + Bevy 遊戲引擎 │
│ 啟動 → 掃描音樂庫 → 選歌 → 即時播放 │
│ （音訊播放、歌詞同步、麥克風、評分） │
└──────────────┬──────────────────────────┘
│ stdin/stdout JSON 通訊
┌──────────────▼──────────────────────────┐
│ Python AI 分析伺服器 │
│ 人聲分離 → 歌詞轉錄 → 時間對齊 │
└─────────────────────────────────────────┘
首次播放一首歌時，Rust 主程式會呼叫 Python 後端進行分析，產出三個快取檔案：
檔案內容*_instrumental.ogg伴奏（去人聲）*_vocals.ogg人聲*_transcript.json逐字歌詞與時間戳
之後播放同一首歌就直接讀取快取，畫面、字幕、音高評分全部由 Bevy 引擎即時渲染，不會產出影片檔。
安裝踩坑紀錄
理論上只要下載一個 exe 就能用，但實際在 Windows 上安裝的過程踩了不少坑。
坑 1：安裝路徑寫死在 C 槽
所有資料（FFmpeg、Python、PyTorch、ML 模型等）一律存放在 C:\Users\<帳號>\.nightingale\，完全沒有任何選項可以更改。我的 C 槽空間已經不多了，而完整安裝大約需要 5～15 GB。
解法：用 Windows 的目錄連接（Junction）把路徑導到其他磁碟：
mklink /J "C:\Users\<帳號>\.nightingale" "E:\nightingale-data"
程式以為在寫 C 槽，實際上所有資料都存到了 E 槽。
坑 2：torch 版本太舊，安全漏洞導致直接報錯
首次啟動的自動安裝流程裝的是 torch 2.5.1+cu121，但最新的 transformers 套件因為 CVE-2025-32434（torch.load 的嚴重安全漏洞）要求至少 v2.6，直接噴出錯誤：
ValueError: Due to a serious vulnerability issue in `torch.load`, even with
`weights_only=True`, we now require users to upgrade torch to at least v2.6
坑 3：升到 2.6 還不夠，WhisperX 要求 2.8
以為升到 torch 2.6 就好了？沒有。WhisperX 3.8.2 的依賴寫的是 torch~=2.8.0，升到 2.6 之後又跳其他依賴錯誤，修了 A 壞了 B。
而且 CUDA 12.1 的 PyTorch wheel 倉庫根本沒有 2.8 版，必須換到 CUDA 12.8 (download.pytorch.org/whl/cu128) 才行。
坑 4：跨磁碟安裝造成 metadata 損壞
因為我用了 Junction 把資料導到 E 槽，uv 套件管理器的 hardlink 在跨磁碟時會失敗。雖然它會 fallback 到 copy 模式，但過程中 torch 的 package metadata 損壞了，importlib.metadata.version('torch') 直接回傳 None：
TypeError: expected string or bytes-like object
這個錯誤訊息完全看不出跟 metadata 有關，找了好一陣子，雖然負責找的人是claude code 不是我
坑 5：重裝時 uv 從 PyPI 抓了 CPU 版的 torch
決定砍掉 venv 重建，一次裝好所有套件。但同時指定 --index-url cu128 和 --extra-index-url pypi 時，uv 竟然優先從 PyPI 拉了 CPU 版的 torch（沒有 CUDA 支援），導致 GPU 完全無法使用。
坑 6：日文歌詞辨識品質極差
好不容易裝好了，拿日文歌測試，結果歌詞辨識慘不忍睹。LRCLIB 沒有收錄這首歌的歌詞，回退到 WhisperX 自動轉錄後，日文對齊模型把歌詞拆成了一個一個字母：
{ "word": "I" }, { "word": "j" }, { "word": "u" }, { "word": "s" }, { "word": "t" }
原本應該是完整的日文歌詞，結果變成一堆毫無意義的單字母，不過這算是預想範圍內本來就不覺得whisper對唱歌的辨識度會高到哪裡去
最終解法
- 用
mklink /J建立 Junction 解決路徑問題 - 砍掉整個 venv 重建
- 先從 PyPI 安裝所有套件（一次解析完依賴）
- 再單獨從
download.pytorch.org/whl/cu128reinstall torch 三件套，並加上--link-mode=copy避免跨磁碟的 metadata 損壞
# 步驟 1：從 PyPI 一次裝好所有套件
uv pip install "torch==2.8.0" "torchaudio==2.8.0" "torchvision==0.23.0" \
"whisperx>=3.8.0" "demucs>=4.0.0" "soundfile" "huggingface_hub>=0.27.0" \
"audio-separator[gpu]>=0.25" "cython" "setuptools" \
--index-url https://download.pytorch.org/whl/cu128 \
--extra-index-url https://pypi.org/simple \
--link-mode=copy
# 步驟 2：單獨重裝 torch CUDA 版（蓋掉 PyPI 的 CPU 版）
uv pip install --reinstall "torch==2.8.0" "torchaudio==2.8.0" "torchvision==0.23.0" \
--index-url https://download.pytorch.org/whl/cu128 \
--link-mode=copy
總結
雖然我在安裝上花了一點時間，但Nightingale 的功能設計很棒——單一執行檔、AI 人聲分離、即時卡拉 OK，概念上非常吸引人，還有導唱功能。
日文歌詞辨識的部分則是 WhisperX 上游的限制，不完全是 Nightingale 的問題，但如果能加入手動匯入 LRC 歌詞檔的功能會好很多。
