⭐ Leave a star on this project: One shines alone; together, they make it visible and keep it alive.

AudioMuse-AI - Where Music Takes Shape

AudioMuse-AI is an opensource and self-hosted tool that uses sonic analysis to rediscover forgotten songs in your music library and generate groove-aware playlists that also capture the meaning behind each track, without relying on metadata or external APIs.

You can run it locally with Docker Compose or Podman, or deploy it at scale in a Kubernetes cluster (AMD64 and ARM64 supported). It integrates with major self-hosted music servers including Jellyfin, Navidrome, LMS, Lyrion, and Emby, with more integrations planned.

Prefer not to self-host? We're proud that Elestio picked AudioMuse-AI as a managed cloud service, happy to see the project reach more people.

Need a hosted LLM provider? AudioMuse-AI supports OpenAI-compatible APIs through the existing OPENAI provider. Atlas Cloud is one hosted option you can configure this way; see the configuration parameters for details.

AudioMuse-AI lets you explore your music library in innovative ways, just start with an initial analysis, and you’ll unlock features like:

• Clustering: Automatically groups sonically similar songs, creating genre-defying playlists based on the music's actual sound.
• Instant Playlists: Simply tell the AI what you want to hear—like "high-tempo, low-energy music" and it will instantly generate a playlist for you.
• Music Map: Discover your music collection visually with a vibrant, genre-based 2D map.
• Playlist from Similar Songs: Pick a track you love, and AudioMuse-AI will find all the songs in your library that share its sonic signature, creating a new discovery playlist.
• Song Paths: Create a seamless listening journey between two songs. AudioMuse-AI finds the perfect tracks to bridge the sonic gap.
• Sonic Fingerprint: Generates playlists based on your listening habits, finding tracks similar to what you've been playing most often.
• Song Alchemy: Mix your ideal vibe, mark tracks as "ADD" or "SUBTRACT" to get a curated playlist and a 2D preview. Export the final selection directly to your media server.
• Text Search: search your song with simple text that can contains mood, instruments and genre like calm piano songs.
• Lyrics Search: search your library by theme, story or meaning, like love songs, not just the sound.

Lyrics language support: the Lyrics Search feature works only with the 72 languages listed below.

Show the 72 supported languages

Afrikaans, Albanian, Arabic, Armenian, Azerbaijani, Basque, Belarusian, Bengali, Bulgarian, Burmese, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, Galician, Georgian, German, Greek, Gujarati, Haitian Creole, Hebrew, Hindi, Hungarian, Icelandic, Indonesian, Italian, Japanese, Javanese, Kannada, Kazakh, Khmer, Korean, Lao, Latvian, Lithuanian, Macedonian, Malay, Malayalam, Marathi, Mongolian, Nepali, Norwegian, Persian, Polish, Portuguese, Punjabi, Romanian, Russian, Serbian, Sinhala, Slovak, Slovenian, Somali, Spanish, Swahili, Swedish, Tagalog, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Vietnamese, Welsh, Yoruba.

More information like ARCHITECTURE, ALGORITHM DESCRIPTION, DEPLOYMENT STRATEGY, FAQ, GPU DEPLOYMENT, CONFIGURATION PARAMETERS AUTHENTICATION and can be found in the docs folder.

The full list or AudioMuse-AI related repository are:

• AudioMuse-AI: the core application, it run Flask and Worker containers to actually run all the feature;
• AudioMuse-AI Helm Chart: helm chart for easy installation on Kubernetes;
• AudioMuse-AI Plugin for Jellyfin: Jellyfin Plugin;
• AudioMuse-AI Plugin for Navidrome: Navidrome Plugin;
• AudioMuse-AI MusicServer: Open Subosnic like Music Sever with integrated sonic functionality.

And now just some NEWS:

• Version 2.1.4 introduces the Windows native version. Attached to each release you will find AudioMuse-AI-amd64-windows.zip.
• Version 2.1.3 introduces the Linux native version. Attached to each release you will find .deb and .rpm file.
• Version 2.1.2 introduces the MacOS native version. Attached to each release you will find AudioMuse-AI-arm64.zip.
• Version 2.1.0 re-exports the GTE lyrics model so it produces correct embeddings on every CPU. The only affected users are those who analyzed lyrics on an older CPU without VNNI (avx512_vnni/avx_vnni), where the previous model could produce degraded vectors, they should re-analyze the lyrics. To check if your CPU has VNNI, run on the host: grep -oE 'avx512_vnni|avx_vnni' /proc/cpuinfo | head -1 , if it prints nothing, you have no VNNI and we suggest to re-analyze. Before re-analyzing, drop the old lyrics tables:

docker compose exec -e PGPASSWORD=audiomusepassword postgres \
  psql -U audiomuse -d audiomusedb \
  -c "DROP TABLE IF EXISTS lyrics_embedding; DROP TABLE IF EXISTS lyrics_index_data; DROP TABLE IF EXISTS lyrics_axes_index_data;"

• Version 2.0.0 introduces a new faster and reliable multilangue model for lyrics search. Follow the release note to drop the old lyrics index and re-analyze the lyrics.

Disclaimer

Important: Despite the similar name, this project (AudioMuse-AI) is an independent, community-driven effort. It has no official connection to the website audiomuse.ai.

We are not affiliated with, endorsed by, or sponsored by the owners of audiomuse.ai.

Table of Contents

• Quick Start Deployment (Containerized)
• Native Deployment
• Hardware Requirements
• Docker Image Tagging Strategy
• How To Contribute
• Star History

Quick Start Deployment (Containerized)

Get AudioMuse-AI running in minutes with Docker Compose.

If you need more deployment example take a look at DEPLOYMENT page.

For a full list of configuration parameter take a look at PARAMETERS page.

For the architecture design of AudioMuse-AI, take a look to the ARCHITECTURE page.

From v1.0.0, only PostgreSQL, Redis, and TZ configuration must still be configured via environment variables. All other configuration values are managed through the browser setup wizard and persisted in the database. For compatibility with legacy installations, environment variables are imported into the database automatically on first startup. The Setup Wizard is shown on clean installation as lending page and is also available later from the menu under Administration > Setup Wizard.

Prerequisites:

• Docker and Docker Compose installed
• A running media server (Jellyfin, Navidrome, Lyrion, or Emby)
• See Hardware Requirements

Steps:

1. Create your environment file:

   cp deployment/.env.example deployment/.env
   

   You can customize the setup by editing deployment/.env before startup. As a minimum, it is suggested to change the default database user and password, but you can also override other PostgreSQL and Redis connection parameters if needed:

   POSTGRES_PASSWORD=your-secure-password
   

2. Start the services:

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

3. Access the application:

   • Web UI: http://localhost:8000
   • Interactive API documentation (Swagger UI): http://localhost:8000/apidocs/ (when authentication is enabled, log in via the Web UI first — /apidocs/ is gated by the same JWT cookie as the rest of the app.)

4. Run your first analysis:

   • Navigate to "Analysis and Clustering" page
   • Click "Start Analysis" to scan your library
   • Wait for completion, then explore features like clustering and music map

5. Stopping the services:

docker compose -f deployment/docker-compose.yaml down

Important: AudioMuse-AI is designed to work with PostgreSql v15 as in the deployment example. Different version could create error.

Native Deployment

Prefer not to use Docker? We ship native packages for macOS, Linux and Windows, attached to each release. Each bundles the whole stack (embedded PostgreSQL, Redis, web UI and workers), so you don't need Docker or an external database. Once started, open http://127.0.0.1:8000.

The apps are not signed, so your OS may warn you on first launch, see the per-platform notes below for how to allow them.

macOS — Apple Silicon, AudioMuse-AI-arm64.zip (from v2.1.2)

• Unzip and move AudioMuse-AI.app to /Applications.
• Remove the quarantine flag (the app is unsigned), either way:
  • Terminal: xattr -dr com.apple.quarantine /Applications/AudioMuse-AI.app, then double-click — the icon appears in your menu bar.
  • No Terminal: double-click and dismiss the warning, then System Settings → Privacy & Security → "Open Anyway", authenticate, and launch again.
• Runs only on Apple Silicon (ARM) on recent macOS (tested on macOS 15.3.1, Mac Mini M4 / 16 GB).

Files: data (database, Redis, temp audio) in ~/Library/AudioMuse-AI, log at ~/Library/Logs/AudioMuse-AI/audiomuse.log

Linux — x86_64 / arm64, .deb or .rpm (from v2.1.3)

• Install as root (writes to /opt and the system app/service dirs):
  • Debian/Ubuntu: sudo dpkg -i AudioMuse-AI-x86_64.deb
  • Fedora/RHEL: sudo rpm -i AudioMuse-AI-x86_64.rpm
• Run as your normal user (never with sudo/root — it stores data in your home and won't start as root):
  • audiomuse-ai start (stop with audiomuse-ai stop), or auto-start on login with systemctl --user enable --now audiomuse-ai.
• Verified on Debian 12 (bookworm) (glibc 2.36). The .rpm is the same payload, expected to work on recent Fedora / RHEL 9, but too old for RHEL/Rocky/Alma 8 (glibc 2.28). Feedback on RPM-based distros is welcome.

Files (under the launching user's home): data (database, Redis, temp audio) in ~/.local/share/AudioMuse-AI, log at ~/.local/state/AudioMuse-AI/logs/audiomuse.log (newest entries first)

Windows — x86_64, AudioMuse-AI-amd64-windows.zip (from v2.1.4)

• Unzip the portable archive anywhere.
• From a terminal you can start with AudioMuse-AI.exe start and stop with AudioMuse-AI.exe stop.
• Runs only on x86_64 (Intel/AMD) on Windows 10/11.

Files: data (database, Redis, temp audio) in %LOCALAPPDATA%\AudioMuse-AI, log at %LOCALAPPDATA%\AudioMuse-AI\logs\audiomuse.log (newest entries first)

Hardware Requirements

AudioMuse-AI has been tested on:

• Intel: HP Mini PC with Intel i5-6500, 16 GB RAM and NVMe SSD
• ARM: Raspberry Pi 5, 8 GB RAM and NVMe SSD / Mac Mini M4 16GB / Amphere based VM with 4core 8GB ram

Minimum requirements:

• CPU: 4-core Intel with AVX2 support (usually produced in 2015 or later) or ARM
• RAM: 8 GB RAM
• DISK: NVME SSD storage

For more information about the GPU deployment requirements have a look to the GPU page.

IMPORTANT: If you use virtualization (e.g. Proxmox), make sure to pass through the host CPU. QEMU's virtual CPU lacks AVX2 support, which will prevent AudioMuse-AI from starting.

Docker Image Tagging Strategy

Our GitHub Actions workflow automatically builds and publishes Docker images with the following tags:

• :latest Last build from the main branch. Recommended for most users.

• :devel Development build from the devel branch. May be unstable — for testing and development only.

• :X.Y.Z (e.g. :1.0.0, :0.1.4-alpha) Immutable images built from Git release tags. Ideal for reproducible or pinned deployments.

• -noavx2 variants Experimental images for CPUs without AVX2 support, using legacy dependencies. Not recommended unless required for compatibility.

• -nvidia variants Images that support the use of GPU for both Analysis and Clustering. Not recommended for old GPU.

Versioning is Major.Minor.Patch release. Eventually (rare) model change that could require a new analysis could happen in Major and Minor release. Read the release note before any update especially for Major and Minor release.

How To Contribute

Contributions, issues, and feature requests are welcome!

For more details on how to contribute please follow the Contributing Guidelines

Code Mirror

AudioMuse-AI repository code is mirrored here:

• https://codeberg.org/NeptuneHub/AudioMuse-AI

DO NOT USE MIRROR TO RAISE ISSUE, PR OTHER ACTION DIFFERENT FROM GET THE CODE

Star History