Frequently Asked Questions


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 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 ( 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 just 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 homage in Anas Ghrab’s music22 package:

When I was giving a talk in Germany, everyone referred to it as Musikeinundzwanzig, and that made me happy, so feel free to localize the name however you like when speaking in your language. Musique vignt-et-un, 音楽二十一, whatever.

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 s.freeze() and then s.thaw() later. Or for more deeply configurable needs, setupSerializationScaffold() and teardownSerializationScaffold() 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 at or 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.

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).


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, can 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 music21.omr.correctors.

I’m having trouble reading in MIDI. The docs for music21.midi.translate and music21.converter.subConverters.ConverterMIDI are rather hard to understand. (Same for musicxml, mei, etc.)

You shouldn’t need to be going into subConverters or the various format modules, like music21.midi or music21.musicxml in everyday use. Just load the file into the system with music21.converter.parse(filename) and it will figure out the right format and everything else, and give you a Stream object. To load from the internet, you can pass in a URL instead. If filename does not give enough information to determine the file type, add format=’midi’ and it will do the right thing.

To save a Stream (stored as variable s) afterwards, just call: s.write(‘midi’, fp=’filename.mid’). Or to hear it immediately,‘midi’).

Feature requests and Consulting

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).

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 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: