xhongc/music-tag-web: a self-hosted Docker tag editor for NAS music libraries

The remote-NAS problem Music Tag Web was built around

Desktop taggers assume the files are local. The README states this directly as the reason the project exists: MP3Tag and MusicBrainz Picard "can only operate on local files" and cannot reach a remote NAS or Linux server library. If your FLAC collection sits on a Synology or QNAP box and Navidrome reads it over the network, editing a hundred albums means either mounting the share on a workstation or copying files back and forth. Music Tag Web removes that step by running as a container next to the library and editing in place.

The audience is narrow and clearly stated: NAS owners, homelab users, and people running Navidrome or Jellyfin who want a sidecar tool for metadata. The README lists supported containers as FLAC, APE, WAV, AIFF, WV, TTA, MP3, M4A, OGG, MPC, OPUS, WMA, DSF and MP4, and says files stay on local storage rather than being uploaded to a third party. That last point matters if your library is large, since a browser upload workflow would be unusable at that scale.

What the repository layout tells you about the stack

The top level holds manage.py, requirements.txt, and directories named applications, component, web, static and templates. That is a Django project with a separate frontend build, and the README describes the product as a web UI over the same operations a desktop tagger performs. requirements.txt pins Django 2.2.6, djangorestframework 3.8.1, celery 4.4.7 with django-celery-beat and django-celery-results, gunicorn 20.1.0 with gevent, and the music-tag 0.4.3 library that does the actual file writing.

The presence of Celery and django-celery-beat is the interesting part. Batch scraping and batch conversion are long-running jobs, not request-response calls, so they are queued and executed by workers. That is the right shape for a tool that rewrites thousands of files, but it also means a single container has to run the web process and the worker, and a job that dies mid-batch leaves you with a partially edited library. The README does not document a transaction or rollback mechanism for interrupted batches, which is the first thing I would want to know before pointing this at a library I cared about.

Django 2.2.6 is a pinned, long-out-of-support release. For a self-hosted tool behind a home network that is a manageable risk. For anything reachable from the internet it is not, and the README's default credentials make that worse.

Installing Music Tag Web with Docker

The README recommends the V2 deployment and says all NAS and Linux homelab users should use it. V2 changes the internal service port to 8002 and drops the command: /start line from the Compose file. Start by pulling the image:

docker pull xhongc/music_tag_web:latest

Then run it, mapping your music directory to /app/media and a config directory to /app/data. Both paths on the left are placeholders you replace with real ones.

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

If you prefer Compose, the README gives this file for Portainer or a NAS container manager. Note that the V2 version has no command key.

version: '3'

services:
  music-tag:
    image: xhongc/music_tag_web:latest
    container_name: music-tag-web
    ports:
      - "8002:8002"
    volumes:
      - /path/to/your/music:/app/media:rw
      - /path/to/your/config:/app/data
    restart: unless-stopped

Open 127.0.0.1:8002/admin in a browser. The default credentials are admin/admin, and the README tells you to change the password before putting the instance online. The first real use is to point the app at a folder, let it index, then edit one album's artist and album fields and confirm the change on disk with your existing player. The V1 guide uses port 8001 and keeps command: /start; mixing the two port numbers is the most likely first mistake.

Scraping, fingerprinting and the CUE splitting feature

The feature list is long, and three items are worth separating from the marketing. The first is fingerprint recognition: the README says untagged files with messy names can be identified and matched automatically. That is the difference between a tag editor and a library recovery tool, and it is the reason someone with a decade of unsorted downloads would look at this project at all.

The second is CUE handling. The README states the tool can split whole-disc APE and FLAC files with CUE sheets into individual tracks and fill in per-track tags. That is a genuinely awkward operation to script by hand and one of the few features here that a desktop tagger does not do well.

The third is the batch text tools: simplified and traditional Chinese conversion across song, album and artist fields, filename parsing to recover missing artist and album values, and batch find-and-replace for cleaning garbled tags. These are aimed at a Chinese-language library, and the README's own framing is bilingual. If your collection is entirely English-language and already well tagged, most of this section does not apply to you.

Metadata comes from several sources. The README names Kuwo, NetEase Cloud Music, QQ Music, Migu and Kugou as the platforms whose public servers are queried. The disclaimer is explicit that the project does not guarantee accuracy of that data, and that you should delete any copyright data produced within 24 hours.

Where Music Tag Web is the wrong tool

The licence is the first boundary. The project is GPL-3.0, and the README adds terms on top of it that forbid commercial use, including selling, tipping or profiting from the code, and state it is for personal study. Whatever your reading of how those extra terms interact with GPL-3.0, the author's intent is unambiguous: this is not for a business that tags music as part of a paid service. If you need a permissive licence, look elsewhere.

The second boundary is maintenance. The last push to the default branch dev_1.0 was on 2026-09-04, which is recent, but the dependency pins tell a different story: Django 2.2.6 and djangorestframework 3.8.1 are years behind current releases. A project can be pushed to regularly and still carry an old framework underneath. Check the commit history yourself rather than trusting the push date.

The third is the workflow itself. This is a browser tool over a mounted directory. It has no undo stack that the README documents, no dry-run mode, and no documented rollback if a batch job is interrupted. For a small library that is fine. For a 50,000-file collection where a mistaken find-and-replace touches every file, the absence of a documented revert path is the risk you are accepting. Back up before batch operations; the README does not tell you to, and it should.

Music Tag Web compared with desktop taggers and Beets

The obvious alternative is the desktop route the README positions itself against: MP3Tag on Windows or MusicBrainz Picard anywhere, with the NAS share mounted over SMB or NFS. The difference is where the code runs. A desktop tagger reads and writes through the network filesystem, which is slow for large batches and depends on the mount staying healthy. Music Tag Web runs on the server, so file operations are local and the browser only carries the UI. If your library is on a remote box and your workstation link is flaky, that is a real difference.

The second alternative is Beets, which is a command-line library manager rather than a tag editor. Beets imports files into a database, moves and renames them according to rules, and can rewrite tags from MusicBrainz. Music Tag Web edits tags in place and does not maintain a catalog. If you want your directory structure to be the source of truth and you dislike moving files, Music Tag Web fits better. If you want reproducible, scriptable library management with a plugin ecosystem, Beets is the more controllable tool, at the cost of learning its configuration.

A third option for Navidrome users specifically is to do nothing and let the server's own metadata handling cope. That works until it does not, which is usually when a batch of files has no tags at all.

Upgrade cost and what the GPL-3.0 licence means here

Upgrades are a container image pull, which is the easy part. The harder part is the config directory mounted at /app/data. The README does not document a migration step between versions, and the V1 to V2 move already changed the internal port from 8001 to 8002 and removed command: /start from the Compose file. Anyone upgrading across that line has to edit their deployment, not just pull a new tag. There are no retrieved releases for this repository, so there is no changelog to read before upgrading; the README's two GitBook manuals are the only upgrade documentation the material points to.

On licensing, the repository ships GPL-3.0 and the README appends terms forbidding commercial use. That combination is worth reading carefully rather than assuming, and it is not something this article can resolve for you. What is clear from the text is the author's stated position: personal, non-commercial, small-scale study use. The project also states it edits only existing local files and does not provide music downloads, and that metadata pulled from the named streaming platforms may carry copyright, with a request to remove such data within 24 hours.

FAQ

These are the questions readers most often arrive with, answered from the README and the repository files rather than from hands-on use. The short version: Music Tag Web edits metadata on files you already own, it deploys as a Docker container on port 8002 in the recommended V2 layout, and it is positioned against desktop taggers that cannot reach a remote NAS library.

Editorial conclusion

Adopt Music Tag Web if your library lives on a NAS or headless Linux box and you want browser-based batch editing without mounting the share on a desktop. Skip it if you need a desktop app with undo history, if you want an actively developed project, or if you need a licence that permits commercial use. Before committing, verify two things: that your Docker host can mount the music directory read-write at /app/media, and that your deployment matches the V2 port 8002 layout rather than the older 8001 one, because the two guides describe different containers.

Frequently asked questions

Official sources

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