NeptuneHub/AudioMuse-AI

AudioMuse-AI uses sonic analysis to rediscover forgotten songs, uncover hidden connections in your music library, and generate intelligent playlists for Navidrome, Jellyfin, LMS, Lyrion, Emby and Plex: no metadata or external services required.

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路径）

克隆仓库并复制示例环境文件：

cp deployment/.env.example deployment/.env

编辑 .env（至少设置 POSTGRES_PASSWORD）。

启动堆栈：

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

打开 http://localhost:8000 → 运行 Setup Wizard → 开始对你的媒体服务器进行分析。
完成后，探索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、原生二进制），并与主流自托管媒体服务器集成。