Library editing setup

Updated 11 November 2026

Use SoundBase on iPhone or Mac to edit track, album and artist tags, choose or create genres, replace artwork, rename audio files and remove music from your library. Editing requires a SoundBase build with the library editor, a Navidrome administrator account, and the helper installed on your music server.

The helper writes changes to your music files and asks Navidrome to scan them. Removed files and originals from metadata edits go into a recovery folder. Completed recovery operations are permanently deleted after 30 days.

Before you start

  • Use a Navidrome version with real-path reporting. The helper has been tested with Navidrome 0.64.2.
  • Give the helper’s service account write access to the music files and parent directories. Navidrome can keep its music mount read-only.
  • Keep the recovery folder outside every scanned music folder, on the same filesystem as the music. Create it before starting a Docker container and give its configured UID/GID write access.
  • Use an HTTPS server address in SoundBase. The proxy forwards the helper route on that same address.
  • Set ND_SUBSONIC_DEFAULTREPORTREALPATH=true before the helper first connects. If the helper has already connected, enable Report Real Path on its SoundBase player entry in Navidrome. Look for the entry with a Python user agent.

The helper manages one music root. For multiple libraries, keep the configured root scoped to the library you intend to edit. Docker paths must match the absolute paths reported by Navidrome, such as /music.

Install the helper

Download the helper source and deployment examples. On a Linux host with Python 3.11 or newer, install it under a directory such as /opt/soundbase-library. Replace each value in angle brackets with your own value, including removing the brackets.

Replace thisWith your own valueExample
<NAVIDROME_INTERNAL_URL>The address the helper uses to reach Navidromehttp://127.0.0.1:4533 on the same host, or http://192.0.2.10:4533 for an example separate server
<MUSIC_PATH>The music directory as seen by the helper, matching the paths Navidrome reports/srv/music
<RECOVERY_PATH>A writable directory outside the music library, on the same filesystem/srv/soundbase-recovery
<PUBLIC_NAVIDROME_URL>The HTTPS address you enter in SoundBasehttps://music.example.com

192.0.2.10 and music.example.com are documentation examples. 127.0.0.1 means the same host or container as the process using it. Use your own hostname, IP, port and base path when they differ.

git clone https://github.com/werket-werk/SoundBase.git
cd SoundBase/server/library
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python manager.py \
  --navidrome "<NAVIDROME_INTERNAL_URL>" \
  --music "<MUSIC_PATH>" \
  --recovery "<RECOVERY_PATH>" \
  --recovery-days 30

For Navidrome with a base path, include it in --navidrome, for example http://127.0.0.1:4533/music. The helper listens on loopback by default.

Run automatically with systemd

Place the helper files and virtual environment in /opt/soundbase-library. Replace <SERVICE_USER> and <SERVICE_GROUP> with the account and group that can write your files, for example music. Replace <HELPER_DIR> with the installation directory, for example /opt/soundbase-library. Save this as /etc/systemd/system/soundbase-library.service.

[Unit]
Description=SoundBase library helper
After=network-online.target
Wants=network-online.target

[Service]
User=<SERVICE_USER>
Group=<SERVICE_GROUP>
WorkingDirectory=<HELPER_DIR>
ExecStart=<HELPER_DIR>/.venv/bin/python "<HELPER_DIR>/manager.py" --navidrome "<NAVIDROME_INTERNAL_URL>" --music "<MUSIC_PATH>" --recovery "<RECOVERY_PATH>" --recovery-days 30
Restart=on-failure

[Install]
WantedBy=multi-user.target
sudo systemctl enable --now soundbase-library
systemctl status soundbase-library
Run with Docker Compose

Use Dockerfile and compose.example.yml from the helper directory. Replace the sample host paths on the left side of the volume mounts. Set the container music path to the path Navidrome reports, and match the helper’s --music argument to it. Use your service account’s UID/GID instead of the sample 1000:1000 and your Docker network name instead of music. Put Navidrome, the helper and the HTTPS proxy on that network.

docker compose -f compose.example.yml up -d --build
docker compose -f compose.example.yml logs soundbase-library

The example binds inside the container and publishes no host port. Point the proxy at http://soundbase-library:4534. The Navidrome URL becomes http://navidrome:4533 when that is its container name.

Add the HTTPS proxy route

Add this location to the HTTPS virtual host for <PUBLIC_NAVIDROME_URL>. Keep its existing Navidrome route. Replace <HELPER_UPSTREAM> with the address the proxy uses to reach the helper, for example http://127.0.0.1:4534 if they run on the same host.

location /soundbase-library/v1/ {
    proxy_pass <HELPER_UPSTREAM>;
    client_max_body_size 3m;
    proxy_read_timeout 300s;
}

For a Docker proxy, use proxy_pass http://soundbase-library:4534;. In Nginx Proxy Manager, add the location in the music host’s Advanced configuration.

If your public server address has a base path such as /music, match /music/soundbase-library/v1/ and use proxy_pass <HELPER_UPSTREAM>/soundbase-library/v1/; so the helper receives the route without the base path.

The helper checks the existing SoundBase login against Navidrome on every request and requires administrator privileges. Keep request bodies out of proxy logs because they contain Subsonic authentication tokens. Test the proxy configuration before reloading it.

Configure artwork

For tracks and albums, import an image or preview and select a release from MusicBrainz and the Cover Art Archive. The helper embeds the cover in FLAC, MP3 or M4A files. Other metadata edits use the tag formats supported by Mutagen.

If existing folder images take precedence over your replacement, put embedded first in Navidrome’s CoverArtPriority. To show one album cover across discs, you can also set DiscArtPriority="". These settings affect artwork selection throughout the library.

For artist images, create a writable image directory on the recovery filesystem, pass it as --artist-images "<ARTIST_IMAGE_PATH>" (for example /srv/artist-images), and configure Navidrome with the same directory.

ArtistImageFolder = "<ARTIST_IMAGE_PATH>"
ArtistArtPriority = "image-folder,artist.*,album/artist.*,external"

For Docker, mount that folder into both containers and use each container’s matching path. Existing artist images uploaded through Navidrome may take precedence. Use Navidrome’s Refresh Metadata action if cached artwork persists. See Navidrome’s artwork documentation.

Artwork searches send the album and artist names to MusicBrainz. Cover previews and downloads contact the Cover Art Archive and its image hosts. Imported images are uploaded to your own helper.

Check the setup

  1. Check the helper’s service or Docker logs for startup errors.
  2. Reopen a SoundBase build that includes editing and sign in as a Navidrome administrator using <PUBLIC_NAVIDROME_URL>.
  3. Open a track, album or artist menu and choose Edit.
  4. Change a test track’s genre, save, and wait for Navidrome’s scan. Confirm the change in SoundBase and Navidrome.
  5. Check that the recovery folder contains the original file and a .soundbase-completed marker inside the operation directory.

Recover files within 30 days

Track removal moves that track. Album removal moves its indexed tracks. Artist removal moves tracks from albums credited solely to that album artist. Metadata edits preserve originals under <kind>-edit-*/originals/. Removal preserves relative paths under removed-<kind>-*/.

To undo a removal or metadata edit, copy the recovered file back to its original relative path under the music root and scan in Navidrome. Restore an artist image from original-artist.jpg to its configured image path. A filename rename keeps the audio in its existing folder and can be undone by renaming it again.

The helper checks completed operations at startup and hourly while running. After 30 days, it permanently deletes the whole recovery operation, including original files. Use --recovery-days N to change retention, or --recovery-days 0 for indefinite retention. Operations from older helper versions without completion markers and manually added folders are left for the administrator to review.

Navidrome normally keeps missing records, including ratings and playlist references, after files move out of the library. Administrators may still see those records until they remove them under Settings → Missing Files. Scanner.PurgeMissing="always" clears every missing record after each scan, so review its library-wide effect before enabling it. See Navidrome’s missing files guide.

Troubleshooting

The Edit menu is missing

Check that the installed SoundBase build includes editing, the account is a Navidrome administrator, the address uses HTTPS, and the proxy forwards /soundbase-library/v1/. Reopen the app after changing the helper setup.

The helper asks for real paths

Enable Report Real Path on the SoundBase player entry created by the helper. Check that the helper can access the exact path returned for the track. Container paths and host paths can differ.

A permission or filesystem error appears

Check ownership, write access, available storage, and that music, recovery and the optional artist image directory share a filesystem. The helper uses hard links to preserve originals. Test support on your NAS with disposable files.

A tag or artist name did not change

Artist renaming replaces exact Artist and Album Artist tag values, including plural variants. Combined credits stored in one value are preserved. Check the raw tags in Navidrome and choose the affected track for a direct edit.

Artwork search is unavailable

MusicBrainz and the Cover Art Archive can return rate limits, missing covers or network errors. Wait and retry, or choose an image file.

Back to SoundBase support