Yet Another MusicBrainz Seeder
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Daniel Erat b99132517f
sources/online/tidal: Set "XW" for worldwide releases.
Set the release event's country to "XW" (worldwide) if the
full tracklist is returned in all countries where Tidal is
available. Note that this only happens when all countries
are queried (i.e. when running "yambs -country XW"). The
country field is still left empty when only a subset of
countries have the full tracklist. See #18.
6 days ago
build build: Pass tag name to create_release.yaml via $_VERSION. 1 month ago
cache cache, cmd/yambsd, db: Add LRU cache. 7 months ago
cmd Move to 1 month ago
mbdb Move to 1 month ago
render render: Automatically open edits when Ctrl is held. 1 month ago
seed sources/online/tidal: Set "XW" for worldwide releases. 6 days ago
sources sources/online/tidal: Set "XW" for worldwide releases. 6 days ago
strutil Only seed MBIDs from URLs when name in DB is similar. 3 months ago
web web: Log redirects when fetching pages. 5 months ago
.gcloudignore Let user specify country code for Tidal API calls. 4 months ago
.gitignore sources/bandcamp: Add support for singles. 7 months ago
LICENSE Add LICENSE. 7 months ago Move to 1 month ago
app.yaml Update go.mod and app.yaml to use Go 1.19. 3 months ago
go.mod sources/mp3: Switch to upstream taglib-go. 3 weeks ago
go.sum sources/mp3: Switch to upstream taglib-go. 3 weeks ago

yambs (Yet Another MusicBrainz Seeder)

Build Status

yambs is a command-line program for seeding edits to the MusicBrainz music database.

It can simplify adding multiple standalone recordings: given a CSV or TSV file describing recordings, yambs can open the Add Standalone Recording page for each with various fields pre-filled. The Add Artist, Add Event, Add Label, and Add Work pages can be seeded in a similar manner.

yambs can also read key=value lines from text files to seed the Add Release page, and it can use Bandcamp, Qobuz, and Tidal album pages and local MP3 files to seed edits too.

There's a web frontend at


To compile and install the yambs executable, install Go and run the following command:

go install ./cmd/yambs

If the account that you will use to run the yambs executable does not have access to the Google Cloud Translation API (used to detect releases' languages and scripts), you can supply the nogcp build tag to avoid attempting to connect to the service:

go install -tags nogcp ./cmd/yambs

Prebuilt executables are also available.


Usage: yambs [flag]... <FILE/URL>
Seeds MusicBrainz edits.

  -action value
    	Action to perform with seed URLs (open, print, serve, write) (default open)
  -addr string
    	Address to listen on for -action=serve (default "localhost:8999")
  -country string
    	Country code for querying Tidal API (ISO 3166, e.g. "US" or "DE"; "XW" for all)
    	Extract artist names from track titles in Bandcamp pages
  -fields string
    	Comma-separated fields for CSV/TSV columns (e.g. "artist,name,length")
  -format value
    	Format for text input (csv, keyval, tsv) (default tsv)
    	Print available fields for -type and exit
  -server string
    	MusicBrainz server hostname (default "")
  -set value
    	Set a field for all entities (e.g. "edit_note=from")
  -timeout duration
    	Timeout for generating edits (e.g. "30s" or "2m")
  -type value
    	Entity type for text or MP3 input (artist, event, label, recording, release, work)
    	Enable verbose logging
    	Print the version and exit

yambs reads the supplied file or URL (or stdin if no positional argument is supplied) and performs the action specified by the -action flag:

  • open: Open edits in a browser using a temporary file.
  • print: Write edit links to stdout (only possible for recordings).
  • serve: Open edits in a browser using a short-lived webserver launched at -addr (useful if you're running yambs in a container).
  • write: Write a webpage containing the edits to stdout.

If you supply a URL, yambs will fetch and parse it.

If you supply a filename, you should also pass the -type, -format, -fields, and -set flags to tell yambs how to interpret the file.


To add multiple non-album recordings for a single artist, you can run a command like the following:

yambs \
  -type recording \
  -format tsv \
  -fields name,length,edit_note \
  -set artist=7e84f845-ac16-41fe-9ff8-df12eb32af55 \
  -set url0_url= \
  -set url0_type=255 \

with a recordings.tsv file like the following (with tab characters between the fields):

Song #1	4:35	info from
Song #2	53234.35	info from

The recordings' names, lengths, and edit notes will be read from the TSV file, and the -set artist=... flag sets all recordings' artist field to the specified artist.

Likewise, the -set url0_... flags add a URL relationship to each recording. seed/enums.go enumerates the different link types that can be specified between entities; 255 corresponds to LinkType_DownloadForFree_Recording_URL.

To edit existing recordings, specify their MBIDs via the mbid field:

yambs \
  -type recording \
  -format csv \
  -fields mbid,name \


c55e74ff-bd7d-40ff-a591-c6993c59bda8,Sgt. Peppers Lonely Hearts Club Band

Note that this example uses the csv format rather than tsv.

More-complicated artist credits can also be assigned:

yambs \
  -type recording \
  -format tsv
  -fields ... \
  -set artist0_mbid=1a054dd8-c5fa-40b6-9397-61c26b0185d4 \
  -set artist0_credited=virt \
  -set 'artist0_join= & ' \
  -set artist1_name=Rush \

(Note that repeated fields are 0-indexed.)

The keyval format can be used to seed a single entity across multiple lines:

yambs -type release -format keyval <release.txt


title=Some Album
artist0_name=Some Artist
packaging=Jewel Case
medium0_track0_title=First Track
medium0_track1_title=Second Track
medium1_track0_title=First Track on Second Disc

seed/enums.go shows that the url0_type=75 line corresponds to LinkType_DownloadForFree_Release_URL.

If you'd like to bulk-add LinkType_Published_Label_Release (ID 362) relationships between the existing label 02442aba and releases 43bcfb95 and a9d8b538, you can set the mbid field to edit the label and seed the new relationships:

yambs -type label -format keyval <label.txt



Pass the -list-fields flag to list all available fields for a given entity type:

yambs -type label     -list-fields
yambs -type recording -list-fields
yambs -type release   -list-fields
yambs -type work      -list-fields

Acceptable values for various fields are listed in seed/enums.go, which is automatically generated from t/sql/initial.sql in the musicbrainz-server repository.

A column in an input file can be assigned to multiple fields by supplying slash-separated field names. For example, -fields name,url0_url/edit_note,length maps the first column to field name, the second column to fields url0_url and edit_note, and the third column to field length.

A column can be skipped by passing an empty field name. For example, -fields name,,length maps the first column to field name, skips the second column, and maps the third column to length.

You can pass Bandcamp, Qobuz, or Tidal album URLs to seed release edits:


The page that is opened will include a link to the album's highest-resolution cover art to make it easier to add in a followup edit.

If you pass a Bandcamp track URL that isn't part of an album, an edit to add it as a single will be created:


You can pass the path to a local MP3 file to use it to seed a (single) release or standalone recording edit:

yambs \
  -type recording \
  -set artist=7e84f845-ac16-41fe-9ff8-df12eb32af55 \
  -set edit_note='from artist-provided MP3 at' \

If the MP3 file contains embedded images, they will be extracted to temporary files so they can be added as cover art.

There's also a yambsd executable that exposes most of the same functionality through a webpage (with some limits to avoid abuse).


There are a bunch of MusicBrainz userscripts that run in the browser with the help of an extension like Tampermonkey to seed edits. They're well-tested, so why not just use them instead of writing a new thing?

Well, at first I was adding a bunch of standalone recordings that I'd downloaded from random musicians' homepages. I couldn't find any userscripts to help with that, since the main focus seems to be seeding releases from major websites. I ended up hacking together a shell script to generate URLs that would seed my edits, but I figured it'd be nice to have something more robust and convenient to use next time.

I had also been using the bandcamp_importer.user.js userscript to import releases from Bandcamp, but I'm nervous about using extensions like Tampermonkey that require permission to modify data on all sites. I'm not so worried about malice on the part of extension or userscript developers, but I have no idea about their security practices and I'm fearful of attackers compromising their computers and uploading malicious versions of their code.

I created a separate browser profile that I could use to run Tampermonkey without exposing any of my (non-MusicBrainz) credentials, but using it was a pain, so I decided to add Bandcamp support to this codebase as well since that's where I get most of my music.

Further reading