Music Tag Web: a Docker tag editor for music libraries that live on a NAS

V1 and V2 are two deployments that differ in port and one compose line

Music Tag Web ships two Docker recipes and both pull the same image, xhongc/music_tag_web:latest. The older V1 layout publishes port 8001 and its compose file sets `command: /start`. V2 moves the in-container service to port 8002 and drops the `command: /start` line, which the project says makes it fit more NAS systems. V2 is the layout the project recommends for new installs.

The practical trap is mixing the two. A V2 compose file that keeps `8001:8001`, or a V1 file with the command line removed, maps a host port to nothing that is listening. Pick one manual and copy its port on both sides of the mapping. The V2 pull and run commands are:

docker pull xhongc/music_tag_web:latest

docker run -d -p 8002:8002 -e DJANGO_SECRET_KEY="$DJANGO_SECRET_KEY" -v /path/to/your/music:/app/media -v /path/to/your/config:/app/data --restart=always xhongc/music_tag_web:latest

After the container is up, the admin page answers at 127.0.0.1:8002/admin for V2 and 127.0.0.1:8001/admin for V1. The project also links two GitBook manuals, one per version, and says to use the V2 manual first.

The compose file refuses to start without a per-deployment secret key

Both layouts read `DJANGO_SECRET_KEY` from the environment. The project asks you to generate a key that is unique to each deployment, save it, and pass it to the container. The generation command is:

export DJANGO_SECRET_KEY="$(openssl rand -hex 32)"

The compose file reads it as `${DJANGO_SECRET_KEY:?Set a unique DJANGO_SECRET_KEY}`. That syntax makes docker compose stop with the quoted message when the variable is empty or unset, so you cannot bring the stack up by accident with a blank key.

The consequence is that the key lives in your shell session unless you store it yourself. If you export it, run the container, close the terminal and later recreate the container, you need the same value or a new one. The project does not describe what a changed key invalidates, so keep the original somewhere durable, such as the environment file of your Portainer stack, before you rely on the deployment.

Two bind mounts decide what the editor can touch and what survives a rebuild

The run command and the compose file both define two volumes. `/path/to/your/music` is mounted at `/app/media`, and `/path/to/your/config` is mounted at `/app/data`. The compose file marks the music mount `:rw`, so the container can write tags back into the audio files. The config mount is the persistence directory for the application's own data.

Two things follow. First, every edit this tool makes is a write to your real library files, so a bulk replace or a bulk repair applied to the wrong folder changes the originals. The project lists an operation log that records tag modifications, which helps trace what happened, but it does not describe a dry run or an undo. Copy a test folder before pointing a large batch job at the whole collection. Second, if you leave out the config mount, the application data sits inside the container and goes when the container is recreated.

The example uses `restart: unless-stopped` in compose and `--restart=always` in the run command, so the service comes back after a reboot of the NAS.

The default admin/admin login and a public demo with the same credentials

Both layouts start with the account admin and the password admin, and the project tells you to change it at the first login. Nothing in the deployment steps forces the change, so a container published on a LAN port keeps the default credentials until someone logs in and replaces them.

The project also links a hosted demo at http://117.72.222.188:8002/#/ that uses the same admin/admin pair. Treat it as a way to see the interface, not as a place to upload anything. It is a demo server run by someone else, and nothing says its state is reset or private.

If you plan remote access to the NAS, the sensible order is to change the password first and only then forward a port. The project advertises phone-browser access to the library, which is exactly the use that puts the login screen on a wider network.

What the editor does to files: fingerprints, CUE splitting, conversion and lyrics

The editing surface is wider than a simple field editor. It reads and writes tags for FLAC, APE, WAV, AIFF, WV, TTA, MP3, M4A, OGG, MPC, OPUS, WMA, DSF and MP4. Single and batch edits cover title, album, artist, lyrics and cover art. Batch text replace cleans garbled or stray characters, and a batch converter switches song, album and artist tags between simplified and traditional Chinese.

Files with missing tags can be handled in two ways: a filename splitter extracts song, artist and album from the file name, and a built-in audio fingerprint matcher identifies tracks with no tags and messy names. A whole-album APE, FLAC and CUE image can be cut into separate tracks, each tagged independently. ffmpeg is integrated for batch conversion between lossless formats. Lyrics can carry an embedded translation, so bilingual lyrics are written into the audio file. Covers can be exported in bulk or replaced with your own upload.

The project does not give accuracy figures for fingerprint matching or scraping, and it does not name the fingerprint service. Check a sample of matched tracks before accepting a batch.

Scraped metadata comes from commercial music platforms, and the terms limit your use of it

Scraping pulls album, artist, lyric and cover data from several sources, with fallbacks between them. The project's own terms name Kuwo, NetEase Cloud Music, QQ Music, Migu and Kugou as the built-in platforms and say data is fetched from their public servers, lightly filtered and merged. It states that it takes no responsibility for the accuracy of that data, so wrong matches are yours to catch.

The terms go further than a normal license note. They forbid any commercial use, including selling or accepting tips, and describe the project as for personal study. They say copyrighted data such as images, audio, names and lyrics may arrive through use of the tool, that the project does not own it, and that users must clear such data within 24 hours. The same terms say the tool only edits metadata of files you already have and does not download music. These terms are written as a supplement to GPL V3.0, with a clause that the supplement wins in a conflict.

The result for a reader: the code is under GPL-3.0, but the scraping and the lyrics and covers it writes into your files carry extra conditions. Anyone running this for a shared or business library should read the full disclaimer first.

Playback and statistics are secondary features, so do not expect a media server

A search for whether you can play music on a website lands on a narrow answer here. The feature list mentions playing a library mounted from a private cloud drive online, reading lossless files from the NAS for Xiaoai speaker playback, and play-count charts shown as bar and line graphs. There is no stated playlist system, no streaming protocol and no client apps.

That matches how the project describes its place: a sidecar tool for Navidrome and Jellyfin users, not a replacement for them. The pitch is that MP3Tag and MusicBrainz Picard only work on files on the local machine, while this runs next to a remote server and edits files there. Your media server stays in charge of serving music, and this tool cleans the tags that the server indexes. After a big tag run, trigger a rescan in the server you use, since nothing in the project describes notifying it.

Old pinned dependencies, no releases and a moving latest tag

The repository has no GitHub releases, its default branch is dev_1.0, and the install instructions pull the `latest` tag only. You cannot pin a known-good version from what is published, so a later `docker pull` can change the application underneath you. The last push to the repository was on 2026-10-08.

requirements.txt pins an older stack: Django==2.2.6, celery==4.4.7, django-celery-beat==2.2.0, djangorestframework==3.8.1, djangorestframework-jwt==1.11.0, Pillow==9.4.0, requests==2.27.1, gunicorn==20.1.0, gevent==21.12.0, pycryptodomex==3.17, django-mysql==3.8.1 and music-tag==0.4.3. These are fixed versions, so security updates for any of them are not picked up unless the project changes the file.

For a home network behind a router this may be acceptable. For anything reachable from the internet, put it behind a VPN or an authenticating reverse proxy, and run a dependency audit against those exact versions before trusting it with write access to your music folder.

Editorial conclusion

Use it if your music sits on a NAS or home server and you want to fix tags, covers and lyrics from a browser instead of copying files to a desktop editor. Skip it if you need versioned releases or a short, audited dependency list. Before exposing it, change the admin/admin login and decide whether scraped lyrics and covers from commercial platforms are acceptable for your use.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Project website
4. README
5. xhongc/music-tag-web on GitHub