instead of vaporwave
FISHWAVE! no. Instrument addition stuff!
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.
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.
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 menues, after $name and data options (for simplicity the url is https://musicbrainz.org/instrument/create anyway)
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 & 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?)
- children an obsolete type, change this to something else away from this!
- part of(cardinality) if this instrument is part of an Ensemble or a Family see https://beta.musicbrainz.org/relationship/5ee4568f-d8bd-321d-9426-0ff6819ae6b5
- derived from/derivations (cardinality) if it is derived, developed, based on or evolved from of another. instrument see https://beta.musicbrainz.org/relationship/deaf1d50-e624-3069-91bd-88e51cafd605
- related instruments (both ways) I tend to use this less these days in deference to derived. 
- is hybrid of/has hybrids (cardinality) An instrument can be a combination of other instruments, often an Artist$entity will take an idea from another related instrument and combine it with something else to create a new thing. (be adviced about novelties however!) see https://beta.musicbrainz.org/relationship/2f522cbc-46f9-409b-9957-d0308d0899ef
- type of/subtypes (cardinality) This is the most used rel, it is for the instrument-tree in general, A cello is a bowed string 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.
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 https://github.com/loujine/musicbrainz-scripts/blob/master/mb-edit-add_aliases.user.js 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
- https://digitalstamp.suppa.jp/musical_instruments_r/index.html in english but older
- https://graphic.nobody.jp/illustrations/index.html usually has images of people playing instruments rather than just the instruments alone, but if these are the only ones found
often in addition he has blogs like
- https://gakki5.blogspot.com/ (see the links also)
- https://irom-gakki.blogspot.com/search/label/%E3%82%AE%E3%82%BF%E3%83%BC?updated-max=2010-03-25T13:00:00%2B09:00&max-results=20&start=20&by-date=false search
- etc etc etc
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 https://digitalstamp.suppa.jp/musical_instruments-chordophone/bowed_strings.html is a rare list of images without people playing them, and on https://animal.tyabo.com/musical_instruments/2string_instruments.html is a great list of various stringed instruments but these are older.
I strongly recommend installing https://github.com/Arnie97/katakana-terminator 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 https://saisaibatake.ame-zaiku.com/gakki/r-musical_instruments.html 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 https://staticbrainz.org/irombook/ on github https://github.com/metabrainz/irombook-instrument-images in the format of https://staticbrainz.org/irombook/$instrumentname/$instrumentname_(possible_variation).png
- cello/cello.png (main)
- hardingfele/hardingfele_alt.png (alternate)
- keytar/keytar_player.png (player)
- xylophone/icon.png (icon)
- ngoni/ngoni_donso.png (a sub type)
- cabasa/cabaça.png (an alternative, but related instrument)
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
I haven't written this part yet, oops!
- 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.
- 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"