music21 Documentation¶
About music21¶
Authors, Acknowledgments, Contributing, and Licensing¶
Music21 is an open-source toolkit for Computer-aided musicology. It is licensed under the LGPL or BSD license (see below).
About the Authors¶
Michael Cuthbert, the creator of music21, is Associate Professor of Music at M.I.T. He received his A.B. summa cum laude, A.M. and Ph.D. degrees from Harvard University. Cuthbert spent 2004-05 at the American Academy as a Rome Prize winner in Medieval Studies, 2009-10 as Fellow at Harvard’s Villa I Tatti Center for Italian Renaissance Studies in Florence, and 2012-13 at the Radcliffe Institute.
Prior to joining the M.I.T. faculty, Cuthbert was on the faculties of Smith and Mount Holyoke Colleges. He has worked extensively on computer-aided musical analysis, fourteenth-century music, and the music of the past forty years. He has published on computer-aided treatment of fragments and palimpsests of the late Middle Ages and on set analysis of Sub-Saharan African Rhythm and the music of John Zorn. In addition to work on music21, Cuthbert is currently writing a book on sacred music in Italy during the age of the Black Death and Great Papal Schism.
Christopher Ariza is Emeritus Lead Programmer of music21 and was Visiting Assistant Professor of Music at M.I.T. from 2010 to 2013. Prior to joining the music21 project, Ariza was Assistant Professor of Music Technology at Towson University in Baltimore. He has published and presented numerous articles and papers on algorithmic composition and generative music systems. Ariza received his A.B. degree from Harvard University and his M.A. and Ph.D. degrees from New York University.
Benjamin Hogue is Former Lead Programmer of music21.
Josiah Wolf Oberholtzer is Former Lead Programmer of music21.
Additional contributions by many MIT students and visitors and the Open Source software community.
Acknowledgements¶
Funding¶
The music21 project was made possible by generous research funding from the Seaver Institute and the National Endowment for the Humanities/Digging into Data research fund.
In addition, we acknowledge consistent support from M.I.T., the School of Humanities Arts and Social Sciences, and the Music and Theater Arts section.
Colleagues and Institutions¶
Music21 is unthinkable without our colleagues and friends working on other music and technology projects, in particular:
- David Huron, inventor of Humdrum, the inspiration for music21.
- The Center for Computer-Assisted Research in the Humanities at Stanford University, contributing to the knowledge of music since 1984, and publishers of Computing in Musicology.
Contributors¶
Additionally, the following individuals have contributed materials or knowledge to this project. Their contributions and generosity are greatly appreciated.
- Thomas Bonte, Nicholas Froment, and Werner Schweer of MuseScore for their
- support and for their contributions to the open source music notation projects, including the Bach Goldberg Variations and the Handel Arias included.
- Donald Byrd, researcher on University of Indiana who created
- a schema for computer-aided musicology (along with the source of all sorts of examples of how music notation is difficult).
- Jack Campin has kindly given permission to distribute his ABC editions of the Aird Collection, the Northumbrian Minstrelsy, and the Colonial and Civil War American Fife Music Collection.
- John Chambers has provided ABC editions to distribute with music21, including the Aird Collection, the O’Neill’s Music of Ireland Collection, and Ryan’s Mammoth Collection of fiddle tunes.
- Laura E. Conrad has kindly given permission to distribute her ABC editions of renaissance polyphony from Serpent Publications.
- Ewa Dahlig-Turek has kindly given permission to distribute the
- Essen folksong database with music21.
- Michael Good and Recordare.com for creating MusicXML and many
- discussions about the project.
- Margaret Greentree kindly gave permission for distribution of her edited
- collection of the Bach chorales in MusicXML format as part of the music21 corpus. Her website contains all these chorales in additional formats. Any discoveries we make regarding these chorales are done in her memory.
- Bret Aarden for kindly contributing his conversions of Palestrina Mass corpus to music21.
- Walter B. Hewlett and Craig Sapp of Stanford’s CCARH for support.
- Justin London compiled and maintained the list of Second-Viennese
- row forms now available in serial.py.
- McGill University ELVIS project for including the MEI parser. Special thanks to Julie
- Cumming, Andrew Hankinson, and especially Christopher Antila for contributing.
- Manuel Op de Coul has kindly gave permission to use the Scala
- scale archive of nearly 4000 scales in music21.
- Seymour Shlien has kindly given permission to distribute his ABC
- encodings of the Essen folksong database with music21.
- Bryen Travis has kindly gave permission to use his collection of
- Bach MIDI data in music21.
- Project Gutenberg houses public domain music, including the quartets of Beethoven, Haydn, and Mozart, in musicxml format which we have been able to include in music21.
How to Contribute¶
We are always interested in working with interested musicologists, programmers, psychologists, composers, game-designers, performers, amateur music enthusiasts, etc. In particular, we’re interested in hearing about how music21 helped you advance your work … or in problems with music21 itself or contributions you’ve made.
You can contact the larger music21 community through the music21 list.
In particular, if you are interested in contributing documentation, tests, or new features to music21, please contact the lead author on GitHub or through the list.
Licensing and Copyright¶
The music21 Toolkit¶
Music21 is Copyright (c) 2006-2017, Michael Scott Cuthbert and cuthbertLab. Music21 code (excluding content encoded in the corpus) is free and open-source software, licensed under the Lesser GNU Public License (LGPL) or the BSD License.
The music21 Corpus¶
The LGPL/BSD music21 software is distributed with a corpus of encoded compositions which are distributed with the permission of the encoders (and, where needed, the composers or arrangers) and where permitted under United States copyright law. Some encodings included in the corpus may not be used for commercial uses or have other restrictions: please see the licenses embedded in individual compositions or directories for more details.
To the best of our knowledge, the music (if not the encodings) in the corpus are either out of copyright in the United States and/or are licensed for non-commercial use. These works, along with any works linked to in the virtual corpus, may or may not be free in your jurisdiction. If you believe this message to be in error regarding one or more works please contact Michael Cuthbert at the address provided on the contact page.
Applications and Extensions of music21¶
Music21 has been used in numerous research tasks already, and will continue to offer researchers many tools with which to explore new domains.
Papers, Presentations, and Publications¶
The following papers and publications make extensive use of music21. Start here:
Cuthbert, Michael Scott Cuthbert and Christopher Ariza. 2010. “music21: A Toolkit for Computer-Aided Musicology and Symbolic Music Data.” In Proceedings of the International Society for Music Information Retrieval. https://www.academia.edu/243058/music21_A_Toolkit_for_Computer-Aided_Musicology_and_Symbolic_Music_Data
Then continue with:
Church, Maura and Michael Scott Cuthbert. 2014. “Improving Rhythmic Transcriptions via Probability Models Applied Post-OMR.” In Proceedings of the International Society for Music Information Retrieval. https://www.academia.edu/7709124/Improving_Rhythmic_Transcriptions_via_Probability_Models_Applied_Post-OMR
Cuthbert, Michael Scott, Beth Hadley, Lars Johnson, and Christopher Reyes. 2012. “Interoperable Digital Musicology Research via music21 Web Applications.” From Joint CLARIN-D/DARIAH Workshop at Digital Humanities Conference Hamburg. https://www.academia.edu/1787946/Interoperable_Digital_Musicology_Research_via_music21_Web_Applications
Cuthbert, Michael Scott, Chris Ariza, Jose Cabal-Ugaz, Beth Hadley, and Neena Parikh. 2011. “Hidden Beyond MIDI’s Reach:Feature Extraction and Machine Learning with Rich Symbolic Formats in music21” In Proceedings of the Neural Information Processing Systems Conference. https://www.academia.edu/1256513/Hidden_Beyond_MIDI_s_Reach_Feature_Extraction_and_Machine_Learning_with_Rich_Symbolic_Formats_in_music21
Cuthbert, Michael Scott, Chris Ariza, and Lisa D. Friedland. 2011. “Feature Extraction and Machine Learning on Symbolic Music using the music21 Toolkit” In Proceedings of the International Symposium on Music Information Retrieval https://www.academia.edu/1256514/Feature_Extraction_and_Machine_Learning_on_Symbolic_Music_using_the_music21_Toolkit
Jordi Barthomé Guillen and Michael Scott Cuthbert. 2011. “Score Following from Inaccurate Score and Audio Data using OMR and music21.” In Proceedings of the Neural Information Processing Systems Conference (Music and Machine Learning, Workshop 4. https://www.academia.edu/1256512/Score_Following_from_Inaccurate_Score_and_Audio_Data_using_OMR_and_music21
Ariza, C. and Michael Scott Cuthbert. 2011. “The music21 Stream: A New Object Model for Representing, Filtering, and Transforming Symbolic Musical Structures.” In Proceedings of the International Computer Music Conference. San Francisco: International Computer Music Association, pp. 61-68. Available online at http://www.flexatone.org/static/docs/music21Stream.pdf
Ariza, C. and Michael Scott Cuthbert. 2011. “Analytical and Compositional Applications of a Network-Based Scale Model in music21.” In Proceedings of the International Computer Music Conference. San Francisco: International Computer Music Association, pp. 701-708. Available online at http://www.flexatone.org/static/docs/scaleNetwork.pdf
Ariza, C. and Michael Scott Cuthbert. 2010. “Modeling Beats, Accents, Beams, and Time Signatures Hierarchically with music21 Meter Objects.” In Proceedings of the International Computer Music Conference. San Francisco: International Computer Music Association. 216-223. Available online at http://mit.edu/music21/papers/2010MeterObjects.pdf
Future Goals and Potential Applications¶
There are numerous applications for music21 that we anticipate, yet simply have not had time to implement. Consider taking on one of these projects, or write us with new and interesting suggestions. To contact the authors, visit Authors, Acknowledgments, Contributing, and Licensing.
- Piano-key-visualization
- Slonimsky scale types
- Automatic clarinet fingering generation via ClarFinger font (link: www.trecento.com/fonts/)
- Automatic string fingerings.
- Indian Raga encoding: including ascending, descending, and typical presentations, microtonal inflections, common associations, historical context.
- Multiple-simultaneous-tempi to a single tempo conversion (via tuplets).
- Palestrina counterpoint generation (via algorithms of Mary Farbood and others.).
- Beneventan chant similarity indices (thanks to the work of Thomas Forrest Kelly and the Exultet encodings made available in **kern by Elsa De Luca).
- Identify potential clefs for fragmentary Renaissance and Medieval pieces that are missing their clefs. (Use their staff-lines and minimizing number of melodic and harmonic tritones).
Frequently Asked Questions¶
General¶
How do I ask a question so that it becomes frequently asked?
Don’t you hate FAQs that are not based on anything anyone’s ever asked? To ask, post to http://groups.google.com/group/music21list. But first read what we’ve already come up with below.
Why is it called music21?
music21 gets its name from the fact that it was (mainly) created at MIT in the Music and Theater Arts Section there. At MIT, everything has a number, and the department number for music is 21M. There’s no connection to “Twenty-first century” etc. and therefore superior to older software. In fact, if I had thought of that mental connection I probably would have come up with a different name.
There was a tradition early on of naming software that dealt with music, with “MUSIC” followed by a number (https://en.wikipedia.org/wiki/MUSIC-N). There is famously Max Matthews’ MUSIC II, III, and IV (the sequels to just plain “MUSIC”), MUSIC V (Matthews and Miller), MUSIC 360 and MUSIC 11 (Vercoe et al., which became CSound). These systems were originally created to synthesize sound digitally though their successor systems can do quite a number of different things.
I figured that since no one had actually released a piece of software in over 35 years that actually followed the “Music N” naming structure, it was fair game to think of it not as the paradigmatic name for a software synthesis package, but for any new or original usage of software and music.
I’m pretty tickled that the new naming convention is getting an hommage in Anas Ghrab’s music22 package: https://pypi.python.org/pypi/music22
What is the native music21 data format?
Quick answer: There is none, but it doesn’t matter.
Longer answer: music21 is a toolkit for the manipulation and analysis of data that you already have or are generating on the fly. As such, its strength is its (and python’s) ability to work with many common formats and easy extensibility to work with many more. You will find that for the most part you will not need to preserve your music21 data in an interchangeable format. And the number of things you can do with music21 makes it impossible for us to create formats for every possible use. We work with music21 all the time for our work and have never needed one.
But if you must store your music21 data somehow, here are some suggestions:
- For data that can quickly and exactly be recreated, use the script that generates as your data storage. Then just rerun the script to get your data back.
- For storing music notation, musicXML output will work well for many purposes. If you just want to store an audio file or graphic of your output, MIDI or Lilypond->PNG could work.
- For data that cannot easily be recreated (because it’s computationally expensive to create, or relies on user input, or is stochastically generated), Python’s pickle package will allow you to store your data on disk. These files cannot necessarily be read in by a later version of music21 (This is the reverse of the problem Finale has, where you can only read older versions of files), so it should not be used for long term storage and sharing. Run
setupSerializationScaffold()andteardownSerializationScaffold()before running pickle.dump(yourStream) and after running pickle.load(yourStream) respectively and almost everything will be preserved.- For data that cannot easily be recreated but needs long-term storage and sharing, try saving the relevant parts of the data in an XML, json, or even CSV(!) format. See plistlib http://docs.python.org/dev/library/plistlib.html or http://code.activestate.com/recipes/440595. You cannot store every element of python’s object structure, but you should easily be able to store the parts that are difficult to recreate. Music21 has some facility for a JSON storage of Streams, but it is not complete.
- If you’re programming data structures too complex to be encapsulated in one of the solutions above, you should have enough experience to create a data storage format of your own. Please consider contributing your solution to improve the package.
Can I synthesize new sounds with music21?
Yes, and no. Music21 is primarily built for manipulating symbolic musical data not sound waves. There are lots of great programs for doing that. But the symbolic data, however, be used as data within a large variety of synthesis packages. So you could create new music21 objects that control the synthesis package of your choosing.
Can music21 read in music directly from an image or a .pdf?
Sorry, that’s beyond music21’s capabilities. This technology is called OMR (Optical Music Recognition) and it’s a whole separate field of research in itself. Audiveris is an open-source OMR software toolkit. The development team here has had good experience with the commercial SmartScore application. Music21 does have a good set of modules for improving the output of OMR after it’s done. See moduleOmrCorrectors.
I’m ready to give it a try, but how do I install music21?
Please see the complete install instructions: User’s Guide, Chapter 1: Installing music21.
I’m using Linux/GNU/Unix and I’m having trouble configuring music21, can you help?
Unfortunately, due to the number of different flavors of open-source operating systems, the development team can only give free help to Mac and Windows installation. (but see paid support, below).
Music21 doesn’t have some feature that I need, how do I get it added?
It won’t hurt to email the list (or us directly) and we’ll consider it. However, we do have a priority list based on what we think the widest audience will require or what we need for our own research. If you’d like your request to leap-frog to the front of the line, the best way is to endow the programming of your feature through a donation that will enable us to increase the number of student programming assistants we employ. (Or side-step us and offer a cash bounty on the music21list itself).
Consulting¶
No, you don’t understand, I really need this feature!
If you really need something done in music21, we offer paid support by the hour at standard consulting rates. Contact cuthbert@mit.edu for details and rates.
Is this also what I should do if I need help using music21 for my own project?
Yes, if you’re having trouble getting music21 to do what you want and you’ve tried the mailing list/StackOverflow, etc. consulting is available to help.
Why not put the rate here?
The rate varies according to the difficulty of the feature–whether it requires a principal investigator to run or whether it could be incorporated into the education of a student; whether licensing agreements need to be signed, etc.
Discounts are available for academic researchers/composers who consider the consultation sufficiently essential as to add authorship credit to the development team on a publication.
3rd-Party Utilities¶
What is MusicXML?
MusicXML is a file format for exchanging musical scores among different programs, such as, oh… music21 and Finale (or music21 and Sibelius, or Dorico, or MuseScore). It was created by Recordare (Michael Good, CEO) and now run by the W3C. More information about the project can be found at:
And this Humdrum about which you speak?
It’s another framework for studying music as symbolic data using simple text files and UNIX scripting tools. Created by David Huron in the 80s and 90s. We’re big fans of Humdrum here at music21, but we thought that it was time to take a different approach.
Information on Humdrum can be found here at the following links:
Installation¶
Installing music21 on Mac¶
Because Apple changes their system details so much from one version of OS X to another, installing music21 is probably the hardest part of the experience. Once you have that set, the rest should be much less painful. Trust us that it should work.
Downloading Python 3 from python.org¶
Though Macs come with Python, it’s a very old version. We recommend updating that by going to http://www.python.org/ and getting Python 3.6 or later.
(The music21 team strongly recommends using the version of Python 3 from the python.org website and not the Conda version (or Enthought Canopy) because it is fully compatiable with matplotlib. If you have no plans on plotting functions, feel free to use any flavor of Python 3.)
Simple install on macOS Sierra or OS X El Capitan¶
If you’re on the newest versions of OS X, Sierra or El Capitan, then installation is very easy. Open up “Terminal” in “Applications -> Utilities”, then type at the prompt:
sudo pip3 install music21
it will prompt you for your password. TADA: you have music21 for Python!
To upgrade later, just do
sudo pip3 install –upgrade music21
(If you didn’t install Python 3.6, then replace “pip3” with “pip”
Starting Python and Checking the Version¶
Python is a simple but powerful programming language that music21 is written in and in which you will write your own programs that use music21.
To determine the Python version you have installed, open a terminal (by going to Applications, then Utilities, and then double clicking “Terminal”) and enter the following command-line argument:
python3 -V
it should display in Terminal something like the following:
If it says 3.4 or higher (or possibly a number like 3.4.2), you’re okay. If it says 2.4 or 2.5 or 2.6, go to http://www.python.org/download and download a newer version. Multiple versions of Python can exist on a single computer without any problems.
Try typing:
2+2
You should see 4. This means Python is working. Now see if music21 is working by typing:
import music21
Hopefully this should work fine.
Exit python by typing quit().
Starting the Configuration Assistant¶
Double click on the installer.command file to start. This file should open a Terminal window and begin running the Configuration Assistant. As this is a program downloaded from the Internet, the System will likely warn you about running it. Go ahead and click “Open”.
After waiting a few moments to load modules, the Configuration Assistant begins.
The first option is to install music21 in its standard location (see below, The Installation Destination). Enter “y” or “yes”, or press return to accept the default of “yes”.
Before installation begins you may be asked for your Mac password. (The cursor won’t move or display any letters when you type in the password. Just rest assured that the characters are being transmitted). As Python packages are stored in a System directory, you need to give permission to write files to that location.
(If you don’t get a prompt but instead start getting a lot of errors, you probably do not have an administrator account on your Mac. To make yourself one, quit the installation program (just close the window), open System Preferences from the Apple menu in the upper left corner of your screen, click on Users and Groups (4th Row). Click on the lock on the lower-left corner – you’ll need your Mac password. Then click “Allow user to administer this computer”. Then close System Preferences and click the music21 installer.command button again and go back one step.)
During installation, a large amount of text will display showing files being copied. Sorry about the mess. Just ignore it! It means it’s working.
After installation the Configuration Assistant will try to configure your setup. If you have never used music21 before, following these prompts is recommended.
Selecting a MusicXML reader is the first step. MusicXML is one of many display formats used by music21, and will provide an easy way for you to visualize, print, and transfer the music you edit or develop in music21.
The Configuration Assistant will attempt to find a MusicXML reader on your system. If it can’t find any, you will be asked to open a URL to download Finale Notepad 2012, a simple and free MusicXML reader and easy writer. Installing this reader is recommended for users who do not have Finale, Sibelius, MuseScore, or another MusicXML reader. You might want to try MuseScore instead, which is also free and doesn’t require you to register to download it.
If one or more MusicXML readers are found, skip ahead to the next instructions.
If you choose to install Finale Notepad (formerly Finale Reader; hence the pictures below), you will download an installer. Launch the installer immediately, and follow the instructions.
After installing a MusicXML reader, or if you already have one or more installed, the Configuration Assistant will present you with a list of MusicXML readers from which to select one to use with music21 by default. This means that music21 will attempt to open MusicXML files with this application. This setting can be easily changed later. Enter the number of the selection as presented in the list:
After selecting a MusicXML reader, you will be asked a number of questions about working with music21. They concern whether music21 can access the Internet, and whether you are willing to comply with the license for use of music21 and the included corpus of scores. You have to accept the license to continue (we need to retain some rights you know!), but you don’t have to give us access to the Internet.
After the Configuration Assistant is complete, you can close the window when it says “[process terminated]”.
After Installation¶
CONGRATS! You’re done with installing. You can delete the music21-4.0.0.tar.gz file and music21-4.0.0 folder from your desktop now.
Open up the Mac Terminal (under Applications/Utilities/Terminal). You might want to drag it to the dock. You’ll use it often.
After a successful installation, you may proceed to Notes to begin using music21.
Installation Help¶
If you have followed all the instructions and still encounter problems, start over from scratch and try it again very carefully. If you still have problems contact the music21 group and someone should be able to help:
Installing music21 in Windows¶
Get Python¶
Python is a simple but powerful programming language that music21 is written in and in which you will write your own programs that use music21.
Windows users should download and install Python version 3.6. Python 2.7 is still supported for music21 v. 4, but if you’re learning Python for the first time, definitely go for Python 3.X. Version 5 of music21 will no longer support Python 2.
To get Python 3.6 for Windows, go to http://www.python.org/download/ and click on the “Windows installer” link. It is probably the first link. Save the file to your desktop and then click on it there.
To test to see if Python has been installed properly, go to the start menu and run (either by clicking “Run” in older Windows or by typing in the search box) a program called IDLE. Once it’s started, type 2+2. If your system then displays 4 python is working properly and we can start thinking about installing music21.
Updating Python¶
If you have already installed Python on your computer, launch IDLE (a Python interpreter and code editor) by clicking the start menu and clicking Run (on Windows XP or older) and typing in “IDLE” or (on Windows Vista and newer) typing in “IDLE” in the Search Programs list.
The first lines of text displayed will include a version number. Make sure it begins with 3.4 or higher.
If your version is too old, download a newer version as above.
Install music21¶
Open up a command prompt and type:
pip install music21
This will download and install music21. If you already have music21 but want to upgrade to the latest version, run:
pip install –upgrade music21
To test to see if music21 has been installed properly, go to the start menu and run (either by clicking “Run” in older Windows or by typing in the search box) IDLE. Type “import music21”. If your system waits for a few seconds and then displays “>>>” and perhaps a warning about missing packages, then you’ve installed everything properly. (If the system cannot find music21 then you may have more than one version of Python on your system. Try uninstalling all of them along with music21 and then restarting from scratch).
You should then configure music21 to find your helper programs such as MuseScore or Finale. In IDLE type:
import music21 music21.configure.run()
or in the command prompt, type:
python3 -m music21.configure
After Installation¶
After a successful installation, you may proceed to Notes to begin using music21.
Installation Help¶
If you have followed all the instructions and still encounter problems, start over from scratch and try it again very carefully. If you still have problems contact the music21 group and someone should be able to help:
Installing music21 on GNU/Linux¶
GNU/Linux, FreeBSD, etc. are supported by music21. However, by choosing to use Unix-like systems you should be an advanced user – the music21list should not be used for general installation/configuration problems that are specific to your operating system. Because of the number of different Unix variants, the list maintainers can only help with music21-specific problems post installation or Mac/PC problems.
To reiterate: GNU/Linux is not a system for which support questions will be answered
Check Your Version of Python¶
Music21 requires Python 2.7.3+ or Python 3.4+.
To determine the Python version you have installed, open a shell or terminal and enter the following command-line argument (where “$” is the prompt):
$ python -V
or in many 3.X installation cases:
$ python3 -V
it should display something like:
Python 3.6.1
if so, you’re okay. If not, go to http://www.python.org/download and download a newer version. Multiple versions of Python can exist on a single computer without any problems.
After Installation¶
After a successful installation, you may proceed to Notes to begin using music21.
Installation Help¶
If you have followed all the instructions and still encounter problems, start over from scratch and try it again very carefully. If you still have problems contact an expert in your operating system.
Extending music21 with Additional Software¶
Installing Additional Python Modules¶
Music21 can do more things, such as plotting graphs, if you install additional Python libraries.
The following topics cover additional software used by music21. For each library, visit the websites listed below, download the additional python libraries, and install them just as you did with music21 above. If you don’t feel like installing them now, no worries: you can always install them later.
It’s best not to install these until you have music21 working without the external modules.
Matplotlib¶
Graphing and visual displays in Music21 are provided by Matplotlib. Matplotlib itself has additional dependencies (such as NumPy).
On Mac if you are using the version of python 3 from python.org, run:
pip3 install matplotlib
and you should be set. If you are using a version from anaconda (conda, miniconda, etc.), you should run these lines:
conda install matplotlib conda install python.app
and then use pythonw instead of python. For more details, see http://matplotlib.org/2.0.0b4/faq/osx_framework.html
Users of 64-bit windows or Python 2.7 will need to download numpy and scipy from:
numpy¶
Numeric extensions to Python. Included with Matplotlib.
On Mac if you are using the version of python 3 from python.org, run:
pip3 install numpy
and you should be set. If using python 2, substitute pip for pip3
scipy¶
Scientific extensions to Python.
On Mac if you are using the version of python 3 from python.org, run:
pip3 install scipy
and you should be set. If using python 2, substitute pip for pip3
pyaudio¶
Allows for recording within python. We use it for the audioSearch module, and nowhere else. Not essential. Requires portaudio and, on the Mac, the XCode command-line development tools.
On the Mac, run:
xcode-select –install brew install portaudio pip3 install pyaudio
pygame¶
Allows for realtime MIDI performance. We use it in the midi.realtime module, and nowhere else Not essential.
On the Mac, run:
pip3 install pygame
Python Imaging Library (pillow or PIL)¶
The Python Imaging Library (pillow; formerly PIL) provides resources for transforming and editing graphics files. Without this library, the output from Lilypond is less good. Not essential.
On the command line type pip3 install pillow and you should get the latest version of pillow.
Installing Additional Software Components¶
Additional functionality of music21 is available with the installation of numerous helper applications. While not essential for all applications, these tools will aid in working with music21.
MuseScore¶
MuseScore offers a free, full-featured, cross-platform (Windows, Mac OS, Ubuntu, Debian, and Fedora) application for viewing and editing music notation. MuseScore can import and export MusicXML, and provides an excellent way to view, edit, and export musical data for working in music21. Downloading MuseScore (version 2 or higher) is highly recommended for working with music21.
Finale or Finale NotePad¶
Finale is one of the industry leaders in creating musical scores. It can import MusicXML that music21 generates and let you see, edit, or print these scores for your own use. There is also a free version of Finale, Finale NotePad that can load MusicXML files but cannot edit all aspects of them. NotePad is available for Windows and Mac OS computers. Use of Finale or Finale NotePad is recommended for working with music21.
http://www.finalemusic.com/products/finale-notepad/
On Windows, after you install Finale or Finale Notepad, you will probably want to associate .xml files so that they are automatically opened by Finale or Finale Reader. To do so download http://web.mit.edu/music21/blank.xml to your desktop. Right click the file in on your desktop and click “Open with” then choose “browse”, select c:\Program Files\Finale Notepad\Finale NotePad.exe (or c:\Programs\Finale\Finale.exe depending on if you’re on Windows Vista/7/8/10 or if you’re using Finale vs. Finale NotePad), and the check the box for always using this program for opening xml files. (Thanks to Craig Sapp for this missing step)
Lilypond¶
Lilypond is a free, open-source music display program that can produce beautiful scores. Music21 can generate PDF or PNG (like JPG) files automatically if Lilypond is installed on your system. Download it at:
Eclipse + PyDev + Git¶
Eclipse is a free, open-source integrated development environment (IDE), essentially a program that makes writing (and finding bugs in) other programs much easier. Eclipse is set up primarily for editing in Java, but the add-in PyDev makes it extremely powerful for creating Python scripts as well. Eclipse + PyDev + Git is the only supported method for developers to get help in contributing to music21.
Details are at Using Git
Developer Reference¶
Documenting music21¶
Music21’s documentation system uses a combination of a few handwritten documentation pages (like this one), a lot of Jupyter notebooks (mainly in the User’s Guide sections), and documentation automatically generated from the documentation found in modules (in moduleReference).
The handwritten pages and Jupyter notebooks are found in the /documentation/source/ directories. The automatically generated documentation is found in each .py module.
To build music21 documentation, go to the /documentation/ folder and run:
python3 make.py
(At present, only MIT affiliates can run the upload.py script.)
.rst format files¶
The handwritten .rst files are written using the reStructuredText format, which is a pretty simple way of defining structure of documents with things such as hyperlinks, emphasis, etc. It is somewhat similar to Markdown format. These files should not contain code examples, since they will not be tested. (You may find some older files that do contain code; we should be translating these in the future).
These files get converted to .html when you run /documentation/make.py so long as the excellent module Sphinx has been installed.
You can also edit these .rst files directly in Jupyter notebook, which will make them show the layout as well.
Jupyter Notebook (.ipynb) files¶
Since 2013, the majority of new documentation should be written in Jupyter Notebook (formerly IPython Notebook) format. These files should never be edited directly, but instead should be edited using Jupyter Notebook running Python 3.4 or higher.
A lot of the music21 documentation is automatically generated from the documentation strings found in music21 modules. We strongly encourage other module writers to create documentation that works the same way. In fact, we won’t add your module to the music21 repository without documentation in this form – there’s a test that ensures that code coverage increases with each build – but we’ll help you learn the ropes. This doc explains some of the main features (and potential Gotchas!) of our automatic documentation system.
Install Jupyter with:
pip3 install jupyter
And then run it by changing directory to the direction you want to edit and run:
jupyter notebook
When editing examples with code be sure, at least the first time, to run each code excerpt individually and pay attention to changes in output and unexpected errors.
Documenting modules and classes¶
music21 documentation for modules is found inside the module itself, at the very top and before the import statements. This module-level documentation, usually in triple-quoted strings, might look like this:
'''
I am documentation for this module!
'''
The buildDoc/build.py script creates RST files for modules, which are processed by Sphinx. Place all documentation for public modules, module-level functions, classes, and class-level attributes, properties, and methods as close to the relevant code as possible.
If you’re going to edit docs you’ll need the latest version of Sphinx. Go to the command line and Type:
pip3 install sphinx
Sphinx uses special characters to identify formatting of documentation. For example, to write a heading you can write: Helpful tips on Sphinx formatting may be found here: Sphinx Documentation Formatting
The code would look like this:
**This is bold**
The documentation looks like this: This is bold
The code would look like this:
*This is italics*
The documentation looks like this: This is italics
This is a one-line code sample:
``print variableName``
The documentation looks like this:
print variableName
You may also use links in your documentation. For example, if in one method you’d like to link to another method’s documentation, write:
:meth:`~music21.note.GeneralNote.addLyric`
The documentation looks like this:
addLyric()
Or you would like to link to another class, write:
:class:`~music21.note.Note`
The documentation looks like this:
Note
Sometimes pictures are useful to visually describe code to readers or to show the results of a .show() method call, etc. This is easy with sphinx. Just copy and paste the picture you’d like to use into the buildDoc/rst/images folder, and reference it in your documentation like this:
.. image:: images/completebach.*
:width: 300
The documentation looks like this:
Finally, if there is a section of your documentation that you’d rather sphinx not format at all, append two colons to the last line of formatted text, followed by a space, followed by the indented text block, followed by a space. Text written after this space will be formatted. For example, in your code write:
...blah blah blah this text is formatted. now I'm ready for not-formatted
text, so I put two colons::
this text is NOT formatted it must be indented
line breaks and spacing is preserved **bold** sphinx formatting is not
observed
Now I'm back to sphinx formatting...**now this is bold!*
The documentation looks like this:
…blah blah blah this text is formatted. now I’m ready for not-formatted text, so I put two colons:
this text is NOT formatted it must be indented
line breaks and spacing is preserved bold sphinx formatting is not observed
Now I’m back to sphinx formatting. now this is bold!
Displaying only some of the test code in the documentation¶
We use doctests a lot in music21 – if you run /music21/test/test.py, it will run not only all the code in class Test() but also all the code in the documentation preceeded by ‘>>>’ marks. This way our documentation and our test code doesn’t get out of sync with each other. Pretty cool, eh?
Here’s the thing: good programming means that you test as much as possible in the code, but good documentation means showing enough example code that the readers get it, but not so much that they want to claw out their own eyeballs. So how to proceed? simply add the line “OMIT_FROM_Docs” in ALL CAPS instead of lowercase. (I can’t write it in all caps here or nothing else will display!)
Anything after that line in your documentation code won’t display. For instance, say we wanted to demonstrate the difference between note.name and note.step, but also wanted to test to make sure that flats and sharps both were equally eliminated. We could write documentation/test-code like this (but with all caps)
'''
>>> from music21 import *
>>> c1 = note.Note('C#')
>>> c1.step
'C'
OMIT_FROM_Docs
(N.B. That should be capital DOCS above...)
>>> c2 = note.Note('C-')
>>> c2.step
'C'
'''
and what you’ll get in your documentation is:
>>> from music21 import *
>>> c1 = note.Note('C#')
>>> c1.step
'C'
Lines can be omitted on an individual basis by adding the expression “#_DOCS_Hide” (again in all caps) somewhere on the line. On the other hand, the text “#_DOCS_Show” (again in all caps) is removed from any line before it appears in the documentation. So you could use some of the same lines to test code and also to give an example like so:
>>> d1 = note.Note("D-")
>>> assert(d1.name == 'D-') #_DOCS_Hide
>>> #_DOCS_Show d1.show('lily.png')
in this case, the assertion code is omitted from the documentation generated from the module, while the lilypond file is not generated during doctests. It will look to your users like:
>>> d1 = note.Note("D-")
>>> d1.show('lily.png')
Together with OMIT_FROM_Docs, it’s a great way to have your cake and eat it too. (remember that these need to be in all caps)
Ordering Module-Level Class Names and Module-Level Functions¶
Classes are by default presented in the order in which they appear in the module. Module-level functions are by default sorted alphabetically. If that’s not what you want, then create a list called _DOC_ORDER which is a list of the class and/or function names in the module. These values are given as evaluated names, not strings.
Since this list uses classes and not strings, this list must come at the end of the module, after the Test classes and before calling music21.mainTest()
At the end of note.py for instance, we write:
_DOC_ORDER = [Note, Rest]
if __name__ == "__main__":
music21.mainTest(Test)
Ordering Class-Level Names¶
Classes can define a _DOC_ORDER attribute which functions the same as the module-level _DOC_ORDER, that is it defines the order of attributes, properties, and/or methods in the class.
Unlike for top-level names, these values are given as strings, not evaluated names. The _DOC_ORDER attribute must be defined outside of the __init__() method to ensure that these values can be read from a Class object and not just instances.
The following abbreviated example is from pitch.py:
class Pitch(music21.Music21Object):
'''Class doc strings.
'''
# define order to present names in documentation; use strings
_DOC_ORDER = ['name', 'nameWithOctave', 'step', 'pitchClass', 'octave', 'midi']
def __init__(self, name=None):
pass
Documenting Class-Level Properties¶
To document a property do something like this:
def _getName(self):
return self._storedName
def _setName(self, newName):
if newName == 'Cuthbert':
raise Exception("what a dumb name!")
else:
self._storedName = newName
name = property(_getName, _setName, doc = '''
The name property stores a name for the object
unless the name is something truly idiotic.
'''
Documenting Class-Level Attributes¶
Class-level attributes, names that are neither properties not methods, can place their documentation in a dictionary called _DOC_ATTR. The keys of the dictionary are strings (not evaluated names) corresponding to the name of the attribute, and the value is the documentation.
Like _DOC_ORDER, don’t put this in __init__().
Here’s an example from note.py:
class Note(NotRest):
'''
Class doc string goes here.
'''
isNote = True
isRest = False
# define order to present names in documentation; use strings
_DOC_ORDER = ['duration', 'quarterLength', 'nameWithOctave', 'pitchClass']
# documentation for all attributes (that are not properties or methods)
_DOC_ATTR = {
'isNote': 'Boolean read-only value describing if this object is a Note.',
'isRest': 'Boolean read-only value describing if this is a Rest.',
'beams': 'A :class:`music21.note.Beams` object.',
'pitch': 'A :class:`music21.pitch.Pitch` object.',
}
def __init__(self, *arguments, **keywords):
pass
If a _DOC_ATTR attribute is not defined, the most-recently inherited _DOC_ATTR attribute will be used. To explicitly merge an inherited _DOC_ATTR attribute with a locally defined _DOC_ATTR, use the dictionary’s update() method.
The following abbreviated example, showing the updating of the _DOC_ATTR inherited from NotRest, is from chord.py:
class Chord(note.NotRest):
'''
Class doc strings.
'''
isChord = True
isNote = False
isRest = False
# define order to present names in documentation; use strings
_DOC_ORDER = ['pitches']
# documentation for all attributes (not properties or methods)
_DOC_ATTR = {
'isNote': 'Boolean read-only value describing if this object is a Chord.',
'isRest': 'Boolean read-only value describing if this is a Rest.',
'beams': 'A :class:`music21.note.Beams` object.',
}
# update inherited _DOC_ATTR dictionary
note.NotRest._DOC_ATTR.update(_DOC_ATTR)
_DOC_ATTR = note.NotRest._DOC_ATTR
def __init__(self, notes = [], **keywords):
pass
Documenting Class-Level Methods¶
This is the most common type of documentation, and it ensures both excellent documentation and doctests. A typical example of source code might look like this:
class className():
[instance variables, __init__, etc.]
def myNewMethod(self,parameters):
'''
This is documentation for this method
>>> myInstance = className()
>>> myInstance.myNewMethod(someParameters)
>>> myUnicorn.someInstanceVariable
'value'
'''
[method code]
Building Documentation¶
Creating or updating the music21 documentation requires a few additional programs to be installed, most importantly one called Sphinx. Sphinx is a documentation generator that uses reStructuredText (rst) as its markup language and outputs HTML documents.
In addition, you will need to install music21 from the .tar.gz file on Github (https://github.com/cuthbertLab/music21/releases) or from the git repository (git://github.org/cuthbertLab/music21.git).
1) Install pip (if needed)
In order to get additional modules, you’ll need a way of getting them more easily. Recent versions of Python include pip or pip3; if you don’t have it, you should download it. Just go to https://pip.pypa.io/ and they’ll help you out.
2) Install pandoc
Pandoc is a universal documentation converter that we use. You can get pandoc at: http://pandoc.org/installing.html
Note that pandoc 1.14-1.15.0 do not work. 1.15.1 and newer are recommended.
3) Install nbconvert
Some of the tutorials and users guides for music21 use the Jupyter/IPython notebook. To convert these files to the Python documentation format .rst, you’ll need nbconvert (and pandoc). Run sudo pip3 install nbconvert. On Windows, omit the sudo. You will probably be asked for your password to install.
4) Downloading and Installing Sphinx
Sphinx is the document builder for Python. Run on Mac “sudo pip3 install sphinx” or on Windows “pip3 install sphinx”.
5) Run documentation/make.py
Find the documentation folder within the base folder of music21. Change directory to that directory and then run python3 make.py, which will automatically build all the music modules in music21 into the “autogenerated” folder and from there into the “build/html” folder. It should also open your web browser automatically.
If you can’t find your music21 installation run these commands: from music21 import * and then common.getSourceFilePath(). The documentation directory is the directory above this named documentation.
The first time you build the documentation, it’ll take a long time. Subsequent builds, however, only build the parts that have changed. If you need to build from scratch, run python3 make.py clean and you will have a clean directory to build again.
Using music21 with Git for Eclipse¶
Music21 stores its master code base in the Git code format at the GitHub website (https://github.com/cuthbertLab/music21 ). In order to have the latest, unreleased, versions of music21, which often incorporate new bug fixes, users will need to be familiar with Git.
Developers of music21 who want access to support or committing to the code base need to use the IDE called Eclipse, which allows for easy debugging and enforcing of coding standards such as consistent whitespace, no unused variable names, and simple error catching. Thus, while Eclipse is not strictly necessary to editing the Python files that make up music21, it is the only supported environment for receiving technical assistance. Thus students and others who wish to be part of the development team for music21 will need to follow the instructions below on using Git for Eclipse.
IMPORTANT: BEFORE BEGINNING, UNINSTALL ALL EXISTING VERSIONS OF `music21`. ADDITIONAL VERSIONS OF MUSIC21 INSTALLED IN OTHER LOCATIONS CAN CAUSE DIRECTORY ROUTING PROBLEMS.
Installing Git¶
First, make sure you have Git installed. You can find binaries for Windows, OSX and Unix at http://git-scm.com/.
But the best way to do almost everything with Git and music21 today is with the GitHub Desktop app, at https://desktop.github.com <https://desktop.github.com>.
Installing Eclipse¶
Once you have Git installed, download and install Eclipse. You can find the most recent version of Eclipse for Java EE at http://www.eclipse.org/downloads/, and these instructions are written with Eclipse for Java EE 4.8 (Oxygen) in mind though some screenshots are from 4.3 (Kepler).
Installing for Windows¶
For Windows users, the safest bet is the 32-bit version, regardless of your system’s capabilities.
If you download the 32-bit version save the Eclipse folder within the zip file in your “Program Files (x86)” directory if there is one, or “Program Files” if there isn’t.
If you choose the 64-bit version (getting more stable) then put the folder in the “Program Files” directory even if there is an “(x86)” directory. You may need to give permission or your password to make this copy.
After you’ve put the folder, go into the folder and drag a shortcut (by holding down Alt when dragging) to Eclipse to your start menu (or know how to find it later).
If you try running Eclipse and it gives you a warning about not having Java installed, go to http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html and download a copy there.
Installing for Mac¶
For Mac users, unless your computer is very old, download the 64-bit Java EE system.
For Mac users, once the .tar file has been unzipped, drag the ‘eclipse’ app. into the Applications folder in your Finder. Once done, click on the Eclipse icon.
You’ll be prompted to select a workspace directory, which, by default is created in your documents folder. Be sure to remember where this directory is, as it is where music21 will be installed. I use ‘/Users/cuthbert/git’ for my workspace (you probably wouldn’t use cuthbert).
If you get an error about Java being too old, download a new one from http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html
Installing for GNU/Linux/FreeBSD/Unix¶
You’ve chosen to run Unix – you should be able to figure this out on your own. :-)
Because there are so many slightly incompatible flavors of UNIX, the music21 team provides free support for problems arising with Windows and Mac installations only; UNIX users have saved a few hundred dollars by running a free OS and can spend their savings on paid support.
Installing PyDev for Eclipse¶
Note
If you are using Windows, make sure to install Python through the normal Windows installation routines. See Installing music21 in Windows.
Warning
If you are using Windows and have a firewall or anti-virus software active, we recommend disabling them while installing Eclipse plugins. Anti-virus software, such as AVG, can cause Eclipse to hang while attempting to fetch packages.
With Eclipse installed, you next need to install the plugin PyDev.
PyDev is a Python IDE for Eclipse, which may be used in Python, Jython, and IronPython development. EGit is a plugin that allows Eclipse to work with Git repositories. Both of these can be installed via the Eclipse Marketplace.
Launch the Eclipse Marketplace via Eclipse’s Help menu:
Search for PyDev in the Marketplace search box, and click Install in the proper search results: (the latest version is now 5.9)
When asked to confirm the installation, click Continue to return to the search dialog:
Now, when asked to confirm the installation of PyDev, click Confirm (note: your system probably won’t also have “EGit” listed).
You will be asked to accept the licensing for the plugin. Choose “I accept the terms of the license agreements” and click Finish:
Eclipse will now go through the process of automatically installing the plugin. When it finishes, you’ll be asked to confirm the certificate for PyDev. Click the checkbox and press OK:
Finally, Eclipse will ask to restart. Click Yes to complete the plugin installation process:
Forking music21 on GitHub¶
The main development paradigm in Git is to create a “Fork” or individualized copy of the music21 code base under your own name and make modifications there. You may “Pull” changes that we have made to the main music21 version into your own fork so that your fork stays up to date. If you’d like to contribute your changes back to the main codebase, you will initiate something called a “pull request” later.
To fork the official music21 repository, simply navigate to https://github.com/cuthbertLab/music21 on GitHub while signed in to your GitHub account, and click Fork in the upper right-hand corner of the page.
Cloning your music21 fork in Eclipse¶
Once you’ve forked music21 on GitHub, you need to clone your fork locally to your machine in order to start working.
To start the cloning process, choose Import… from Eclipse’s File menu, or right-click in the Package Explorer and choose Import from the contextual menu that appears.
In the Import dialog, open the Git folder and select Projects from Git, then click Next:
You may not see the “Repositories from GitHub” option on your computer. That’s okay, despite using GitHub, you won’t actually use this option.
You’ll now be asked to choose a repository source. While you can try using the GitHub repository source - which allows dynamically searching GitHub for repositories - if you’ve just made your fork a few minutes ago it won’t show up when searching. We recommend selecting the Clone URI option. Once you’ve selected Clone URI, click Next:
Now you need to enter information about your fork. For the purposes of this tutorial, we’ll use the fork of music21 found at https://github.com/josiah-wolf-oberholtzer/music21, but take note of the information for your own fork when proceeding here. The GitHub webpage lists the clone URL for this fork partway-down the right side of the page. The HTTPS clone URL for this fork is https://github.com/josiah-wolf-oberholtzer/music21.git.
Enter the GitHub clone URL into the URI field in the Location section of Eclipse’s dialog, then enter your GitHub credentials in the Authentication section. The other fields will be filled in automatically, and you don’t need to touch them.
When finished, press Next:
In the Branch Selection dialog, simply click Next:
In the Location Destination dialog, you can choose the local destination for the repository. By default, Eclipse will try and clone new repositories into a git folder in your home directory. In the example below, we’re opting to put it somewhere else.
Choose a new directory, or accept Eclipse’s default. Then, click Next:
Eclipse is now cloning your music21 fork! Sit tight: this will take a few minutes:
Once the cloning process has finished, click Next in the following dialog:
Finally, you’ll be given the option to choose how Eclipse will refer to the project. Choose music21base instead of music21.
Note
You can name your music21 Eclipse project whatever you like. However, we strongly recommend choosing a project name other than music21. Why? The project you’ve now downloaded contains a directory named music21. You may run into problems if you create subsequent projects in Eclipse which attempt to reference the music21 Python package inside the music21 Eclipse project. Naming the Eclipse project to something other than music21 mitigates this reference problem.
Configuring your music21 project with PyDev¶
You need to teach Eclipse that music21 should be considered a PyDev project. In the Package Explorer window, right-click on your music21 project and choose Set as PyDev Project from the PyDev submenu:
If you don’t see this option, see http://stackoverflow.com/questions/19873064/pydev-not-showing-up-in-eclipse
You also need to tell PyDev that your project should be included in your Python path. If you don’t do this, Python won’t be able to find music21 at all.
Configuring the music21 Environment¶
Configuring the music21 Environment is done mostly like a normal install with one big difference noted below.
To create a user environment settings file, open the music21/configure.py file and run it by pressing the green circle with a white arrowhead in it at the top of the Eclipse interface.
A new “Run As” window will appear in which you will be prompted to select a way to run configure.py. Choose “Python Run” and click on “OK.” (You should always click this when running Python programs)
In the console, you may see errors about installing additional packages, after which you will see a message beginning with “Welcome to the music21 Configuration Assistant.”
When asked if you would like to install music21 in the normal place for Python
packages, type no and press Enter.
Warning
Make sure you write no here.
See User’s Guide, Chapter 24 for more information on configuring user settings. Otherwise, head to: What is Music21? for further demos and tutorials on using music21.
Committing, pushing and pulling¶
This used to be really hard…now look at the instructions for the Github Desktop app.
Sending pull requests to the official music21 repository¶
To get your changes into the official music21 repository, you’ll have to make a pull request via the GitHub web site or the desktop app.
A pull request is just what it sounds like: a request to another repository (the music21 team’s copy) for them to pull in changes from your repository and add them to the centralized version.
Making pull requests is easy:
Log into GitHub and find your fork of music21. Under the repository summary header you’ll see a green button with two arrows, labeled “Compare & review”.
Click that button:
If your repository differs from the official music21 repository, you’ll be shown the diff stats, as well as a large banner with the text
Click to create a pull request for this comparison.Click on that banner to continue:
Almost done. Now you can write a description of what your pull request involves. While the music21 team can and will review the diffs for your request, please provide a useful description. What do your changes accomplish? Do they address one of the issues in the official issue tracker? Which issue? Do they represent an enhancement, or new functionality?
When you’ve finished writing your description, click on the
Send pull requestbutton. You’ve sent your pull pull request!
Getting your pull requests accepted¶
Once you’ve sent a pull request to the music21 team they’ll need to review the changes you’ve suggested. They can opt to accept some, all or none of the commits you’ve included in your pull request. If the work looks good, they’ll merge your changes into the official repository.
What do we mean by the “if the work looks good”? The first and highest priority is that if the code expands music21 in any way that it is well documented (see Documenting music21) and includes tests that ensure that future changes to the system will not break the code. You will need to run test/multiprocessTest.py which will update the file test/lastResults.txt to show that the tests have passed. To run these tests you will need to install the optional modules such as NumPy, matplotlib, etc. The tests you have written cannot add appreciatively to the amount of time it takes to run the test suite (so a few milliseconds for a tiny addition, at most a second or two for a major contribution). The code needs to be well placed within the structure of the library so as not to add unneeded complexity. For instance, if your new methods will only apply to a small number of users working on a constrained repertory (such as chorales, jazz, medieval music, etc.) it should not add ten new methods to Note or Stream. The contributions cannot require any new external dependencies and even optional dependencies should be discussed with the music21 team before attempting a Pull Request. The code should work on Mac, Windows (watch out for file system calls), and Unix equally well. It sounds hard, but after a while looking out for these caveats becomes second nature and will help ensure the toolkit is viable for at least a decade to come.