Fast automated music tagging and organisation based on MusicBrainz
wrtag is similar to music tagging and organisation tools such as Beets and MusicBrainz Picard but aims to be simpler, more composable, and faster.
To describe the general workflow:
- Input files are provided (existing or new).
- They are matched with releases in the MusicBrainz database. This may be done using existing tags or filenames.
- The files are moved or copied to a user-defined filesystem layout. For example,
My music/Artist name/(Release year) Release name/1. Track title.ext. - The file's tags are updated to match the tags in the MusicBrainz database.
- Enjoy a clean, consistent, and accurate browsing experience in your music player/server of choice.
- Features
- Included tools
- Installation
- Global configuration
- Path format
- Addons
- Notifications
- Goals and non-goals
- Unix-style suite of tools for different use cases, using the same core wrtag functionality.
- Fast tagging thanks to Go.
- Filesystem organisation of music files, covers, and configurable extra files.
- Cover fetching or upgrades from the Cover Art Archive.
- Care taken to ensure no orphan folders are left in the library when moves or copies occur.
- Validation to ensure your library is always consistent with no duplicates or unrecognised paths.
- Safe concurrent processing with tree-style filesystem locking.
- Addons for fetching lyrics, calculating ReplayGain, or any user-defined subprocess.
- Rescanning the library and processing it for new changes in MusicBrainz (
wrtag sync). - An optional web interface for importing new releases over the network. Allows the user to be notified and confirm details if there is no 100% match found.
- Support for gazelle-origin files to improve matching from certain sources.
- Support for Linux, macOS, and Windows with static/portable binaries available for each.
The wrtag tool is the main command line tool for music organisation. It has two subcommands for working on individual folders (copy, move), and one for bulk processing (sync).
wrtag is the main command line tool that works on a single folder and requires an operation such as move or copy.
For example:
$ wrtag move "Example" # tags and moves `Example` into the library defined by the path-format config option
$ wrtag move -dry-run "Example" # shows move and tag operations without applying them
$ wrtag move -yes "Example" # use anyway even if low match
$ wrtag move -mbid "abc" -yes "Example" # overwrite matched MusicBrainz release UUIDIf the source files should be left alone, wrtag also provides a copy operation:
$ wrtag copy -yes "Example" # copies and tags `Example` into the library, use anyway even if low match
$ wrtag copy -mbid "abc" -yes # overwrite matched MusicBrainz release UUID even if low matchRe-tagging your music can be useful for a few reasons. For example, if your path-format configuration has changed, or the metadata in the MusicBrainz database has changed.
Since a move operation always cleans up the source directory - and is smart about the music already being in place - a re-tag is just a move pointed at some music that is already in place:
# path-format is /my/music/XXX
$ wrtag move "/my/music/Tame Impala/(2010) Innerspeaker"
# now has updated tags, and moved again if neededBulk operations are done with the sync subcommand. Unlike the copy and move commands which operate on single releases, the sync command works on your already imported and tagged library.
Warning
As the sync command is non-interactive, when used incorrectly it can be destructive. Only use sync on a library whose contents have been populated by copy or move.
By default, sync recurses through all directories rooted in path-format and finds leaf directories. A leaf directory is one that has no sub-folders, and therefore looks like a release. The tracks are read, and if they have a MUSICBRAINZ_ALBUMID (e.g., from copy or move), the release info is fetched from MusicBrainz and the release is re-tagged.
If no MUSICBRAINZ_ALBUMID is present, the release is matched as it usually would, and only re-tagged if a high match score is calculated.
$ wrtag sync # recurse all releases and re-tag
$ wrtag sync -dry-run # show what above would do
$ wrtag sync "/my/music/Tame Impala" # find all releases in "Tame Impala/" and re-tag those
$ wrtag sync -age-older 24h # find all releases older than 1 day and re-tag
$ wrtag sync -num-workers 16 # process a maximum of 16 releases at a time
wrtagweb is based on the same core functionality as wrtag, except it's web-based instead of command line. Instead of importing releases from the command line arguments, new releases are imported over HTTP.
For example, an HTTP client (a custom script, a BitTorrent client "on complete" script, or Soulseek) sends an HTTP request to wrtagweb, giving it a new path to import. wrtagweb imports it. If there isn't a 100% match, the user is notified. Then, the user can correct the match, reject, or accept anyway.
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '26px' }}}%%
flowchart LR
a["BitTorrent / Soulseek script"] -->
b["Release added to queue"] -->
c["User notified if input needed"] -->
d["Release imported"]
Jobs are added to the queue with an HTTP request like POST <wrtag.host>/op/<copy|move> with form value path=<absolute path to directory>. The form value can be an application/x-www-form-urlencoded form body, or URL query parameter.
Authentication is done via HTTP a basic auth password (without a username), and is configured by web-api-key.
Warning
HTTP Basic Authentication is only as secure as the transport layer it runs on. Make sure wrtagweb is secured using TLS behind your reverse proxy.
Example with cURL
curl \
--request POST \
--data-urlencode "path=/path/to/the/release" \
"https://:my-api-key@wrtag.hostname/op/copy"Example with Transmission
Create a script named done.sh or anything you like, and make it executable:
chmod +x done.sh
Update your Transmission settings.json to reference the new script:
...
"script-torrent-done-enabled": true,
"script-torrent-done-filename": "/scripts/done.sh",
...Edit the script to send a copy job with the newly finished torrent. Transmission will set TR_TORRENT_NAME to the name/path of the torrent. See all variables
#!/bin/sh
curl \
--request POST \
--data-urlencode "path=<path to downloads>/$TR_TORRENT_NAME" \
"http://:<wrtag api key>@<wrtag host>/op/copy"Example with qBittorrent
TODO
Example with Deluge
TODO
Example with sldkd
TODO
Configuration for wrtagweb works the same as Global configuration. For example, wrtagweb -web-arg, WRTAG_WEB_ARG, and the global config file is also read.
| CLI argument | Environment variable | Config file key | Description |
|---|---|---|---|
| -web-api-key | WRTAG_WEB_API_KEY | web-api-key | API key for web interface |
| -web-db-path | WRTAG_WEB_DB_PATH | web-db-path | Path to database path for web interface (default "wrtag.db") |
| -web-listen-addr | WRTAG_WEB_LISTEN_ADDR | web-listen-addr | Listen address for web interface |
| -web-public-url | WRTAG_WEB_PUBLIC_URL | web-public-url | Public URL for web interface (optional) |
The metadata tool is a standalone helper program for reading and writing track metadata. It can write multiple tags (each with multiple values) to multiple files in a single invocation.
Since it uses the same tag normalisation as wrtag itself, it works well with the subproc addon. This allows for custom metadata read and write after the main release process has completed.
$ metadata [<options>] read <tag>... -- <path>...
$ metadata [<options>] write ( <tag> <value>... , )... -- <path>...
$ metadata [<options>] clear <tag>... -- <path>...
# <tag> is an audio metadata tag key
# <value> is an audio metadata tag value
# <path> is path(s) to audio files, dir(s) to find audio files in, or "-" for list audio file paths from stdin $ metadata read -- a.flac b.flac c.flac
$ metadata read artist title -- a.flac
$ metadata read -properties -- a.flac
$ metadata read -properties title length -- a.flac
$ metadata write album "album name" -- x.flac
$ metadata write artist "Sensient" , genres "psy" "minimal" "techno" -- dir/*.flac
$ metadata write artist "Sensient" , genres "psy" "minimal" "techno" -- dir/
$ metadata clear -- a.flac
$ metadata clear lyrics artist_credit -- *.flac
$ find x/ -type f | metadata write artist "Sensient" b -
$ find y/ -type f | metadata read artist title -
$ find y/ -type f -name "*extended*" | metadata read -properties length -For more, see metadata -h and metadata read -h
You can find static/portable binaries (wrtag, wrtagweb, metadata) on the releases page for Windows, macOS, and Linux.
To install from source, install a recent Go toolchain, clone the repo, and run go install ./cmd/... from inside.
For packagers, CGO is not required, so you can build with CGO_ENABLED=0 to produce a static binary.
Docker images for many architectures are available on Docker Hub and GitHub. The Docker image by default starts wrtagweb, but has the wrtag tools included too.
If you're using Docker Compose and wrtagweb, you can use this compose.yml to get started:
services:
wrtag:
image: sentriz/wrtag
environment:
- WRTAG_WEB_API_KEY= # change this
- WRTAG_WEB_LISTEN_ADDR=:80
- WRTAG_WEB_PUBLIC_URL=https://wrtag.example.com
- WRTAG_WEB_DB_PATH=/data/wrtag.db
- WRTAG_LOG_LEVEL=debug
# add more config options, like mentioned in the docs above
# - WRTAG_PATH_FORMAT=...
# - WRTAG_ADDON=...,...
# - WRTAG_RESEARCH_LINK=...,...
# or, use the config file if you use wrtag outside the container. make sure to add it to `volumes:` too
# - WRTAG_CONFIG_PATH=/config
expose:
- 80
volumes:
- ./data:/data # for the wrtagweb job queue DB
- /path/to/music:/path/to/musicGlobal configuration is used by all tools. Any option can be provided with a CLI argument, environment variable, or config file key. See Format for more technical details.
| CLI argument | Environment variable | Config file key | Description |
|---|---|---|---|
| -addon | WRTAG_ADDON | addon | Define an addon for extra metadata writing (see Addons) (stackable) |
| -caa-base-url | WRTAG_CAA_BASE_URL | caa-base-url | CoverArtArchive base URL (default "https://coverartarchive.org/") |
| -caa-rate-limit | WRTAG_CAA_RATE_LIMIT | caa-rate-limit | CoverArtArchive rate limit duration |
| -config | WRTAG_CONFIG | config | Print the parsed config and exit |
| -config-path | WRTAG_CONFIG_PATH | config-path | Path to config file (default "$XDG_CONFIG_HOME/wrtag/config") |
| -cover-upgrade | WRTAG_COVER_UPGRADE | cover-upgrade | Fetch new cover art even if it exists locally |
| -keep-file | WRTAG_KEEP_FILE | keep-file | Define an extra file path to keep when moving/copying to root dir (stackable) |
| -log-level | WRTAG_LOG_LEVEL | log-level | Set the logging level (default INFO) |
| -mb-base-url | WRTAG_MB_BASE_URL | mb-base-url | MusicBrainz base URL (default "https://musicbrainz.org/ws/2/") |
| -mb-rate-limit | WRTAG_MB_RATE_LIMIT | mb-rate-limit | MusicBrainz rate limit duration (default 1s) |
| -notification-uri | WRTAG_NOTIFICATION_URI | notification-uri | Add a shoutrrr notification URI for an event (see Notifications) (stackable) |
| -path-format | WRTAG_PATH_FORMAT | path-format | Path to root music directory including path format rules (see Path format) |
| -research-link | WRTAG_RESEARCH_LINK | research-link | Define a helper URL to help find information about an unmatched release (stackable) |
| -tag-weight | WRTAG_TAG_WEIGHT | tag-weight | Adjust distance weighting for a tag (0 to ignore) (stackable) |
| -version | WRTAG_VERSION | version | Print the version and exit |
Just call the command with the CLI argument. For example, wrtag -some-key "some value". For stackable (repeatable) arguments, pass them multiple times. For example, wrtag -some-key "value 1" -some-key "value 2".
Note
Be aware of the position of global vs command arguments. For example, wrtag <global options> cmd <cmd options>. Check -h when in doubt.
Environment variables are prefixed with WRTAG_ usually. For example, WRTAG_LOG_LEVEL=info wrtag. For stackable (repeatable) arguments, join them with a comma (,). For example, WRTAG_ADDON="replaygain,lyrics genius musixmatch". If the value of the variable should have a comma, it can be escaped with a backslash. For example, \,.
The config file can be used instead of CLI arguments or environment variables, but can be overwritten with the -config-path CLI argument or WRTAG_CONFIG_PATH environment variable.
Note the default config file locations:
| OS | Path |
|---|---|
| Linux | $XDG_CONFIG_HOME/wrtag/config |
| Windows | %AppData%\wrtag\config |
| macOS | $HOME/Library/Application Support/wrtag/config |
The format follows (flagconf), which looks something like:
some-key argument
other-key argument
For stackable (repeatable) arguments, provide the same key multiple times. For example:
addon replaygain
addon lyrics genius musixmatch
See the example config for more.
The path-format configuration option defines both the root music directory and the template for organising your music files. This template uses Go's text/template syntax and is populated with MusicBrainz release data.
In order to minimise potential release conflict, the path format should include at least three path segments:
- The root music directory (where all your music will be stored).
- Artist/release organisation (typically artist name and album details).
- Track naming format (including track numbers and titles).
For example:
path-format /music/library/{{ <some artist format> }}/({{ <some release format> }}/{{ <track format> }}
This could format a release like:
/music/library/Tame Impala/(2010) Innerspeaker/01. It Is Not Meant to Be.flac
/music/library/Tame Impala/(2010) Innerspeaker/02. Desire Be Desire Go.flac
/music/library/Tame Impala/(2010) Innerspeaker/03. Alter Ego.flac
...
On Windows, you can use drive letters and backslashes:
path-format C:\User\John\Music\{{ <some artist format> }}\({{ <some release format> }}\{{ <track format> }}
The template has access to the following data:
.Release- The full MusicBrainz release object (seetype Release struct {).Track- The current track being processed (seetype Track struct {).TrackNum- The track number (integer, starting at 1).Tracks- The list of tracks in the release.ReleaseDisambiguation- A string for release and release group disambiguation.IsCompilation- Boolean indicating if this is a compilation album.Ext- The file extension for the current track, including the dot (e.g., ".flac")
In addition to what's provided by Go text/template, several helper functions are available to format your paths:
| Function | Description | Example |
|---|---|---|
join |
Joins strings with a delimiter | {{ artists .Release.Artists | join "; " }} |
pad0 |
Zero-pads a number to specified width | {{ pad0 2 .TrackNum }} → "01" |
sort |
Sorts a string array | {{ artists .Release.Artists | sort }} |
safepath |
Makes a string safe for filesystem use | {{ .Track.Title | safepath }} |
artists |
Gets artist names from artist credits | {{ artists .Release.Artists }} |
artistsString |
Formats artists as a string | {{ artistsString .Track.Artists }} |
artistsEn |
Gets artist names in English locale from artist credits | {{ artistsEn .Release.Artists }} |
artistsEnString |
Formats artists names in English locale as a string | {{ artistsEnString .Track.Artists }} |
artistsCredit |
Gets credit names from artist credits | {{ artistsCredit .Release.Artists }} |
artistsCreditString |
Formats artist credits as a string | {{ artistsCreditString .Release.Artists }} |
Note
If you need help with creating custom path formats, please see the provided playground here
Including multi-album artist support, release group year, release group and release disambiguations, track numbers, total track numbers, artist names if the release is a compilation album:
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}{{ if not (eq .ReleaseDisambiguation "") }} ({{ .ReleaseDisambiguation | safepath }}){{ end }}/{{ pad0 2 .TrackNum }}.{{ len .Tracks | pad0 2 }} {{ if .IsCompilation }}{{ artistsString .Track.Artists | safepath }} - {{ end }}{{ .Track.Title | safepath }}{{ .Ext }}
/music/{{ artists .Release.Artists | join "; " | safepath }}/{{ .Release.Title | safepath }}/{{ pad0 2 .TrackNum }} {{ .Track.Title | safepath }}{{ .Ext }}
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}{{ if not (eq .ReleaseDisambiguation "") }} ({{ .ReleaseDisambiguation | safepath }}){{ end }}/{{ pad0 2 .TrackNum }} {{ .Track.Title | safepath }}{{ .Ext }}
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}/{{ pad0 2 .TrackNum }} {{ if .IsCompilation }}{{ artistsString .Track.Artists | safepath }} - {{ end }}{{ .Track.Title | safepath }}{{ .Ext }}
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}/{{ pad0 2 .TrackNum }}.{{ len .Tracks | pad0 2 }} {{ .Track.Title | safepath }}{{ .Ext }}
Addons can be used to fetch/compute additional metadata after the MusicBrainz match has been applied and the files have been tagged.
They are configured as part of the global configuration using a config format.
For example:
$ wrtag -addon "lyrics a b c" -addon "replaygain x y z"$ WRTAG_ADDON="lyrics a b c,replaygain" wrtag- or repeating the
addonclause in the config file.
The lyrics addon can fetch and embed lyric information from Genius and Musixmatch in your tracks.
The format of the addon config is lyrics <source>... where the source is one of genius or musixmatch. For example, "lyrics genius musixmatch". Note that sources will be tried in the order they are specified.
The replaygain addon computes and adds ReplayGain 2.0 information to your files. It is great for normalising the perceived loudness of audio in your tracks.
The format of the addon config is replaygain <opts>... where opts can be true-peak and force. If the force option is passed, ReplayGain information is recomputed even if it’s already present in the files.
The subprocess addon is for running a user-provided program.
The format of the addon config is subproc <path> <args>..., where path is the path to the program, or the program name itself if it’s in your $PATH. args are extra command line arguments to pass to the program. One of the args should be a special placeholder named <files>. This will be expanded to the paths to the files that were just processed by wrtag.
For example, the addon "subproc my-program a --b 'c d' <files>" might call my-program with arguments ["a", "--b", "c d", "track 1.flac", "track 2.flac", "track 3.flac"] after importing a release with 3 tracks.
Notifications can be used to notify you or another system of events such as importing or syncing. For example, sending an email when user input is needed to import a release. Or notifying your music server after a sync has completed.
The possible events are:
| Tool | Name | Description |
|---|---|---|
wrtagweb |
complete |
Executed when a release is imported |
wrtagweb |
needs-input |
Executed when a release requires input |
wrtag |
sync-complete |
Executed when a sync has completed |
wrtag |
sync-error |
Executed when a sync has completed with errors |
wrtag uses shoutrrr to provide upstream notifications over SMTP, HTTP, etc.
For example:
smtp://username:password@host:port/?from=from@example.com&to=recipient@example.comgeneric+https://my.subsonic.com/rest/startScan.view?c=wrtag&v=1.16&u=user&p=password
See the shoutrrr documentation for the list of providers.
Notifications are configured as part of the global configuration. The format is <eventspec> <shoutrrr uri>. eventspec is a comma-separated list of event names.
For example, "complete,sync-complete smtp://example.com". Multiple eventspec and URIs can be configured by stacking the config option according to the config format.
TODO