An Informative Introduction to Instrument Inserting
Or, the workflow of an Instrument Inserter and how to do the job without going crazy, by CatQuest.
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 https://musicbrainz.org/instruments - 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 https://tickets.metabrainz.org/projects/INST (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 CatQuest
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), you should close it. 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 not be add (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 me (for example because it's just not an instrument ticket at all), I close it as "invalid" (but this doesn't happen very often and even then the ticket should usually be *moved* to the appropriate project rather than 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 often combined with another version on tickets. These are 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 won'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". "electric" is for things that have been electrified (such a piano with pickups), while "electronic" is for instruments that work with digital audio signals (such a synthesizer keyboard). 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.
If the ticket is not obviously non-actionable, it's now 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 on INST tickets):
Wikipedia, of course, even if not linked from the article.
MIMO (the Musical Instruments Museum Online, https://mimo-international.com/MIMO/search.aspx), 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 https://chandrakantha.com/music-and-dance/instrumental-music/indian-instruments/ 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, and the accompanying music CD has of course already 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 https://www-jstor-org.wikipedialibrary.idm.oclc.org/action/doBasicSearch?Query=SEARCH (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 https://wiki.musicbrainz.org/How_to_Add_Instruments#Not_to_be_added_as_instruments (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 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?
- 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!
- 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 https://musicbrainz.org/instrument/create directly.
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). We have other fields for more info.
- 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 on the way MusicBrainz works, it is currently possible for regular users to add this relationship via the artist/label screen, and sometimes they use it when they want to say an artist plays the instrument, since there's no relationship for that. Happily there are users patrolling and reverting these edits so fast that you almost always won't have to do it yourself.
- 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.
- 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. If that's all you know, 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: "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 is uncommon).
Then click Enter edit and you'll be mostly done! But check the alias section below for a second useful step.
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 that a string quartet consists of 2 violins, 1 viola and 1 cello. "Optional" can be used to indicate that 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!
actually no, 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 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 though, since it means aliases won't sort as according to the language in question (for example, Japanese names should probably use Hiragana instead of Latin for sort names). Once it is possible to list aliases as transliterations, I will change the format and try to use the actual script sort name, when I can find it.
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 on alias adding.
A little bit about image (IROM) extraction
Since we can 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 on the repository irombook-instrument-images.
IROM has a set of websites with often somewhat different information (and sometimes different images):
- https://digitalstamp.suppa.jp/musical_instruments_r/index.html (in English but older)
- https://graphic.nobody.jp/illustrations/index.html (which usually has images of people playing instruments rather than just the instruments alone, but those are better than nothing if you can't find anything else)
In addition they have blogs like:
- https://gakki5.blogspot.com/ (see the links also)
Usually saisaibatake will have the best images, but occasionally you will find something surprising in digitalstamp. And at times graphic.nobody will have pages that will *link* to a page (on saisaibatake) that is different than the usual one. 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 one page do always check every one, in case they contain yet more links!
I also take the icon in front of the instrument name as seen in the sidebar and the dictionary page, 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 https://staticbrainz.org/irombook/ - you'll want to upload them to folders for the instrument and name them following the convention below to get images in the format https://staticbrainz.org/irombook/$instrumentname/$instrumentname_(possible_variation).png
- cello/cello.png (main image, shares the folder name)
- hardingfele/hardingfele_alt.png (alternate image, with _alt)
- keytar/keytar_player.png (player image, with _player)
- xylophone/icon.png (icon, just named icon)
- ngoni/ngoni_donso.png (a subtype stored in the same folder)
- cabasa/cabaça.png (a somewhat different, but closely related instrument stored in the same folder)
As seen above, sometimes a related instrument should just be in the same folder as that one. Just 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 nor 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.
I've learnt 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! (unless you're already an expert on musical instruments, but even then you'll still probably learn something). Try to have fun with it, not get too frustrated with the most challenging/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!
Or, to paraphrase the LEGO Movie: Instruments are awesome *and* instruments are cool when you're part of a team! Enjoy your time with them!