AudioMuse-AI FAQ

This document provides answers to frequently asked questions (FAQs) about deploying and using AudioMuse-AI.

Deployment FAQs

Find answers to common questions about setting up, configuring, and deploying AudioMuse-AI in different environments.

Which is the HW requirements?

> AudioMuse-AI work on both ARM and INTEL architecture. The suggested requirements are 4core and 8gb of ram with SSD. Some very old processor could have issue due to not supported command. > If you want to use the -nvidia version we suggest a GPU with 8gb VRAM.

How to deploy AudioMuse-AI?

> The [readme](../README.md) section has the explanation and multiple examples can be found in the [deployment folder](../deployment/). If you're not able to reach the front-end on **http://YOUR-IP:8000** or the analysis seems to finish without analyzing anything, it usually means that some parameters are missing in your `.env`. > > 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 landing page and is also available later from the menu under Administration > Setup Wizard.

Can AudioMuse-AI support multiple music libraries?

> Yes, it can support multiple music libraries within a single media server instance (e.g., two separate music folders in one Jellyfin server). However, a single AudioMuse-AI instance cannot connect to multiple different media servers (e.g., one Navidrome and one Jellyfin server) at the same time. > > The parameters `MUSIC_LIBRARIES` can be used for matching multiple music libraries on the same music server. It is a comma-separated list of music libraries/folders for analysis. If empty, all libraries/folders are scanned. For Lyrion: Use folder paths like "/music/myfolder". For Navidrome/Jellyfin: Use library/folder names.

The analysis takes too long, can I speed it up?

> The time needed for the analysis really depends on your HW and how big your music collection is. For big collections (100k+ songs) or old HW, 1 week+ of analysis can be totally normal. > > If you want faster analysis, you can disable the text search functionality by setting `CLAP_ENABLED` to false. This will run only the Musicnn model, skipping the CLAP model. > > Alternatives include running multiple worker containers in parallel (see the [ARCHITECTURE](ARCHITECTURE.md) page and deployment examples in the `deployment/` folder). GPU analysis is also supported but still experimental (see [GPU DEPLOYMENT](GPU.md)).

Setup Wizard connection test fails when using Jellyfin

> During the initial setup, the Setup Wizard may fail the connection test when configuring Jellyfin. > > This is most commonly caused by incorrect credentials. In Jellyfin, you must use the **User ID (UID)** instead of the username. > > You can find instructions on how to retrieve the Jellyfin User ID here: [PARAMETERS](PARAMETERS.md).

How to get the Plex auth token (X-Plex-Token)

> Plex authenticates with an auth token instead of a username/password. > > Sign in to the Plex Web App, open the browser developer tools (F12) and go to the Network tab. Refresh a library, click a request pointing to your server (for example one ending in `/library/sections`), then copy the `X-Plex-Token` value from the request headers or the query string. > > Reference: [plexapi.dev authentication](https://plexapi.dev/authentication). See also [PARAMETERS](PARAMETERS.md).

---

User Guide FAQs

Learn how to use AudioMuse-AI effectively, from basic features to advanced functionality.

• NOTE: Most front-end parameters default value can be configured in the Setup Wizard functionality. See the parameter table in the PARAMETERS page for a complete list.

How do I start using AudioMuse-AI?

> After deployment, the first thing to do is access the AudioMuse-AI frontend, available at **http://YOUR-IP:8000**. > > From there, run the **Analysis**, which collects information about your songs and stores it in the local database. > > Running the analysis is **mandatory** before you can use any other features.

How long does the analysis take? What if I interrupt it midway?

> The time required depends on the number of songs and hardware performance. It can take from a few hours to several days. > > If interrupted, you can safely restart the process, already analyzed songs are stored in the database, so only missing songs will be processed.

Clustering returns empty playlist or with only a few songs. How can I fix this?

> The default clustering parameters are tuned for collections of around **50,000–100,000 songs**. > > If clusters are too small or empty, adjust these Advanced Parameters: > > - **Stratified Sampling Target Percentile**: increases number of songs included in clustering (set up to 100 for more coverage) > - **min clusters / max clusters**: reduce or increase number of clusters and adjust cluster size

Clustering returns clusters with big number of songs. How can I fix this?

> Increase the `Stratified Sampling Target Percentile`, `min clusters`, and `max clusters` values in the advanced parameter view.

Clustering takes a lot of time, how can I run it faster?

> By default, clustering runs 5000 iterations. You can reduce the **Clustering Runs** value (e.g., 1000) to speed up execution while keeping acceptable quality.

How to reset the Admin password?

> From AudioMuse-AI v1.0.0, the Admin password is stored encrypted in the database. The only way to reset it is by accessing the PostgreSQL database and deleting it. See the [AUTHENTICATION](./AUTH.md) docs for more details.

How to backup and restore the database?

> Backup and restore are available under `Administration > Backup and Restore`. > > Important notes: > * Ensure the PostgreSQL version matches the deployment example (e.g., up to v2.1.5 uses `postgres:15-alpine`). Version mismatches may break backup/restore compatibility. > * Backups may not be interchangeable across different OS/container setups (Linux, Windows, macOS) due to PostgreSQL version differences. > * If issues occur, check logs in the Flask container under `/app/backup`.

What happens if my music server IDs change ?

> AudioMuse-AI depends on stable track IDs provided by the music server. If an action causes IDs to change (e.g. database reset, migration, reinstall, or major update), existing mappings may break and tracks may appear missing, duplicated, or mismatched. > > If this happens, the recommended recovery steps are: > 1. Restore a previous backup of the music server to recover the original track IDs. > 2. If restore is not possible, try a provider migration to preserve as much identity mapping as possible. > 3. If the change is partial (e.g. albums moved or deleted), use `Administration > Cleaning` to remove stale entries and just run a new analysis > 4. If none of the above works, as a last resort, reset the AudioMuse-AI database and run a full new analysis (this will rebuild all mappings from scratch). > > **Always create backups of both the music server and AudioMuse-AI database after the first analysis and possible on weekly basis**