From MusicBrainz Wiki
Jump to navigationJump to search

instead of vaporwave

FISHWAVE! no. Instrument addition stuff!

Basic tools

Hi! If you're here, you probably need to (temporarily or permanently) substitute me as the Instrument Inserter. In that case, you'll need to understand how I've organized the whole instrument thing so far, so let's start from the basics:

The list of all the instruments already in MB is at - keep in mind it does not list aliases, so if an instrument does not seem to be there, it can't hurt to search for it with the search too just in case we have it under another name.

Instrument requests are tracked in JIRA. We have an INST (instruments) project for that, which you can find at (you can also check the statistics dashboard for more detailed links, or a list of all issues).

I often use fix versions to group tickets more or less thematically and then work on one of them all together.

Adding and closing instrument tickets

First the ticket must be selected. usually I square related things of in "mini-version" type ticket, where related tickets are subtickets of that.

  • for new instruments we have new feature/sub-newfeature
  • for tickets that require updating or changing, description or adding aliases we have improvement/sub-newimprovement
  • for actual errors we have bug
  • task is seldom used but occasionally for large unspecific things like "research the difference between these concepts or "translate this wikipage"

When closing the ticket thus status is used

  • for fixed finished tickets, just "fixed" and a comment with a link to the finished instrument if adding a new one/description of what has been done (eg "added all aliases and fixed description")
  • for tickets that are duplicates, just "duplicate" and close them while pointing to the one we have in a comment and linking it "as a duplicate" of that one. recently I've also been upping the priority of tickets which receive duplicates.
  • for tickets which are deemed to not be added (usually these are novelties (link to see how to add $ novelties)) just "won't fix" with a comment explaining why and a link to the appropriate guideline.
  • if the ticket does not have enough information and a search on the internet has yielded no usable information, i close it with "incomplete" these can always be reopened if someone has more information and adds it!
  • for situations where something is totally not actionable by me, not an instrument ticket etc, it would be closed as "invalid" (this doesn't happen very often and usually the ticket should be *moved* to the appropriate project)

Ticket should have at fixing closing have a comment with a link to the instrument and the instrument add on musicbrainz should have a link to the associated ticket.

Researching instruments

On the actionable tickets thus:

usually the ticket will have a wikipedia link, we follow hat and read the article, possibly also i will read swedish/danish/norwegian wikipedia as well I will then do a duckduckgo search as well as following any other links in the ticket.

I have a set of resources I almost always look up in:

for string instruments especially(of which as of current (2022) still is the largest group of instruments on INST tickets)

Next there is of course wikipedia. but also:

there is also countless blogs, sites etcetera that have specialist info, such as for indian instruments

finally there is irom for images (but someone japanese could possibly get info from pages)

(more on image abstraction later)

Then I have some offline sources I loom in:

  • The excellent The New Grove Encyclopedia of Musical Instruments I-III 1984 edition
  • The History of Musical Instruments by Curt Sachs (only borrowed from library)
  • Percussion Instruments and their History by James Blades (for percussion instruments, only borrowed from library, it is an excellent book I wish I owned)
  • Taonga pūoro: Singing Treasures (The musical instruments of the Māori) by Brian Flintoff (for the Māori instruments I extensively borrowed from the library this book several times (its music CD has already been added to mb ;)) another book I wish I owned)

else I borrow from the library any topic books if they have them, I also go through ([off] and searching for any article or book of the topic for what I'm adding

(example: while trying to piece together how ancient Indian string instruments connect together I searched extensively for these "Veena" instruments in all these sources.)

How to determine if a ticket is not actionable?

A ticket can be not actionable because:

  • it has insufficient information, calls for more information have not yielded any result in a fair amount of time and searching in the ways explained above has found nothing good enough -> close as incomplete.
  • it is a duplicate -> close with the appropriate resolution as explained above.
  • it is a valid ticket, but not an instrument ticket -> move to the appropriate project (such as MBS for MusicBrainz bugs).
  • it is spam -> report to a JIRA admin (if in doubt, report it in #metabrainz on IRC).
  • it is a valid instrument or issue, but nothing can be done right now because something else is blocking it, such as an implementation detail (such as MBS-9642 blocking INST-658) -> set the status as "blocked" with an explanatory comment.

Which leaves then the difficult last case, "it is an instrument, but it's not reasonable or useful to add it to MusicBrainz". Whether this is the case often needs to be decided on a case by case basis, but in general the logic for deciding this has been outlined in (which was written specifically in order to have a document that describes the rationale for inclusion/non-inclusion).

In general, any instrument that seems to be exclusive to a specific artist (a "signature move", to borrow a Pokémon term) is likely to be too much of a novelty for addition.

If after reading this the right decision still seems unclear, then as mentioned it will just come down to your own judgement! As you can see from the document, all the cases have exceptions and counter arguments, because nothing is ever actually that clear in the music world!

So what I've usually done when in doubt is to just ask other people in the team or the community for their point of view, chiefly reosarevok as the style leader, sometimes Freso or yvanzo for things that they might know more about, such as folk instruments.

Reaching out to the community to get specific opinions, research help and translation help for useful sources in languages you can't read can be very rewarding! (we have a fairly international community so if you're not sure who speaks the language you need, just ask around on IRC or on the forums, and often you'll find help. Hopefully we will keep attracting more and more people from all around the world who can help with this in the future - yet another reason why it is important to make MusicBrainz easy to use by everyone!)

However keep in mind that the community is mostly comprised of volunteers with their own interests, and sometimes even a simple question which from your point of view seems to be simple to answer can turn into a long discussion that might not even answer the question. It's always worth engaging with the community though, but try not to get too discouraged if you end up not getting any useful answer. Remember that anything can always be edited if an answer arrives way later when you were no longer expecting it.

What to do when two (or more) sources contradict eachother

if there is one source contradicting the others:

  • unless very reputable, ignore it.
  • if reputable and the others may infact be sourced to one or a few not so reputable source(s), go with the contracting source (but be discerning)

if two (or several where it is conceivable that the others source either of the two) reputable sources contradict eachother especially:

  • try to find a synthesis of the two (if one says 4 strings an the other says 6 write "4-6 strings")
  • try finding a third reputable independent source and see what it says. it might clarify why the two seem to disagree (sometimes things in these are a bit like the telephone game, in different places bits are given different weight and then when the whole story gets repeated with omissions and finally in a few iterations results seemingly contradict eachother)
  • if it is an open known that there are several leading ideas that contradict eachother, try to include both.
  • if ALL sources disagree with a point, omit it entirely, in this case it is speculation on the part of the writers because it is actually not known.
  • if a western and native source disagree, go with the native source.
  • check (get machine or help with translation) what other language wikipedia say, and see their sources. it might be a translation error.

In the end if it is still unclear, simply write "it is unclear if" since this is literally true.

What makes a source reputable?

  • in general academic, sourced, researched stuff is good for (western) musical instruments
  • hobbyist blogs that are written by people with a passion for whatever - often this will be your best bet with native and non-western instruments (if only reading in english, in the native languages, there are sure academic, sourced, researched stuff as well.)
  • reputable data can come from surprising places, like a reddit thread or blog, never assume that hobbyists don't know what they're talking bout, if possible engage with them and ask more. Naturally be discerning in any case


  • sites that *sell* instruments - (unless data also collaborates other better sources)
  • things like wikiwand or fandom or random crap, disregard these as main sources and only look if they collaborate a better reputable source.
  • be on the lookout for badly written text, it *might* just be badly translated/nonenglish person writing, but usually it also means the data is less reputable.


How To (actually) Add An Instrument

The link to add Instruments is in the "Admin" dropdown at the rightmost of the user menues, after $name and data options (for simplicity the url is anyway)

add instrument.png (the add instrument screen)

After all is researched and data is found one makes the instrument. a Disambiguation and a Description.

  • The Name should always be lovercase, unless an actual proper noun is in it, (eg "Saraswati veena"). Do not include anything but the name (e.g. like "Swedish lute", unless that is the name)
  • The Disambiguation should be as short and sweet as possible, it should have the main idea up. so you include where or whence it is from, what it is made of and the summary of what makes it distinct. So if the neck is short write "short-necked" if it is goblet shaped write "goblet-drum" etc. combine like "Namibian short-necked lute" or "Ancient cedarwood goblet-drum" or "Double-barrelled brass used in western orchestra" etc.
  • Type is one of "Percussion" (membranophones, in here also idiophones), "Wind" (aerophones), "String" (chordophones), "Electronic" (electrophones), as well as "Family" "Ensemble" and "Other"
    • piano is a string-instrument, shut up.
  • Description! here the essence of your research should go. try to use as few helper conjugations as possible, don't include the name of the instrument, be concise and get to the point as fast as possible; ex: "Used in traditional dance and religious ceremony, it's 40 cm long heavily decorated bamboo soundbox has 3-4 metal strings plucked by bone plectrum."

In Relationships you connect other entities in MusicBrainz

  • Area: linking the instrument where it is from. you can also use rel-credits for historical placenames and instruments
  • Artist[1] & Label: if it was invented by a person or company, add this, try to find at-least a circa year - it is permissible to add a new artist for the inventor of instruments (but unsure about adding new labelcompanies just for instruments?)
  • Instrument:

a bit about Families and Ensembles

    • consists of (opposite of "part of")

I have put this here as it is a relationship used for Families and Ensembles especially Like above, a violin is a member of the viola (not viol) family, and a member of several ensembles

Families are new type of alround more "fuzzy" instrument, like "lute family" which encompasses most necked string instruments. A family can itself contain a family (lute family containing guitar family) there might be some problematic overlap with "type of".

Ensembles are a lot more defined. These are stings like "string ensemble" or combination of instruments like "pipe & tabor", "guban" or "samba drums", even large things like Western Orchestra or Gamelan are ensembles.

else see

Consists of can have attributes: optional and amount. These are both used for Ensemble, for example and ensemble of 2 violins a viola and an optional cello.

More attributes are possible.

  • finally, the External Links section! here you will paste the Wikidata link, the image link form IROM/staticbrainz (see below) and any very interesting sites that look stable.
  • it is permissible (and encouraged!) to create wikidata items for instruments that do not have them (but their creation is out-of-scope of this guide, maybe some other time :|)

For the Edit note: we write the jira ticket and any intresting things if there is something unusual (this will be rare, usually)

"Enter edit! and we're done!

actually no, we still have:

a bit about aliases

(technically parts of this part goes against established guidelines of how things are *supposed* to be, but I do it this way anyway because it's easier and can be retrofitted should the mb schema be updated (hopefully) in the future )

Generally I will go by the Wikidata list of aliases (ie other lang wiki's) names for an instrument is. I will also add other actual aliases written on that wikidata page, additionally some wikipedia pages will sometimes have more names in their article text (usually the first or second sentence includes them in bold/italiceds) I will include these (provided they don't duplicate any actual language names) as "search hint"

Then I will add any extra names/spellings from Grove or Oxford dictionary (or any other source) as an alias too.

for aliases in a script other than latin i follow the common done thing for artist names -> that is, for the alias name use the full script but for the sortname of thus, use a latin transliteration

this has some issue in that example, japanese names should probably use hiragana instead

I do this because it is easier to see what an alias is, it's interesting ot see language families, and not to unoften are alternate names transliterations of other scripts as well.

a better way of handling this would be to create a transliteration/script way for aliases

for actually adding the aliases i use which was actually initially request by myself, this creates the ability to submit several aliases at the same time, as some of the more well documented instruments can have over 20 aliases + alternate names it is indispensable a tool.

a bit about image (IROM) extraction

irom has many sites

often in addition he has blogs like

Usually saisaibatake will have the best images, but occasionally digitalstampa will surprise you. sometimes graphicnobody will have pages that will *link* to a page (on saisai) that is different than the usual one. on is a rare list of images without people playing them, and on is a great list of various stringed instruments but these are older.

I strongly recommend installing for being able to quicklier see what things are on IROM's sites (unless you read kana natively of course)

In general go with the largest, clearest and cleanest image, the saisaibatake page for an instrument will sometimes have more images, and clicking on the main image will usually get you to a /$instrument2 page that may have other images. Sometimes there is even a third page obtainable by clicking the image on the second page, and in the event of several images always check every one, usually an image will have an url to a different page, always.

Collect also the icon infront of the instrument name as seen in the sidebar and here it will be uploaded as a small image in the folder as well. finally it can be beneficial to also have an image of a person playing the instrument, especially if any other image if the instrument is older or not as descriptive (or if the playing of the instrument itself is interesting, e.g. keytar)

Instrument image will be uploaded to on github in the format of$instrumentname/$instrumentname_(possible_variation).png


as seen above, sometimes a related instrument should just be in the same folder as that one, use discernation family (like ngoni, kacapi, etc) are usually in the same folder. Names will have spaces as underscores but hyphen if the name itself conceivably can has hyphen.

reosarevok knows the drill.

how to deal with community friction

How to deal with community friction when correct decisions lead to argument and complaints about "making it impossible to add instruments unless you're a scholar" etc?

  • first thing, Don't panic!
  • Don't just "give in" and give the people what they (think) they want and compromise data
  • learn to walk away and ignore toxious people and arguments
    • don't engage with toxic people, ignore them.
  • always second guess yourself, but get a 2 persons opinion about if your initial logic was all that faulty to begin with

in closing

I haven't written this part yet, oops!

  1. due to MB schema limitations, it is possible for regular users to add this rel via the *artist* screen, happily there are users patrolling and reverting these edits so fast that you almost always won't have to do it yourself.
  2. I predict that "related" might be made obsolete some time in the future, it is of course better to specify *how* it is related. new types can be added instead of the vague "related"