Skip to content

FAQ.md

Latest commit

 

History

History
166 lines (114 loc) · 9.69 KB

FAQ.md

File metadata and controls

166 lines (114 loc) · 9.69 KB
Raw

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 section has the explanation and multiple examples can be found in the deployment folder. 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 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, in two different ways.

Several libraries inside one server. Each server has a library filter. It is a comma-separated list of libraries or folders to analyze; if it is empty, everything is scanned. For Lyrion use folder paths like "/music/myfolder". For Navidrome, Jellyfin, Emby and Plex use the library or folder names.

Several servers at the same time. A single AudioMuse-AI instance can be connected to several media servers at once, including several servers of the same type, for example one Navidrome plus two Jellyfins plus a Plex. Add them under Setup > Music Servers. The same song present on two servers is analyzed only once and mapped to both. See MULTI_SERVER for the full model.

How can I make the analysis faster?
  1. Configure a Lyrics API in the Setup Wizard (or have lyrics on your music server). Whisper ASR is by far the slowest part of the analysis and only runs when no lyrics are found.
  2. Add more workers in parallel. Just deploy another worker container, for example on another PC, using these worker examples. It only needs to reach the database and the music server, see ARCHITECTURE. This works only with the container version, not with the native apps.
  3. As a last resort, turn off some models under Machine Learning Models in the Setup Wizard. You lose the features that use them, but everything runs faster. Musicnn alone is enough for the basic features, but we suggest keeping DCLAP too.
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.

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. See also PARAMETERS.

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.

What do the small bars under the Machine Learning Models in the Setup Wizard mean?

Each bar shows how much of your library that model's search index can find right now: one lit segment means the index has just started filling, five means it is ready (more than 95 percent of the songs). The bars are read every time you open the Setup Wizard and fill up as the analysis runs, because every analysis run rebuilds the indexes at its end.

They are deliberately bands, not percentages. A library of 200,000 songs with a hundred songs not yet indexed is complete for every practical purpose, so it shows as Ready. If a bar stays short after the analysis has finished, run the analysis again: the songs it skipped are re-tried. The GTE Lyrics bar counts the songs whose lyrics stage has run (a song with no words gets an instrumental marker and counts as done), so instrumental tracks never hold it back. Open What it does under a model to see the pages that use it and why.

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

First check that Automatic Parameter Discovery is enabled. It is the recommended setting: a few quick probe runs tune the cluster count and the sampling percentile for each of your servers before the real run, which is what usually fixes empty or tiny playlists on its own.

If you prefer to tune by hand, turn it off and adjust these Advanced Parameters:

  • Stratified Sampling Target Percentile: raises the number of songs included in the clustering sample (set it up to 100 for maximum coverage)
  • min clusters / max clusters: fewer clusters means bigger playlists, more clusters means smaller ones
  • Minimum playlist size: playlists below this size are dropped at the end, so a high value can leave you with very few playlists
Clustering returns playlists with too many songs. How can I fix this?

Raise min clusters and max clusters, and lower the Stratified Sampling Target Percentile, in the advanced parameter view. With Automatic Parameter Discovery on, you can instead lower the maximum playlist size target so the calibration aims for smaller playlists.

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

Reduce the Clustering Runs value. The default is 1000 iterations; a few hundred already gives usable results on a small library.

The run also stops enqueuing new batches once several consecutive batches fail to improve the best result, so raising the run count is not always as expensive as it looks.

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 docs for more details.

How to backup and restore the database?

Backup and restore are available under Administration > Backup and Restore.

Important notes:

  • Restore into the same PostgreSQL major version the backup came from. The published Docker Compose examples use postgres:15-alpine; the native builds bundle their own PostgreSQL, whose version can differ.
  • For the same reason, a backup is not always interchangeable between a container deployment and a native Linux, Windows or macOS build.
  • If something fails, check the Flask container logs and the files 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