⥽ An Informative Introduction to Instrument Inserting ⥼
Or, the workflow of an Instrument Inserter and how to do the job without going crazy, by CatQuest.
Adding and closing instrument tickets
- for new instruments we have "new feature" / "sub-new feature"
- for actual errors we have "bug"
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 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.
- 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
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
If the ticket is not obviously non-actionable, it's now time to research it. This is my general process for that:
Additionally, I have a set of resources I almost always check.
Wikipedia, of course, even if not linked from the article.
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)
- "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)
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 spam -> report to a JIRA admin (if in doubt, report it in #metabrainz on IRC).
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.
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 a Western and a native source disagree, go with the native source.
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 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.
- 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).
- 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".
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.
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 this in parentheses i 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 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.
- 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 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 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
- https://staticbrainz.org/irombook/cello/cello.png (main image, shares the folder name)
- https://staticbrainz.org/irombook/hardingfele/hardingfele_alt.png (alternate image, with _alt)
- https://staticbrainz.org/irombook/keytar/keytar_player.png (player image, with _player)
- https://staticbrainz.org/irombook/xylophone/icon.png (icon, just named icon)
- https://staticbrainz.org/irombook/ngoni/ngoni_donso.png (a subtype stored in the same folder)
- https://staticbrainz.org/irombook/cabasa/cabaça.png (a somewhat different, but closely related instrument stored in the same folder)
How to deal with community friction
- 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 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! (unless you're already an expert on musical instruments, but even then 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!