NeptuneHub/AudioMuse-AI

AudioMuse‑AI – AI驅動的音樂庫探索工具

是什麼 – 一個開源、自架設的應用程式，分析您個人音樂收藏中檔案的實際音訊內容（不依賴標籤或外部API）。它為每首歌曲建立「聲學指紋」，並將結果儲存在 PostgreSQL 資料庫中。利用這些指紋，它可以自動聚類音色相似的歌曲，產生情緒導向的即時播放清單，將整個音樂庫映射到2D視覺化畫布上，並能回應自然語言查詢，例如 「高節奏、低能量的音樂」。

為何重要 – 多數音樂管理工具依賴元資料（藝術家、流派等），但這些資訊經常遺漏或不準確。AudioMuse‑AI 直接分析實際聲音，因此能發現歌曲之間的隱藏關係，並創建反映音樂「感受」而非標籤的播放清單。

---

核心功能（詳見 README）

功能	你將獲得
多伺服器支援（v3.0.0+）	可將 Navidrome、Jellyfin、LMS、Lyrion、Emby 或 Plex 的任意組合連接到單一 AudioMuse‑AI 實例。重複檢測確保每個實體檔案僅分析一次。
聚類與音樂地圖	自動將音色相似的歌曲分組，並提供2D視覺化地圖，讓您按「聲音區域」探索您的收藏。
即時播放清單	向AI描述一個情境（例如 高節奏、低能量），即可獲得即時生成的播放清單。
基於相似歌曲的播放清單	選擇一首喜愛的歌曲，即可獲得包含所有共享其聲學特徵的歌曲的發現型播放清單。
歌曲路徑	生成一條連接任意兩首歌曲的聆聽旅程，中間穿插音色平滑過渡的歌曲。
聲學指紋 / 聽歌習慣播放清單	系統會追蹤你的播放行為，可推薦符合你個人聽歌偏好的歌曲。
歌曲煉金術	提供互動式「新增/移除」介面，微調氛圍，預覽結果在2D地圖上的變化，並將最終清單推送到媒體伺服器。
文字與歌詞搜尋	可按情緒、樂器、流派或歌詞內容搜尋（支援72種語言）。
錄音搜尋	上傳或錄製一段20秒的音訊片段，即可在你的音樂庫中查找匹配的歌曲，或定位已知歌曲的其他錄音版本。

---

架構概覽

• Flask Web UI – 提供瀏覽器介面、Swagger API文件，並處理認證（JWT Cookie）。
• 工作容器 – 執行繁重的音訊分析和聚類任務；可在CPU上執行，或可選地在NVIDIA GPU上執行（常規 -nvidia 鏡像或實驗性 -nvidia-arm）。
• PostgreSQL v15 – 儲存指紋、聚類結果、使用者設定和任務佇列（v2.6起，佇列從Redis遷移至PostgreSQL）。
• 外掛系統 – 簡單的外掛系統允許第三方擴充功能加入；外掛持久化儲存在Flask與工作容器共用的卷中。
• 部署方式 – 提供 Docker-Compose、Kubernetes用Helm圖表，以及macOS、Linux（deb/rpm）和Windows的原生二進位包。

---

快速入門（Docker路徑）

1. 克隆倉儲並複製範例環境檔案：

   cp deployment/.env.example deployment/.env
   

2. 編輯 .env（至少設定 POSTGRES_PASSWORD）。
3. 啟動堆疊：

   docker compose -f deployment/docker-compose.yaml up -d
   

4. 打開 http://localhost:8000 → 運行 Setup Wizard → 開始對你的媒體伺服器進行分析。
5. 完成後，探索UI中的聚類、音樂地圖、即時播放清單等功能頁面。

---

原生（非容器）安裝

• macOS（Apple Silicon） – 下載 AudioMuse‑AI-arm64.zip，移除系統限制標誌，執行封裝的應用程式。
• Linux – 安裝 .deb 或 .rpm（x86_64 或 aarch64）。服務可透過 audiomuse‑ai start 啟動，或作為使用者systemd單元啟用。
• Windows – 解壓便攜歸檔檔案並執行 AudioMuse‑AI.exe start。

所有原生套件均內建 嵌入式 PostgreSQL 實例，無需外部資料庫。

---

硬體與效能說明

• 最低配置：支援AVX2的4核心CPU（或任何近期ARM），8GB RAM，NVMe SSD。
• GPU加速為可選；-nvidia 鏡像使用CUDA加速分析與聚類。實驗性 -nvidia-arm 鏡像針對DGX Spark類ARM GPU。
• 虛擬機必須暴露主機的AVX2指令；無AVX2支援的QEMU將導致服務中止。

---

可擴充性與社群

• 外掛 – 詳見 docs/PLUGIN.md；公開目錄位於 github.com/NeptuneHub/AudioMuse-AI-plugins。
• Helm圖表 – AudioMuse‑AI‑helm 倉儲提供Kubernetes部署的即用型Helm圖表（AMD64與ARM64支援）。
• 貢獻指南 – 詳見 CONTRIBUTING.md；項目歡迎程式碼、文件與外掛貢獻。
• 托管雲選項 – Elestio為不願自架設的使用者提供托管版本。

---

發布亮點（最新）

• v3.3.0 – 新增針對ARM架構NVIDIA GPU的實驗性 -nvidia-arm 鏡像。
• v3.2.0 – 將任務佇列切換至PostgreSQL，不再需要Redis。
• v3.0.0 – 引入多伺服器支援並具備重複檢測功能。
• v2.6.0 – 正式推出外掛系統。
• v2.5.0 – 新增Plex整合。

---

總結

AudioMuse‑AI 是一款真正的AI驅動音樂庫工具：它提取聲學特徵，建立嵌入向量，並利用這些向量實現聚類、相似性搜尋、自然語言播放清單生成與視覺化探索。此專案完全開源，提供多種部署模式（Docker、Kubernetes、原生二進位），並與主流自架設媒體伺服器整合。