User:ApeKattQuest, MonkeyPython/INSTwave

From MusicBrainz Wiki
Jump to navigationJump to search

⥽ An Informative Introduction to Instrument Inserting ⥼

Or, the workflow of an Instrument Inserter and how to do the job without going crazy, by ApeKattQuest.

Basic tools

Hi! If you're here, you probably need to (temporarily or permanently) substitute 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 this list does not list aliases, so if an instrument seems not to be there, it can't hurt to search for it using the website search too, just in case it is in the database 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.

I've created a fair amount of filters that I find useful to see subsets of the tickets. To get a list, go to this search page and search for owner ApeKattQuest

Adding and closing instrument tickets

Usually, you will not need to add tickets for things yourself - the community will provide a steady trickle of tickets. Now, while we have the documentation that explains how to do just that, there will be adders that will not have read it (or understood, or cared) so you'll often get tickets that will need to be improved.

The Jira system allows setting different types for the tickets. The different types are explained in the documentation above, but basically:

  • for new instruments we have "new feature" / "sub-new feature"
  • for tickets that require updating or changing, description or adding aliases we have "improvement" / "sub-improvement"
  • for actual errors we have "bug"
  • "task" is rarely used but it can occasionally be useful for large unspecific things like "research the difference between these concepts" or "translate this wiki page"

If we have several very related tickets (such as different instruments for a specific instrument family) I usually create a "mini-version" type ticket to collect them, with the related tickets linked as sub-tickets of that.

Once you're done with a ticket (whether you've done what it asks for or decided you should not), it should be closed. You will need to select a resolution:

  • for fixed finished tickets, close as "fixed" and add a comment with a link to the finished instrument if adding a new one or a description of what has been done (e.g. "added all aliases and fixed description"). Also, if adding a new instrument, link to the ticket from the edit note so that they are connected in both ways.
  • for tickets that are duplicates, close as "duplicate", point to the one we already have in a comment, and add a Jira duplicate link too. Recently I've also been upping the priority of still-open tickets which receive duplicates, since that suggests multiple people want it.
  • for tickets which you have decided will not be added (usually novelty instruments and the like), close as "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, close it as "incomplete" - these can always be reopened if someone has more information and adds it!
  • in situations where something is totally not actionable by the Instrument Inserter (for example because it's just not an instrument ticket at all), close it as "invalid". (This doesn't happen very often and even then the ticket should probably instead be *moved* to the appropriate project rather than being closed).

A little bit about fix versions

As mentioned above, for each new group of related tickets I want to work on I make a "fix version". Mine always have some silly name because I'm easily amused and life's too short not to be silly; it's up to you whether to continue the tradition or not. For example, my second batch of Māori instruments is in the "Taonga puortwo" version.

There's also a few versions that have no tickets and are only used in "affects versions" on tickets. They are "Strings 'n' Things (...(formerly just Strings))" and "Instruments IV: Electric Boogaloo". They might get repurposed or deleted in the future, but for now you can just ignore them.

You'll also notice a couple of GCI versions, named with parentheses, which are usually combined with another version on tickets. These were related to the (now defunct) Google Code-In program, in which high school students from around the world helped us (among other things) to research tickets and improve our instrument coverage.

A version shouldn't be officially marked as released until all tickets in it are done. This can take a long time: the largest version by far, "Ensemble This!", was started in 2018 and is yet to be finished at this time.

A little bit about components

Components are used to indicate which kind of instrument the ticket is about. As such, there are components for string, wind & percussion instruments, an "ensemble/family" component for instrument groupings, and finally "electric" and "electronic". "electronic" is for instruments that work with digital audio signals (such a synthesizer keyboard), while "electric" is for things that have been electrified (such a piano with pickups) and is therefore always used together with another component. There's also a "modify existing instrument" component, which should be self-explanatory.

A little bit about labels

Labels are used to add "tags" to tickets that wouldn't fit a version nor a component. They are shared between projects, so be careful about creating these because they'll also appear for everyone else using JIRA.

  • "GCI" was set on tickets we thought would be interesting for Google Code-in students. Quite a few instruments have this label.
  • "Extensive research" was created specifically for instrument tickets, and it marks the ones where a short research process is not enough to close the ticket. These are **difficult** instrument tickets.

Researching instruments

If the ticket is not obviously un-actionable, it will now be the time to research it. This is my general process for that:

To begin with, usually the ticket will have a Wikipedia link. I start by following that and reading the article, and possibly also reading the Swedish/Danish/Norwegian Wikipedia articles as well if they exist (replace those with whatever languages you happen to speak, but the general idea is that sometimes different Wikipedia articles provide different information and sources).

I will then do a DuckDuckGo search for the instrument to see what I can find, as well as following any other links in the ticket.

Additionally, I have a set of resources I almost always check.

For string instruments especially (which at least as of 2022 are the most common group of instruments requested as INST tickets):

Wikipedia, of course, even if not linked from the article.

Oxford Music Online ( which while is usually a paid resource, I have full access thanks to the [Wikipedia Library] ( (the reason this was granted me was that I also work to create and improve wikidata items about instruments, but how this is done is definitely out of scope for this article.)

MIMO (the Musical Instruments Museum Online,, which is a consortium aggregating musical instrument data from museums all over Europe and also maintains the Hornbostel–Sachs classification of instruments.

There are also countless blogs and other websites that have specialist info, such as for Indian instruments.

Finally, there are the IROM sites, where you can sometimes find images (that we can use in MusicBrainz, there's a section further down just for that). Someone who speaks Japanese could possibly get additional info from the pages as well as the images.

Then I have some offline sources I also make use of; if you have to replace me, I'd suggest trying to get your hands on some of them! Your library might have a copy (since my library is where I got most of them):

  • 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, an excellent book that I've gotten from the library and I wish I owned!)
  • "Taonga pūoro: Singing Treasures (The Musical Instruments of the Māori)" by Brian Flintoff (when working on Māori instruments I borrowed this book from the library several times, (it has an [accompanying music CD], which of course has been added to MusicBrainz ;) - another book I wish I owned)

Else I just see what books on the specific topic I'm looking into are available at the library and borrow them. I also go through (and, sometimes, other less-reputable sources of scholarly articles) searching for any article or book on the topic that could also help. For example, while trying to piece together how ancient Indian string instruments connect to each other, 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 inclusion.

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 rest of 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, 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 each other

If there is one source contradicting several others:

  • unless it is very reputable, ignore it.
  • if it is reputable and the others may in fact be all following one or a few not so reputable original source(s), go with the contradicting source (but be discerning).

If two reputable sources contradict each other (also applicable if more sources do, but they seem based on these two reputable ones):

  • if a piece of information seems like it might be variable (rather than wrong in one case), try to combine the info (e.g. if one source says 4 strings and 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 sources can be a bit like the telephone game: in different places different bits of info are given different weight, and then when the whole story gets retold with omissions, you eventually get results that seemingly contradict each other.
  • if it is an openly known fact that there are several leading ideas that contradict each other, try to include both in your description.
  • if all sources list conflicting information, just omit it entirely. It is better to omit unclear information than to perpetuate wrong data.
  • if a Western and a native source disagree, go with the native source.
  • check what other language Wikipedias say, and investigate their sources. It might be a translation error. You can ask for help with translations, or use machine translation if needed.

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

What makes a source reputable?

Reputable sources:

  • in general academic, sourced, researched stuff is good for (Western) musical instruments.
  • hobbyist blogs that are written by people with a passion for whatever you are looking into; often this will be your best bet with native and non-Western instruments (if only reading in English, in the native languages there is often academic, sourced, researched data 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 about; if possible engage with them and ask more. Naturally be discerning in any case!

Unreputable sources:

  • sites that *sell* instruments (unless data also matches other better sources).
  • wikis (including Wikipedia, but specially smaller ones like Fandom), are not a great main source. Disregard them unless they link to better, reputable sources.
  • be on the lookout for badly written text; while it *might* just be badly translated or written by a non-native, it often 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 menus. Or you can just go to directly.

add instrument.png
The "Add instrument" screen

Once you're done researching and have enough data, it's time to create the instrument. You'll want to put together a disambiguation and a description.

  • The name should always be in lowercase, unless an actual proper noun is part of it (e.g. "Saraswati veena", "French horn", "Rhodes piano"). Do not include anything but the name (even if there's other instruments with the same name). For that we have better fields:
  • The disambiguation should be as short and clear as possible. It should just contain the main idea of what makes the instrument different from others. As such, include where and/or when it was used, what it is made of, and some other defining qualities: if the neck is short write "short-necked", if it is goblet shaped write "goblet drum"... Just combine all this to create the disambiguation: examples could be "Namibian short-necked lute" or "ancient cedarwood goblet drum" or "double-reed brass used in western orchestra", etc.
  • The type is one of "Percussion" (membranophones, in here also idiophones), "Wind" (aerophones), "String" (chordophones), "Electronic" (electrophones), as well as "Family", "Ensemble" and "Other". The choice should usually be obvious.
  • The description is where the majority of your research results. Try to use as few helper conjugations as possible, don't repeat the name of the instrument, be concise and get to the point as fast as possible. As an example: "Used in traditional dance and religious ceremony, its 40 cm long, heavily decorated bamboo soundbox has 3-4 metal strings plucked by bone plectrum."

In the Relationships section you can connect the instrument to other entities in MusicBrainz:

  • Area: linking the instrument to the area(s) where it is from. You can also use relationship credits for historical place names and instrument names.
  • Artist / Label: if it was invented by a person or company, add this relationship. Try to find the invention year and list it on the relationship. It is acceptable to add a new artist or company/label for the inventor(s) of an instrument. (Note: due to limitations in the way MusicBrainz works, it is currently possible for regular users to add this relationship from the artist or label side, and they will sometimes erroneously use this when trying to say that an artist plays an instrument, since such a relationship does not exist yet. However, happily there are users patrolling and reverting such edits, and so fast that you almost never have to do that yourself!)
  • Instrument:
    • children is an obsolete type from before we had more specific ones. If you see it, try to change it to something more specific:
    • part of/consists of is to be used if this instrument is part of an ensemble or a family. (see below for details on this)
    • derived from/derivations is to be used if this instrument is derived, developed, based on or evolved from of another instrument. For example, the electric violin is derived from the violin.
    • related instruments/related to is kind of obsolete as well, since it doesn't specify how two instruments are related. But if this is all you can find out, it's probably better than nothing, but if you know and we don't have a relationship for it yet, consider requesting that to be added instead (with a STYLE ticket in JIRA).
    • hybrid of/has hybrids is to be used if this instrument is a combination of other instruments. Sometimes an artist will get an idea to combine the body of one instrument with the mouthpiece or some other mechanism of another, for example. Be sure to only add hybrids that are reasonably established, rather than novelties, however!
    • type of/subtypes is the most common instrument relationship and the basis of our instrument tree: e.g. "talharpa" is a type of "bowed lyre" which is a type of "bowed string instruments" which is a type of "string instruments".

Finally, the External Links section is where you should paste the Wikidata link, the image link for IROM/StaticBrainz (see the related section 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 the scope of this guide).

In the edit note you should enter a link to the JIRA ticket, and any interesting/unusual extra comments you have, if needed (which has been up to now uncommon, but can become much more useful in the future.).

A little bit about families and ensembles

As mentioned above, the part of/consists of relationship is mostly used for families and ensembles.

Families are a more "fuzzy" type of instrument. For example, the "lute family" encompasses most necked string instruments. A family can itself contain a family ("lute family" contains "guitar family"), although this can lead to some problematic overlap with "type of".

Ensembles are a lot more defined. These are standard groupings with mostly defined components, such as "string quartet", or combination of instruments like "pipe & tabor", "guban" or "samba drums". This includes even large groupings, such as a western orchestra or a gamelan.

This relationship can have two attributes: optional and amount. These are both used for ensembles. "Amount" can be used to indicate e.g. that a string quartet consists of 2 violins, 1 viola and 1 cello. "Optional" can be used to indicate that e.g. a string quintet consists of 2 violins and other three string instruments which can vary: 1 or 2 violas, 1 or 2 cellos, and optionally a double bass.

More attributes can be requested if needed.

Press "Enter edit!" and we're done! Yay!

Well, actually not quite, because there is still:

A little bit about aliases

Aliases help users find and use the correct instruments whatever the language of their source, so we want to have as many as we can. Generally I will start by checking the Wikidata list of names for an instrument (which most commonly means "the names used by the Wikipedia pages in every available language"). I will also add other actual aliases written on that Wikidata page (in the "Also known as" column). Additionally, some Wikipedia pages will sometimes have more names in their article text that haven't been copied to Wikidata (usually the first or second sentence includes them in bold and/or italics). 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 (often as "instrument name").

For aliases in a script other than Latin I make an exception on the general alias guidelines, and follow the common practice for artist names and sort names instead. That is, for the alias name I use the original script, but for the sort name I use a Latin transliteration. This makes it easier for me to see what an alias is, and the connection between original and transliterated names. It does have some issues however, since it means aliases won't sort according to how the language in question (for example, Japanese names should probably use Hiragana instead of Latin) should be sorted. Once it is possible to list aliases as transliterations, I will change the format and try to use the actual script's sort name.

In addition, there are a few number of languages for which we have no Locale - in these cases I will write the lowercase name of it in parentheses in the sortname. It should be possible to programmatically move these to the right place should these locales be added in the future.

For actually adding the aliases I use a script that loujin created per my request. This allows me to submit several aliases at the same time; since some of the more well documented instruments can have over 20 aliases + alternate names, it is an indispensable tool to avoid spending hours adding aliases.

A little bit about image (IROM) extraction

Since we [no longer] use Wikimedia Commons images to illustrate entities, we looked into possibilities and found a Japanese illustrator named IROM who is an enthusiast of musical instruments and makes all their illustrations free for reuse. We store the ones we want to use on GitHub in the repository irombook-instrument-images.

IROM has a set of websites with often somewhat different information (and sometimes different images):

In addition there are blogs like:

Usually saisaibatake will have the best images, but occasionally digitalstamp will surprise you. And at times graphic.nobody will have pages that will *link* to a page (on saisaibatake) that is different than the usual one. Additionally, there's also a list of string instrument images without people playing them, and another, older one.

I strongly recommend installing katakana-terminator in order to be able to see more quickly what things are on IROM's sites (unless you can easily read kana, of course).

In general, I 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 an /instrument2 page that may have other images. Sometimes there is even a third page obtainable by clicking the image on the second page, and if there's more than one image on any of these pages, do always check every one of them, as they may contain even more links!

I also take the icon in front of the instrument name as seen in the sidebar and the dictionary pages, to also upload it as a separate icon image. 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).

You can upload the instrument images yourself, or contact a member of the team for it (reosarevok is a good bet if around). Images uploaded to the irombook-instrument-images repository are automatically made available as static PNG files for MusicBrainz use on the domain - you'll want to upload them to folders for the instrument and name them following the convention below to get images in the format$instrumentname/$instrumentname_(possible_variation).png


As seen above, sometimes a related instrument should just be in the same folder as that one. Use your own judgement to decide when to split or keep together. It often makes sense to keep instruments of a close family (like ngoni, kacapi, etc.) in the same folder, unless they're very well known and would be expected to be separate (violin/viola/cello). Replace spaces in the names with underscores, but use hyphens if they are part of the name itself. If in doubt, ask reosarevok to do a quick check to make sure the choice makes sense.

How to deal with community friction

How to deal with community friction when decisions that you are sure are better for the data lead to arguments and complaints about how a specific instrument should or should not have been added, or a name is better than another, or a change will make it harder to add instrument performer relationships?

  • First thing, don't panic or get angry! People can have different opinions and that does not mean anything against you personally (unless you get personal attacks, which you should always report to the community manager).
  • Don't just "give in" and give the people what they (think) they want and compromise data, unless you become convinced that you made a mistake.
  • Learn to walk away and ignore toxic people and arguments; don't engage with toxic arguments if you can at all avoid them.
  • Always listen to constructive opinions and do reconsider your choices, but try to always get a third person's opinion about the issue before you make a decision to change your original choice to make sure you're not just doing it to avoid the situation.
  • Simultaneously, don't be haughty and think you always know best, even if you are a specialist or have a doctorate in instruments there is always room for more knowledge and points of view!

In closing

I've learned a lot about instruments in my years as the Instrument Inserter, and I'm still learning every time I look into some new ticket. If you're now in charge of instrument insertion for a while, or even permanently, you're probably going to learn a lot of stuff too! (even if you're already an expert on musical instruments, you're still going to probably learn a lot!). Try to have fun with it, not get too frustrated with the most challenging or annoying bits, and don't forget that you don't have to do it all on your own; the team and the community are there to help, at least most of the time!

To paraphrase the LEGO Movie: Instruments are awesome *and* instruments are cool when you're part of a team! Enjoy your time with them!