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 데이터베이스에 저장합니다. 이 지문을 사용해 유사한 곡들을 자동으로 클러스터링하고, 2차원 시각화 캔버스에서 라이브러리를 탐색할 수 있으며, 자연어 질의(예: 고속도, 저에너지 음악)에 응답할 수 있습니다.

왜 중요한가요 – 대부분의 음악 관리 도구는 아티스트, 장르 등 메타데이터에 의존하지만, 이는 종종 누락되거나 정확하지 않습니다. AudioMuse‑AI는 실제 음성에 주목하므로, 곡들 사이의 숨겨진 관계를 발견하고, 곡이 어떻게 느껴지는지에 기반한 플레이리스트를 생성할 수 있습니다.

핵심 기능 (README에 설명됨)

기능	제공되는 기능
다중 서버 지원 (v3.0.0+)	Navidrome, Jellyfin, LMS, Lyrion, Emby 또는 Plex의 임의 조합을 단일 AudioMuse‑AI 인스턴스에 연결 가능. 중복 검출을 통해 각 물리 파일은 한 번만 분석됩니다.
클러스터링 및 음악 맵	음성적으로 유사한 트랙을 자동으로 그룹화하고, "소리 지역"별로 컬렉션을 탐색할 수 있는 2차원 시각화 맵을 제공합니다.
즉시 플레이리스트	AI에 설명(예: 고속도, 저에너지)을 제시하면 실시간으로 플레이리스트를 생성합니다.
유사 곡 기반 플레이리스트	좋아하는 트랙을 선택하고, 그 소리 특징을 공유하는 모든 곡을 포함한 탐색용 플레이리스트를 얻습니다.
곡 경로	임의의 두 곡을 연결하는 청취 여정을 생성하며, 소리가 부드럽게 전환되는 중간 트랙을 포함합니다.
소닉 지문 / 청취 습관 기반 플레이리스트	사용자가 재생하는 내용을 추적하고, 개인의 청취 프로파일과 일치하는 곡을 제안할 수 있습니다.
곡 알케미	인터랙티브한 "추가/제거" UI로 분위기를 세밀하게 조정하고, 2차원 맵에서 미리 보기 후 최종 목록을 미디어 서버에 전송합니다.
텍스트 및 가사 검색	기분, 악기, 장르 또는 가사 내용으로 검색 가능 (72개 언어 지원).
녹음 기반 검색	20초 음성 스니펫을 업로드하거나 녹음하여 라이브러리 내 일치하는 트랙을 찾거나, 알려진 곡의 다른 녹음본을 찾을 수 있습니다.

아키텍처 개요

Flask 웹 UI – 브라우저 인터페이스, Swagger API 문서, 인증(JWT 쿠키)을 처리합니다.
워커 컨테이너 – 무거운 음성 분석 및 클러스터링을 수행하며, CPU 또는 옵션으로 NVIDIA GPU에서 실행 가능 (일반 -nvidia 이미지 또는 실험적 -nvidia-arm).
PostgreSQL v15 – 지문, 클러스터링 결과, 사용자 설정, 작업 큐를 저장 (v2.6부터 큐는 Redis에서 PostgreSQL으로 이전됨).
플러그인 – 간단한 플러그인 시스템을 통해 제3자 확장 기능을 추가 가능. 플러그인은 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를 대상으로 합니다.
가상 머신은 호스트 CPU의 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, 네이티브 바이너리 등 다양한 배포 모델을 제공하며 주요 자체 호스팅 미디어 서버와 통합 가능합니다.