Difference between revisions of "User:CatCat/INSTwave"

From MusicBrainz Wiki
Jump to navigationJump to search
m
 
(50 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  +
= ⥽ An Informative Introduction to Instrument Inserting ⥼ =
instead of vaporwave
 
   
  +
Or, the workflow of an Instrument Inserter and how to do the job without going crazy, by CatQuest.
FISHWAVE! no. Instrument addition stuff!
 
   
  +
== 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 extant instruments on mb are https://musicbrainz.org/instruments
 
The Instrument project on jira is situated https://tickets.metabrainz.org/projects/INST/summary/statistics
 
it shows an overview of stats and the like (I also have some dashboard named "blup" and stats images for my own uses)
 
   
  +
The list of all the instruments already in MB is at https://musicbrainz.org/instruments - 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.
https://tickets.metabrainz.org/issues/ is the view for all the issues.
 
   
  +
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 [https://tickets.metabrainz.org/projects/INST/summary/statistics the statistics dashboard] for more detailed links, or [https://tickets.metabrainz.org/projects/INST/issues a list of all issues]).
I have some filters i use to delimit tickets and find things. (such as https://tickets.metabrainz.org/browse/INST-776?filter=11020 for "ensemble this!" fix version)
 
   
  +
I often use [https://tickets.metabrainz.org/projects/INST?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page fix versions] to group tickets more or less thematically and then work on one of them all together.
Fix versions are used for an overarching large compound.
 
   
  +
I've created a fair amount of filters that I find useful to see subsets of the tickets. To get a list, go to [https://tickets.metabrainz.org/secure/ManageFilters.jspa?filterView=search this search page] and search for owner <u>CatQuest</u>
First the ticket must be selected. usually I square related things of in "mini-version" type ticket, where related tickets are subtickets of that.
 
* for new instruments we have new feature/sub-newfeature
 
* for tickets that require updating or changing, description or adding aliases we have improvement/sub-newimprovement
 
* for actual errors we have bug
 
* task is seldom used but occasionally for large unspecific things like "research the difference between these concepts or "translate this wikipage"
 
   
  +
== Adding and closing instrument tickets ==
When closing the ticket thus status is used
 
   
  +
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 [[How_to_Add_Instruments#How_to_request_an_instrument|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.
* for fixed finished tickets, just "fixed" and a comment with a link to the finished instrument if adding a new one/description of what has been done (eg "added all aliases and fixed description")
 
* for tickets that are duplicates, just "duplicate" and close them while pointing to the one we have in a comment and linking it "as a duplicate" of that one. recently I've also been upping the priority of tickets which receive duplicates.
 
* for tickets which are deemed to not be added (usually these are novelties (link to see how to add $ novelties)) just "won't fix" with a comment explaining why and a link to the appropriate guideline.
 
* if the ticket does not have enough information and a search on the internet has yielded no usable information, i close it with "incomplete" these can always be reopened if someone has more information and adds it!
 
* for situations where something is totally not actionable by me, not an instrument ticket etc, it would be closed as "invalid" (this doesn't happen very often and usually the ticket should be *moved* to the appropriate project)
 
   
  +
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.
Ticket should have at fixing closing have a comment with a link to the instrument and the instrument add on musicbrainz should have a link to the associated ticket.
 
   
  +
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.
on the actionable tickets thus:
 
  +
* 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 ===
usually the ticket will have a wikipedia link, we follow hat and read the article, possibly also i will read swedish/danish/norwegian wikipedia as well
 
I will then do a duckduckgo search as well as following any other links in the ticket.
 
   
  +
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.
I have a set of resources I almost always look up in:
 
   
  +
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.
for string instruments especially(of which as of current (2022) still is the largest group of instruments on INST tickets)
 
   
  +
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.
* http://www.atlasofpluckedinstruments.com/
 
* http://stringedinstrumentdatabase.aornis.com/t.htm
 
   
  +
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. <!--\\and was finished in ($date) the reason for this delay was the same as all other delays worldwide in the years 20-22.-->
Next there is of course wikipedia.
 
but also:
 
   
  +
=== A little bit about components ===
* http://oxfordmusiconline.com/ (I have full access via https://wikipedialibrary.wmflabs.org/ )
 
* https://mimo-international.com/MIMO/search.aspx
 
   
  +
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 is also countless blogs, sites etcetera that have specialist info, such as https://chandrakantha.com/articles/indian_music/instruments.html for indian instruments
 
  +
There's also a "modify existing instrument" component, which should be self-explanatory.
   
  +
=== A little bit about labels ===
finally there is irom for images (but someone japanese could possibly get info from pages)
 
  +
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 ==
* https://saisaibatake.ame-zaiku.com/gakki/a-musical_instruments.html
 
* https://digitalstamp.suppa.jp/musical_instruments_a/index.html
 
* https://graphic.nobody.jp/
 
   
  +
If the ticket is not obviously un-actionable, it will now be the time to research it. This is my general process for that:
(more on image abstraction later)
 
   
  +
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.
Then I have some offline sources I loom in:
 
   
  +
Additionally, I have a set of resources I almost always check.
* The excellent The New Grove Encyclopedia of Musical Instruments I-III 1984 edition
 
* The History of Musical Instruments by Curt Sachs (only borrowed from library)
 
* Percussion Instruments and their History by James Blades (for percussion instruments, only borrowed from library, it is an excellent book I wish I owned)
 
* Taonga pūoro: Singing Treasures (The musical instruments of the Māori) by Brian Flintoff (for the Māori instruments I extensively borrowed from the library this book several times (its music CD has already been added to mb ;)) another book I wish I owned)
 
   
  +
For string instruments especially (which at least as of 2022 are the most common group of instruments requested as INST tickets):
else I borrow from the library any topic books if they have them, I also go through https://www-jstor-org.wikipedialibrary.idm.oclc.org/action/doBasicSearch?Query=SEARCH ([off] and https://libgen.is/) searching for any article or book of the topic for what I'm adding
 
   
  +
* http://www.atlasofpluckedinstruments.com/
(example: while trying to piece together how ancient Indian string instruments connect together I searched extensively for these "[[User:CatCat/v*na|Veena]]" instruments in all these sources.)
 
  +
* http://stringedinstrumentdatabase.aornis.com/t.htm
   
  +
Wikipedia, of course, even if not linked from the article.
   
  +
Oxford Music Online (http://oxfordmusiconline.com/) which while is usually a paid resource, I have full access thanks to the [[https://en.wikipedia.org/wiki/Wikipedia:The_Wikipedia_Library Wikipedia Library]] (https://wikipedialibrary.wmflabs.org/). (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.)
How to determine if a ticket is not actionable?
 
   
  +
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.
it can be not actionable because:
 
   
  +
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.
* it has insufficient information, calls for more information has not yielded any result in a fair amount of time and search in prior explained ways have left nothing -> close as incomplete
 
* duplicate or erroneous type - > as already explained.
 
* finally may be a valid instrument or issue, but can not be done because something blocks it, such as implementation detail (eg https://tickets.metabrainz.org/browse/MBS-9642 or https://tickets.metabrainz.org/browse/INST-658) in this case it's status should be set as "blocked" with an explanatory comment.
 
   
  +
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.
Which leave the difficult "when is an instrument not useful for musicbrainz"
 
   
  +
* https://saisaibatake.ame-zaiku.com/gakki/a-musical_instruments.html
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
 
  +
* https://digitalstamp.suppa.jp/musical_instruments_a/index.html
(which was the secondary reason we worked it out - have a document that describes the rationale for inclusion/non-inclusion)
 
  +
* https://graphic.nobody.jp/
   
So after reading it what is the summary?
 
   
  +
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):
Basically it comes down to judgement! all examples have counter arguments, it's never actually that clear, because artists, sigh.
 
   
  +
* The excellent "The New Grove Encyclopedia of Musical Instruments I-III", 1984 edition
So what I do is I ask for other people's point of view, chiefly reosarevok (Nicolas Tamargo), sometimes Freso (Frederik Olesen) or yvanzo (I don't actually know your name :O) for things that they might know specific about, Bodhráns/Koras etc.
 
  +
* "The History of Musical Instruments" by Curt Sachs (only borrowed from library)
I will also reach out to the community with specific opinions and calls for help from anyone who could know/languag ot translate etc. (example sothotalker or shepard for translating german, d4rkie for translating japanese, zas, yvanzo, loujine etc for french, etcetra.) some years ago we had gci'ers coming in from countries that spoke languages we did not have many of in our community, they where a great help and I hope we can attract more people with more languages to help with translations.
 
  +
* "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 [[https://musicbrainz.org/release/a9cf5c54-7bd0-4fc5-af24-0651251835ba 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 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 "[[User:CatCat/v*na|Veena]]" instruments in all these sources.
   
  +
== How to determine if a ticket is not actionable? ==
However be advised: the community can be fickle, ask them for suggestions on alias translations and they'll just get occupied with with the usage of transliteration in sortnames :|
 
   
  +
A ticket can be not actionable because:
You can *not* direct peoples attention or incentives anywhere, you can only suggestively nudge, if they do not want to help, but instead want to argue about something else, it is little use to try to redirect them.
 
   
  +
* 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".
Remember that anything can always be edited.
 
  +
* 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 [https://tickets.metabrainz.org/browse/MBS-9642 MBS-9642] blocking [https://tickets.metabrainz.org/browse/INST-658 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 all instruments that are "signature moves" to borrow a Pokémon-term of a specific artist are susspect of novelty
 
   
  +
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!
What to do when two (or more) sources contradict eachother
 
   
  +
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.
if there is ''one'' source contradicting the others:
 
* unless very reputable, ignore it.
 
* if reputable and the others may infact be sourced to one or a few not so reputable source(s), go with the contracting source (but be discerning)
 
   
  +
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!)
if two (or several where it is conceivable that the others source either of the two) reputable sources contradict eachother especially:
 
* try to find a synthesis of the two (if one says 4 strings an the other says 6 write "4-6 strings")
 
* try finding a third reputable independent source and see what it says. it might clarify why the two seem to disagree (sometimes things in these are a bit like the telephone game, in different places bits are given different weight and then when the whole story gets repeated with omissions and finally in a few iterations results seemingly contradict eachother)
 
* if it is an open known that there are several leading ideas that contradict eachother, try to include both.
 
   
  +
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.
* if ALL sources disagree with a point, omit it entirely, in this case it is speculation on the part of the writers because it is actually not known.
 
   
  +
== What to do when two (or more) sources contradict each other ==
* if a western and native source disagree, go with the native source.
 
* check (get machine or help with translation) what other language wikipedia say, and see their sources. it might be a translation error.
 
   
  +
If there is ''one'' source contradicting several others:
In the end if it is still unclear, simply write "it is include if" since this is literally true.
 
  +
* 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.
What makes a source reputable?
 
   
  +
* if a Western and a native source disagree, go with the native source.
* in general academic, sourced, researched stuff is good for (western) musical instruments
 
  +
* 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.
* hobbyist blogs that are written by people with a passion for whatever - often this will be your best bet with native and non-western instruments (if only reading in english, in the native languages, there are sure academic, sourced, researched stuff as well.)
 
* reputable data can come from surprising places, like a reddit thread or blog, never assume that hobbyists don't know what they're talking bout, if possible engage with them and ask more. Naturally be discerning in any case
 
   
  +
In the end, if it is still unclear, simply write "it is unclear if", since this is literally true.
unreputable!
 
* sites that *sell* instruments - (unless data also collaborates other better sources)
 
* things like wikiwand or fandom or random crap, disregard these as main sources and only look if they collaborate a better reputable source.
 
* be on the lookout for badly written text, it *might* just be badly translated/nonenglish person writing, but usually it also means the data is less reputable.
 
   
  +
== 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
+
== 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
+
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.
(for simplicity the url is https://musicbrainz.org/instrument/create anyway)
 
   
[[File:add_instrument.png]]
+
[[File:add_instrument.png]]<br>
(the add instrument screen)
+
The "Add instrument" screen
   
After all is researched and data is found one makes the instrument. a Disambiguation and a Description.
 
* The Name should always be lovercase, unless an actual proper noun is in it, (eg "Saraswati veena"). Do not include anything ''but'' the name (e.g. like "Swedish lute", unless that ''is'' the name)
 
* The Disambiguation should be as short and sweet as possible, it should have the main idea up. so you include where or whence it is from, what it is made of and the summary of what makes it distinct. So if the neck is short write "short-necked" if it is goblet shaped write "goblet-drum" etc. combine like "Namibian short-necked lute" or "Ancient cedarwood goblet-drum" or "Double-barrelled brass used in western orchestra" etc.
 
* Type is one of "Percussion" (membranophones, in here also idiophones), "Wind" (aerophones), "String" (chordophones), "Electronic" (electrophones), as well as "Family" "Ensemble" and "Other"
 
** piano is a string-instrument, shut up.
 
* Description! here the essence of your research should go. try to use as few helper conjugations as possible, don't include the name of the instrument, be concise and get to the point as fast as possible; ex: "Used in traditional dance and religious ceremony, it's 40 cm long heavily decorated bamboo soundbox has 3-4 metal strings plucked by bone plectrum."
 
   
  +
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.
In Relationships you connect other entities in MusicBrainz
 
  +
* 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 where it is from. you can also use rel-credits for historical placenames and instruments
 
  +
* Artist<ref>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.</ref> & 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?)
 
  +
* 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:
 
* Instrument:
** ''children'' an obsolete type, change this to something else away from this!
+
** '''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'''(cardinality) if this instrument is part of an Ensemble or a Family see https://beta.musicbrainz.org/relationship/5ee4568f-d8bd-321d-9426-0ff6819ae6b5
+
** '''[https://musicbrainz.org/relationship/5ee4568f-d8bd-321d-9426-0ff6819ae6b5 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''' (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
+
** '''[https://musicbrainz.org/relationship/deaf1d50-e624-3069-91bd-88e51cafd605 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''' (both ways) I tend to use this less these days in deference to derived. <ref>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"</ref>
+
** '''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).
*** '''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
+
** '''[https://musicbrainz.org/relationship/2f522cbc-46f9-409b-9957-d0308d0899ef 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''' (cardinality) This is the most used rel, it is for the instrument-tree in general, A cello is a bowed string instrument,
+
** '''[https://musicbrainz.org/relationship/40b2bd3f-1457-3ceb-810d-57f87f0f74f0 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).
a bit about Families and Ensembles
 
   
  +
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.).
** '''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".
 
   
  +
=== A little bit about families and ensembles ===
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.
 
   
  +
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".
else see https://beta.musicbrainz.org/relationship/5ee4568f-d8bd-321d-9426-0ff6819ae6b5
 
   
  +
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 [[instrument:708c6d50-c768-4f93-a5c7-b41fb3cf029f|string quartet]] consists of 2 violins, 1 viola and 1 cello. "Optional" can be used to indicate that e.g. a [[instrument:d2385a89-bb39-4316-b562-27b2c19ff531|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.
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.
+
More attributes can be requested if needed.
   
* 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 :|)
 
   
  +
Press "Enter edit!" and we're done! Yay!
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:
+
Well, actually not ''quite'', because there is still:
   
a bit about aliases
+
== 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".
(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 )
 
   
  +
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").
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"
 
   
  +
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. <!-- it's worth noting also, that currently sort names of aliases do ''nothing!'' the list of aliases will sort on language code no matter what. (this should be fixed) -->
Then I will add any extra names/spellings from Grove or Oxford dictionary (or any other source) as an alias too.
 
   
  +
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 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
 
   
  +
For actually adding the aliases I use [https://github.com/loujine/musicbrainz-scripts/blob/master/mb-edit-add_aliases.user.js 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.
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 little bit about image (IROM) extraction ==
a better way of handling this would be to create a transliteration/script way for aliases
 
   
  +
Since we [[https://blog.metabrainz.org/2019/06/25/we-were-sued-by-a-copyright-troll-and-we-prevailed/|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 in the repository [https://github.com/metabrainz/irombook-instrument-images irombook-instrument-images].
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.
 
   
  +
IROM has a set of websites with often somewhat different information (and sometimes different images):
   
  +
* https://saisaibatake.ame-zaiku.com/gakki/index.html
  +
* 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 these are better than nothing if you can't find anything else)
   
  +
In addition there are blogs like:
 
a bit about image (IROM) extraction
 
 
irom has many sites
 
 
* https://saisaibatake.ame-zaiku.com/gakki/index.html
 
* 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://gakki5.blogspot.com/ (see the links also)
 
* https://animal.tyabo.com/musical_instruments/2string_instruments.html
 
* https://animal.tyabo.com/musical_instruments/2string_instruments.html
* 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
+
* 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
* etc etc etc
 
   
Usually saisaibatanka 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.
+
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.
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.
+
Additionally, there's also [https://digitalstamp.suppa.jp/musical_instruments-chordophone/bowed_strings.html a list of string instrument images without people playing them], and [https://animal.tyabo.com/musical_instruments/1string_instruments.html another, older one].
   
  +
I strongly recommend installing [https://github.com/Arnie97/katakana-terminator 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 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)
 
   
  +
I also take the icon in front of the instrument name as seen in the sidebar and the [https://saisaibatake.ame-zaiku.com/gakki/r-musical_instruments.html 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 [https://github.com/metabrainz/irombook-instrument-images 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
In general go with the largest, clearest and cleanest image, the saisaibatanke 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
 
   
 
example
 
example
* [https://staticbrainz.org/irombook/cello/cello.png cello/cello.png] (main)
+
* [https://staticbrainz.org/irombook/cello/cello.png https:​//staticbrainz.org/irombook/cello/cello.png] (main image, shares the folder name)
* [https://staticbrainz.org/irombook/hardingfele/hardingfele_alt.png hardingfele/hardingfele_alt.png] (alternate)
+
* [https://staticbrainz.org/irombook/hardingfele/hardingfele_alt.png https:​//staticbrainz.org/irombook/hardingfele/hardingfele_alt.png] (alternate image, with ''_alt'')
* [https://staticbrainz.org/irombook/keytar/keytar_player.png keytar/keytar_player.png] (player)
+
* [https://staticbrainz.org/irombook/keytar/keytar_player.png https:​//staticbrainz.org/irombook/keytar/keytar_player.png] (player image, with ''_player'')
* [https://staticbrainz.org/irombook/xylophone/icon.png xylophone/icon.png] (icon)
+
* [https://staticbrainz.org/irombook/xylophone/icon.png https:​//staticbrainz.org/irombook/xylophone/icon.png] (icon, just named ''icon'')
* [https://staticbrainz.org/irombook/ngoni/ngoni_donso.png ngoni/ngoni_donso.png] (a sub type)
+
* [https://staticbrainz.org/irombook/ngoni/ngoni_donso.png https:​​//staticbrainz.org/irombook/ngoni/ngoni_donso.png] (a subtype stored in the same folder)
* [https://staticbrainz.org/irombook/cabasa/caba%C3%A7a.png cabasa/cabaça.png] (an alternative, but related instrument)
+
* [https://staticbrainz.org/irombook/cabasa/cabaça.png https:​//staticbrainz.org/irombook/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, 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.
 
 
   
  +
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.
reosarevok knows the drill.
 
   
  +
== 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?
how to deal with community friction
 
   
  +
* 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).
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?
 
  +
* 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 ==
* 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'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!
   
  +
------------------
in closing
 
   
  +
To paraphrase the LEGO Movie: Instruments are awesome *and* instruments are cool when you're part of a team! Enjoy your time with them!
I haven't written this part yet, oops!
 

Latest revision as of 16:44, 21 February 2022

⥽ An Informative Introduction to Instrument Inserting ⥼

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

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 https://musicbrainz.org/instruments - 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 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), 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 (http://oxfordmusiconline.com/) which while is usually a paid resource, I have full access thanks to the [Wikipedia Library] (https://wikipedialibrary.wmflabs.org/). (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, 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, (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 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 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 https://musicbrainz.org/instrument/create 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 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

example

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!