AudioMuse-AI

**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.

Quick Start Deployment

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

**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.