pubPhotos

What is music21?

Music21 is a set of tools for helping scholars and other active listeners answer questions about music quickly and simply. If you’ve ever asked yourself a question like, “I wonder how often Bach does that” or “I wish I knew which band was the first to use these chords in this order,” or “I’ll bet we’d know more about Renaissance counterpoint (or Indian ragas or post-tonal pitch structures or the form of minuets) if I could write a program to automatically write more of them,” then music21 can help you with your work.

How simple is music21 to use?

Extremely. After starting Python and typing "from music21 import *" you can do all of these things with only a single line of music21 code:

Display a short melody in musical notation:
converter.parse("tinynotation: 3/4 c4 d8 f g16 a g f#").show()

Print the twelve-tone matrix for a tone row (in this case the opening of Schoenberg's Fourth String Quartet):
print (serial.rowToMatrix([2,1,9,10,5,3,4,0,8,7,6,11]) )

or since all the 2nd-Viennese school rows are already available as objects, you can type:
print (serial.getHistoricalRowByyName('RowSchoenbergOp37').matrix() )

Convert a file from Humdrum's **kern data format to MusicXML for editing in Finale or Sibelius:
converter.parse('/users/cuthbert/docs/composition.krn').write('musicxml')

With five lines of music21 code or less, you can:

Prepare a thematic (incipit) catalog of every Bach chorale that is in 3/4:

catalog = stream.Opus()
for workName in corpus.getBachChorales():
  work = converter.parse(workName)
  firstTS = work.flat.getTimeSignatures()[0]
  if firstTS.ratioString == '6/8':
    catalog.append(work.measureRange(0,2))
catalog.show()

Google every motet in your database that includes the word ‘exultavit’ in the superius (soprano) part (even if broken up as multiple syllables in the source file) to see how common the motet's text is:

import webbrowser
for motet in listOfMotets:
  superius = motet[0]
  lyrics = text.assembleLyrics(part)
  if 'exultavit' in lyrics:
    webbrowser.open('http://www.google.com/search?&q=' + lyrics)

Add the German name (i.e., B♭ = B, B = H, A♯ = Ais) under each note of a Bach chorale and show the new score:

bwv295 = corpus.parse('bach/bwv295')
for thisNote in bwv295.flat.notes:
  thisNote.addLyric(thisNote.pitch.german)
bwv295.show()

Of course, you are never limited to just using five lines to do tasks with music21. In the demos folder of the music21 package and in the sample problems page (and throughout the documentation) you’ll find examples of more complicated problems that music21 is well-suited to solving, such as cataloging the rhythms of a piece from most to least-frequently used.

Music21 builds on preexisting frameworks and technologies such as Humdrum, MusicXML, MuseData, MIDI, and Lilypond but music21 uses an object-oriented skeleton that makes it easier to handle complex data. But at the same time music21 tries to keep its code clear and make reusing existing code simple. With music21 once you (or anyone else) has written a program to solve a problem, that program can easily become a module to be adapted or built upon to solve dozens of similar (but not identical) problems.

Interested in learning more?

Latest music21 News

[April 11, 2015 13:47 pm] « » [music21]
The RILM blog, Bibliolore, published a recent post about the early history of computational musicology:

In the 1940s Bertrand Harris Bronson became one of the first scholars to use computers for musicological work.
For one of his projects he encoded melodic characteristics of hundreds of tunes collected for the traditional ballad Barbara Allen on punch cards, so a computer could ferret out similarities. His project resulted in four groups of tunes, members of which came from both sides of the Atlantic with varying frequency.
Read more at their site.  The RILM blog is amazing in any case.
[March 14, 2015 14:28 pm] « » [music21]
The master of empirical music studies and the inventor of Humdrum, David Huron, announced a workshop to be held in late May in Columbus, Ohio -- probably of great interest to anyone working with music21 who wants to put their work into a broader context:


Methods in Empirical Music Research: A Workshop for Music Scholars.
Monday May 18 to Friday May 22, 2015.
School of Music, Ohio State University

We are pleased to announce a workshop on empirical methods in music research. This is an intensive five-day workshop taught by Prof. David Huron.

The workshop will be of interest to anyone wishing to expand or enhance their research skills in music. Participants will learn how to design and carry out music experiments, and how to apply empirical, systematic and statistical techniques to problems in music history, analysis, performance, education, culture, policy, and other areas. The workshop is designed specifically to develop practical research skills for musicians and music scholars with little or no previous background in empirical methods.

The workshop introduces participants to a number of methods, including descriptive, exploratory and questionnaire methods, field research, interview techniques, correlational and experimental methods, hypothesis testing, theory formation, and other useful research tools and concepts. Participants will also learn how to read and critique published empirical research related to music - identifying strengths and weaknesses in individual music-related studies.

The workshop objectives will be pursued through a series of day-long activities, including lectures and demonstrations, interspersed with twenty hands-on and group activities.

Three different forms of registration are available for workshop participants. The fee for non-credit participation is $450. A fee schedule for continuing education, and graduate course credit (2 credit hours) is pending. Participants are responsible for their own transporation, food and accommodation.

For further details, see http://musiccog.ohio-state.edu/home/index.php/Workshop
[January 15, 2015 12:37 pm] « » [music21]

An important milestone for music21 passed unnoticed by me a few weeks ago: ten years since the first time that code (well mostly documentation and tests) that still remains somewhere in the music21 codebase was run and did something useful (a scrambled loop for a composition project I was working on called Fine dead sound, after Faulkner).  It seemed worth saying a bit about the history of the project and things learned along the way.

Music21 started as a Perl project -- the oldest code I can find that even vaguely resembles the current music21  comes from November 2003, a 30k Perl script to label a Bach chorale with Roman numerals and correct keys (I still need to publish the algorithm somewhere since I haven't seen a better one). It had no graphical output except using David Rakowski's Lassus font. I was able to get it back up and running and through the modern miracle of web fonts, everyone (except IE users) can play with the oldest  music21  system at: http://www.trecento.com/test/lassus.cgi?num=260. If I remember correctly, chords in red had only a passing functionality, the small letters are the roots of chords and the second line of text is the locally active key. Pivot chords are labeled in brackets. This was done for an assignment in Avi Pfeffer's AI and Music class; others in my group had already produced the code (in C I believe) for removing passing tones from the score.

I had begun that project using Humdrum, a system I knew well and still have great admiration for, but I began to need to encapsulate more and more items into individual classes.  I googled around, because I figured someone would have already gotten far in an object-oriented replacement for Humdrum. But I found nothing, so when I got back to the project about a year later I started creating generalized objects which I incorporated into a package called "PMusic" for "Perl Music." (I think I first called it just "Music" but realized that this was going to be a problem.)  Here is part of the PMusic code for Chords, written on 12/31/2004.  Good documentation was already a music21 principle, but names of notes were still based on Kern/Humdrum:


=head1 PMusic::Chord (class)

class for dealing with chords

  $ch1 = PMusic::Chord->new(['CC', 'E', 'g', 'b-']);

Note double set of brackets, indicating a perl array reference.
Doesnt deal with rests yet.  Chords of more or less than four notes might
be odd...

Can also give an arrayRef of Note objects if you're that perverse...

=cut

package PMusic::Chord;
use strict;
use Carp;

sub new {
  my $proto = shift;
  my $class = ref($proto) || $proto;
  my %args;

  ## if only one arg, assume it's an arrayref of Note names
  if (scalar @_ == 1) { $args{Notes} = $_[0] }
  else { %args = @_ };
  my $self  = \%args;
  bless $self, $class;
}

### for now, first note is always bass of chord (does tenor ever go below bass? sometimes!)

=item NoteObjs()

Returns an array ref of PMusic::Note objects

=cut

sub NoteObjs {
  my $self = shift;
  return $self->{NoteObjs} if $self->{NoteObjs};
  my @objs = ();
  foreach (@{$self->{Notes}}) {
    if (ref($_)) { push @objs, $_; }
    else         { push @objs, Note->new($_); }
  }
  $self->{NoteObjs} = \@objs;
}

=item Bass([note PMusic::Note])

returns the bass note or sets it to note.  Usually defined as the first noteObj
but we want to be able to override this.  You might want an implied
bass for instance...  v o9.

=cut

sub Bass {
  my $self = shift;
  $self->{Bass} = $_[0] if defined $_[0];
  $self->{Bass} ||= $self->NoteObjs->[0];
  return $self->{Bass};

}

At this point I was living in Rome at the American Academy as a Rome Prize fellow in Medieval Studies, and halfway through my fellowship I realized that none of this code was going to write a six-hundred page dissertation on fourteenth-century music fragments, and besides, I had job interviews to prepare for, and later, students to teach at Smith College, Mount Holyoke College, and then MIT, none of which (yes, including MIT) cared that I was working on generalized software for musical analysis as a side project. I also saw how long this project was going to take.  And besides, I was still convinced that someone had already written a generalized OO toolkit for musical analysis, I just wasn't searching well enough.  So the project was put aside for almost two years before it reemerged in Python, as the (to be written) Part 2 explains.
[January 11, 2015 17:14 pm] « » [music21]
We're happy to announce that the first public alpha of music21 v.2 has been released!

Version 2 is the first version of music21 since v.1 to make substantial changes in the code base that introduce backwards incompatibilities in order to make going forward faster and smoother.  It doesn't change anything super fundamental à la Python 3's print function, so most code should still run fine, but definitely test in a separate environment before upgrading on any code you have that needs to run without problems.  The system is still changing and more backward-incompatible changes could be included until v.2.1.

We have had 420 commits since the last release, so there is a lot that is new!

Substantial changes include:

  • Offsets and quarterLengths are now stored internally as Fractions if they cannot be exactly represented as floating point numbers. A lot of work went into making this conversion extremely fast; you probably won't ever notice the speed difference, but you can now be sure that seven septuplets will add up to exactly a half note.  For instance:
  • >>> n = note.Note()
    >>> n.duration.appendTuplet(duration.Tuplet(3,2))
    >>> n.fullName
    'C in octave 4 Quarter Triplet (2/3 QL) Note'
    >>> n.quarterLength
    Fraction(2, 3)
    >>> n.quarterLengthFloat # if you need it...
    0.6666666666666666
  • Converter structure has been overhauled for more easily adding new converters in the future. If you've wanted to write a converter or already have one for a format not supported but have been daunted by how to include it in music21 now is a great time to do it.  Speaking of which...
  • MEI format is supported for import (thanks to Chris Antila and the ELVIS team at McGill university for this great enhancement)
  • Python 2.6 is no longer supported. All tests and demos pass and run on Python 2.7, 3.3, and 3.4. (3.2 and older are not supported)
  • FreezeThaw on Streams works much better and caching loaded scores works great (some of this was included in 1.9, so definitely upgrade at least to that.
  • Much improved Vexflow output using music21j, Javascript/Vexflow rendering engine. Was in 1.9, but improved here.
  • Lots of places that used to return anonymous tuples, now return namedtuples for more easily understanding what the return values mean.
  • Integrated Travis-CI testing and Coverage tests will keep many more bugs out of music21 in the future.
  • Many small problems with Sorting and stream handling fixed.
  • Corpus changed: for various licensing reasons, v.2.0 does not include the scores from the MuseData corpus anymore. This change mostly affects Haydn string quartets and Handel's Messiah.  However, new replacement scores are being included and 2.1 will have as many great works as before.  The MuseData scores are still available online.  MuseData is now a deprecated format and no further testing on it will be conducted; only bug fixes that are easily implemented will be accepted.
  • music21 is now available under the BSD license in addition to LGPL! 

We will try to stick to something close to the semantic versioning model in the future once v.2.1 is released. In other words, after 2.1, we'll try very hard not to break anything that worked in v.2.1 until v. 3.0 is released.  This will probably mean that the version numbers are going to creep up faster in the future.

Still todo before v.2.1 is a major change in how elements are stored in Streams.  Stay tuned if you care about performance tweaks etc., otherwise ignore it -- we'll keep the interface the same so you might not notice anything except speed improvements.

Smaller backward-incompatible changes include:
  • Stream __repr__ now includes a pointer rather than a number if .id is not set.  This change will make filtering out doctests easier in the future.
  • TinyNotation no longer allows for a two-element tuple where the second element is the time signature.  Replace: ("C4 D E", "3/4") with ("tinynotation: 3/4 C4 D E")
  • Obscure calls in SpannerBundle have been removed: spannerBundle.getByClassComplete etc.
  • Convenience classes: WholeNote, HalfNote, etc. have been removed.  Replace with Note(type='whole') etc.
  • Old convenience classes for moving from Perl to Python (DefaultHash, defList) have been removed or renamed (defaultlist) 
  • Articulations are marked as equal if they are of the same class, regardless of other attributes.
  • common.almostLessThan, etc. are gone; were only needed for float rounding, and that problem is fixed.
  • duration.aggregateTupletRatio is now aggregateTupletMultiplier, which is more correct.
  • scala.ScalaStorage renamed scala.ScalaData
  • common.nearestMultiplier now returns the signed difference.
  • layout -- names changed for consistency (some layout objects had "startMeasure" and some "measureStart" - now they're all the same); now all use namedtuples.
  • rarely used functions in Sites, base, Duration, SpannerStorage, VariantStorage, have been removed or renamed.  I'd be surprised if these affect anyone outside the development team.
Improvements and bug fixes:
  • common.mixedNumeral for working with large rational numbers
  • common.opFrac() optionally converts a float, int, or Fraction to a float, int, or Fraction depending on what is necessary to get exact representations. This is a highly optimized function responsible for music21 working with Fractions at about 10x the speed of normal Fraction work.
  • Rest objects get a .lineShift attribute for layout.
  • staffDetails, printObject MXL had a bug, writing out "True" instead of "yes"
  • staffLines is now an int not float. (duh!)
  • better checks for reused pointers.
  • lots of private methods are now ready for public hacking!
  • Lyric.rawText() will return "hel-" instead of "hel" for "hel-lo".
[July 23, 2014 21:39 pm] « » [music21]
[This is a guest post by Derek Klinge who uses music21 in his research on music and disability. I thank him for his contribution. - MSC]

I am a researcher within the Performing Arts Medicine Association. I was interested in looking at Beethoven's use of range over time in his piano sonatas. Although several previous studies have looked at the question of how Beethoven's compositions were affected by his hearing loss, the results were far less than conclusive. A study in the British Medical Journal counted the notes in the first movements of the first violin parts of Beethoven's string quartet's by hand. For a number of reasons, I thought it might be better to look at the piano sonatas, including that Beethoven wrote more piano sonatas than he did string quartets and symphonies, so the statistical power would be greater. Counting all of the notes in Beethoven's piano sonatas by hand would be a Herculean task for sure, but fortunately with scores available from the Center for Computer Assisted Humanities and music21 sufficient coding skills would do the job.

Why music21?

In addition to the number of high notes, I was also interested in Beethoven's overall use of range, the average note, average frequency, number of measures with high notes, and in calculating values based on the number of notes, as well as weighting those measures by the duration of notes. The methods available in music21 allow the collection of this data very quickly. To collect the majority of the data I needed from all 103 movements of Beethoven's piano sonatas, count over a quarter million individual notes, and organize the data into sonatas, and separating the data by movement number, takes about 11 minutes.

Some Interesting Findings

Beethoven's use of high notes was lowest around 1800 (for all the graphs below, the colors within the dots represent the Sonata Numbers, going from red to purple from 1-32):


The average frequency of each sonata follows a similar trend:

In general, as there are more notes per measure, there are more high notes per measure. This trend does not hold many of the sonatas written before 1802.

Also, the relationship between the use of high notes, and the average frequency was different between the earlier and later sonatas:


Conclusions

Technology like music21 is an invaluable tool for the empirical study of musicology. Relatively quickly, data gathered can be used to analyze the possible relationships between Beethoven's use of high notes and his overall range, and compare that with what we understand about his hearing loss. These data suggest that Beethoven was significantly affected by his hearing loss, though it seems that sometime around 1802 he developed strategies to cope with his progressing disability.
[June 25, 2014 20:09 pm] « » [music21]
We are proud to release music21 v1.9.3, the latest and last release in the 1.x series.
There have been 147 commits in the two months since v1.8; here are some of the highlights:
  • MUCH faster .getContextByClass (KUDOS to Josiah Oberholtzer for this). Even if you don't use .getContextByClass in your own code, you're definitely calling something that calls it. This method figures out where the most recent key signature, time signature, clef, etc. is for any given object, finds relationships between notes in different voices, etc. For analysis of medium-sized scores (say, 3 voices, 100 measures) expect a 10-fold speedup. For larger pieces, the speedup can be over 100-fold.
  • A new stream/timespans module that makes the previous speedup possible by representing m21 Streams as AVL trees -- it's used in a few places (needs more docs), forthcoming releases will use it in a lot more places
  • Python3 support (3.3 and later). The entire test/multiprocessTest.py suite passes on Python 3. N.B. to contributors -- from now on all contributions need to pass tests on both Python 2.7 and 3.3 and later. Negative -- in the past you could have made music21 run on unsupported older systems (2.6 and sometimes 2.5); now from music21 import * will fail on pre-2.7. 2.7 has been a requirement since Music21 1.7. Fewer than 30% of Macs still in use are running Lion or earlier and thus will need to update to 2.7. This version of music21 runs about 25% faster on Python 3 than Python 2, but otherwise no new features of Python3 are used. Python 2.7 will be supported throughout the Music21 2.x cycle so no panicking -- it'll be years (if ever) before Python 3.3+ is a requirement.
  • Improvements to reductions of scores. And to analyzing voiceleading motion (some of this is backwards incompatible)
  • Better, faster, and more consistent sorting of elements in a Stream
  • Changes to the derivations module that I doubt anyone else was using anyhow...
  • Removed obsolete files.
  • Stafflines import and export from musicxml (thanks Metalmike!)
  • Complete refactoring of converter.py to make it easier for users to write their own Subconverter formats (that can eventually be put into the system)
  • Complete serialization of Streams via a new version of jsonpickle. This has big implications down the line; for now it affects...
  • Vexflow output is much improved (unless you were counting on Voices; in which case do not upgrade) using the alpha version of music21j -- Javascript reimplementation of music21's core features.
  • IPython improvements, allowing for robust and persistent communication between Javascript and Python. This will eventually (once I document it...) let you use the web browser as a UI for music21 python apps including live updating of music notation. It's too complex for most users right now, but I can attest that this will be one of the biggest perks of the 2.x development.
The usual bug fixes, documentation improvements and fixes, etc. are implemented. Thanks to MIT, the NEH, and the Seaver Institute for funding the project. (and to MIT for tenuring me in part on the basis of music21). This is the last release that Josiah Oberholtzer was lead programmer for; his considerable talents will still be on display in Abjad and many other projects he works on, and the implications of the new storage system he has developed will continue to pay off for years.

What's next?

Starting work on music21 2.0 today. That release will have some backwards incompatible changes that developers will need to deal with -- just as the path to 1.0 meant that some things that were originally thought of as good ideas were thrown out, the path to 2.0 will rely on 8 years of using music21 to fix some things that really should've been done differently from the beginning. Having just spent 2 weeks making m21 compatible with Python 3, I will give my assurance that as few incompatibilities as possible will be introduced. Most of the major changes will be on the core -- so if you've never messed with Sites, SpannerStorage, etc., you'll be fine.
  • Problems with 5 quintuplets = .99999999 of a beat will disappear. Music21 2.X will store offsets and quarterLengths internally as rational numbers (actually a custom MixedNumeral class, so that the __repr__ is nicer...). All music21 objects will gain four properties: ".offsetRational, .duration.quarterLengthRational, .offsetFloat, and .duration.quarterLengthFloat" -- in music21 2.0, .offset and .duration.quarterLength will be aliases for offsetFloat and .duration.quarterLengthFloat -- so no changes will be needed to existing code. This will give a period of time (6 months?) to switch .offset either to .offsetFloat or .offsetRational. We'll have a tool to make the switch automatically. Then at a certain point, .offset will become an alias for .offsetRational. By music21 3.0 .offset will only support Rational numbers.
  • Streams will store the position of notes, etc. in them. Right now this is all stored in the Note object itself. There are some great reasons for doing it that way, but significant speedups will take place by shifting this.
  • inPlace will be False by default for all operations on Notes, Streams, etc. -- you can plan for the migration by explicitly setting inPlace for every call now.
  • Some changes to boundary cases in .getElementsByOffset will take place -- it will not change much, but for a few users this will be crucial.
  • NamedTuples and OrderedDicts will appear in a lot of places
that's all for now, but more examples to come soon. - Myke

How can I contribute?

Music21 is a rapidly-progressing project, but it is always looking for researchers interested in contributing code, questions, freely-distributable pieces, bug fixes, or documentation. Please contact Michael Scott Cuthbert (cuthbert at mit.edu), Principal Investigator.

The development of music21 has been supported by the School of Humanities, Arts, and Social Sciences at M.I.T., the Music and Theater Arts section, and generous grants from the Seaver Institute and the NEH/Digging-Into-Data Challenge. Further donations to the project are always welcome.