Quick Start: Getting Started with music21

Here are some quick steps to get up and running quickly with music21.

Download and Install

First, download and install music21. Read the full instructions at: Installing Music21.

Starting Python and Importing Modules

Like all Python functionality, music21 can be run from a Python script (a .py file) or interactively from the Python interpreter. The Python interpreter is designated with the command prompt >>>.

On UNIX-based operating systems with a command line prompt (Terminal.app on Mac OS X), entering python will start the Python interpreter.

On Windows, starting IDLE from the start menu will provide an interactive Python session.

Once you start Python, you can check to see if your music21 installation is correctly configured by trying to import a music21 module. A module is a Python file that offers reusable resources. These are all found inside the music21 package, so often we will import a module (or all of them) from music21. To import the music21.corpus module from music21, enter the following command.

>>> from music21 import corpus

Assuming this works, your music21 installation is complete and you can move on. However, you may get the following error:

>>> from music21 import corpus   
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named music21

If this happens, Python is not able to find the music21 package. Return and review the instructions in Installing Music21 or contact the music21 group for help:


Examining a Score

Once music21 is installed, opening and examining a score and it elements is a good first step. Music21 comes with a corpus, a large collection freely distributable music stored in the MusicXML and humdrum formats. These files can be found in the music21/corpus directory. However, tools are provided for easy, direct access.

To import, or parse, a score stored in the corpus, use the music21.corpus module. (To see a complete listing of works in the corpus, see List of Works Found in the music21 Corpus.) We imported this module above, but here, lets import all music21 modules with the catch-all import statement from music21 import *. We will often use this import statement to quickly import all modules for easy access.

We will the use the parseWork() method to translate the file (a MusicXML or humdrum file) into music21 objects.

>>> from music21 import *
>>> sBach = corpus.parse('bach/bwv7.7')

The score is returned as a music21 Score, which is a type (subclass) of a music21 Stream.

Once the score is parsed, we can view, transform, and manipulate its components in a variety of ways. If we want to output and view the entire score, we can use the show() method.

Without any arguments, this method does two things. First, it writes a MusicXML file (the default output format) of the current Stream as a temporary file or in the user-specified scratch directory. (This directory can be defined as part of the user’s Environment settings. See Configuring Environment Settings for complete details.) Second, it attempts to open this file with a user-specified helper application.

For a MusicXML file, an application that can load and display a MusicXML file as notation, or a MusicXML reader, is very useful. See Installing Music21 for information on “Additional Software Components,” or download and install MuseScore or Finale Reader immediately:



After installing an appropriate MusicXML reader, the generated file can be examined and opened. For music21 to automatically open MusicXML files, you may need to set a music21 musicxmlPath preference in Environment (see Configuring Environment Settings). Once the MusicXML file has been opened, the following output (excerpted) will be displayed.

>>> sBach.show()   

If we do not have a MusicXML reader handy, we can always show the components of a Stream in a text format, with the optional ‘text’ argument passed to the show method. Here is an excerpt of the output.

>>> sBach.show('text')      
{0.0} <music21.stream.Part object at 0x2a85d70>
    {0.0} <music21.instrument.Instrument P1: Soprano: Instrument 1>
    {0.0} <music21.stream.Measure 0 offset=0.0>
        {0.0} <music21.meter.TimeSignature 4/4>
        {0.0} <music21.clef.TrebleClef object at 0x2ca7e50>
        {0.0} <music21.key.KeySignature of 2 sharps>
        {0.0} <music21.note.Note E>
        {0.5} <music21.note.Note F#>
    {1.0} <music21.stream.Measure 1 offset=1.0>

Once the score has been parsed, we can access its components, as with all Streams, in multiple ways. A Score often, but not always, includes Part objects (specialized Streams that contain Measures) and a Metadata object.

The components of a Stream can be accessed as a list of elements accessed by index values. Index values in Python, as common in many programming languages, count from zero. Using the Python len() method, We can see that the Score as six components, index numbers 0 through 4.

>>> len(sBach)
>>> sBach[0]
<music21.metadata.Metadata object at ...>
>>> sBach[1]
<music21.stream.Part Soprano>

Components of a Stream subclass, filtered by class type, are made available through property names. For example, all of the Part objects of this Score can be accessed with the parts property.

>>> len(sBach.parts)

We can view one of these Parts by accessing the appropriate component and calling the show() method.

>>> sBach.parts[0].show()  

Again, we can view the components of the Part with the ‘text’ option for the show() method:

>>> sBach[0].show('text')  
{0.0} <music21.instrument.Instrument P1: Soprano: Instrument 1>
{0.0} <music21.stream.Measure 0 offset=0.0>
    {0.0} <music21.meter.TimeSignature 4/4>
    {0.0} <music21.clef.TrebleClef object at 0x18e9310>
    {0.0} <music21.key.KeySignature of 2 sharps>
    {0.0} <music21.note.Note E>
    {0.5} <music21.note.Note F#>
{4.0} <music21.stream.Measure 1 offset=4.0>

Parts contain numerous components, including Instrument objects. We can access the components of a Part by index, or directly access Measures from within a Part by using the measures() method. In the following example, measures 2 through 4 are extracted from the Part as a new Stream (called select) and displayed with the show() method.

>>> select = sBach.parts[0].measures(2,4)
>>> select.show()  

Measures contain numerous components, including Clef, KeySignature, TimeSignature, Note, and other objects. We can access the Notes of a Measure directly with the notes property. This property returns a Stream of all Notes and Chords found in a given Measure (but not Rests). Like all Streams, the components can be accessed by index values starting from zero. To view the first note of the second measure (stored in the Stream select), we can do the following.

>>> select[0].notes[0].show()  

Examining a Score by Part Id

Alternatively, we can access components of a Stream by id, or string identifiers. Streams can get components by id by using the getElementById() method. For example, we can first look at all id attributes of all Score elements, and then select one.

>>> [part.id for part in sBach.parts]
['Soprano', 'Alto', 'Tenor', 'Bass']
>>> sBach.getElementById('Soprano')
<music21.stream.Part Soprano>

Creating Notes, Measures, Parts, and Scores

We can create notes and measures from scratch using music21. Nearly every common music component has a Class that does what you expect (and a lot more).

If we wanted to re-create a few measures form a popular counterpoint text, we can create Notes and add them to Measures. We can then add Measures to Parts, and then Parts to Scores. At each step along, we can call the show() method to check our progress. In the first stage, we will create the bottom Part, and do this explicitly, one object at a time.

>>> from music21 import *
>>> n1 = note.Note('e4')
>>> n1.duration.type = 'whole'
>>> n2 = note.Note('d4')
>>> n2.duration.type = 'whole'
>>> m1 = stream.Measure()
>>> m2 = stream.Measure()
>>> m1.append(n1)
>>> m2.append(n2)
>>> partLower = stream.Part()
>>> partLower.append(m1)
>>> partLower.append(m2)
>>> partLower.show()  

We might automate this procedure by using Python’s loop control structure and nested data structure of lists within lists. We can store the desired pitches and duration in a list, grouped by measure, and then iterate through them to create Measures and Notes.

>>> data1 = [('g4', 'quarter'), ('a4', 'quarter'), ('b4', 'quarter'), ('c#5', 'quarter')]
>>> data2 = [('d5', 'whole')]
>>> data = [data1, data2]
>>> partUpper = stream.Part()
>>> for mData in data:
...     m = stream.Measure()
...     for pitchName, durType in mData:
...         n = note.Note(pitchName)
...         n.duration.type = durType
...         m.append(n)
...     partUpper.append(m)
>>> partUpper.show()  

Finally, we can add both Part objects to a Score object. To display both parts simultaneously, we need to use the insert() method, adding each Part at the 0 position of the Score.

>>> sCadence = stream.Score()
>>> sCadence.insert(0, partUpper)
>>> sCadence.insert(0, partLower)
>>> sCadence.show()  

Next Steps

The following chapters provide introductions to key components of music21. Proceeding through usersGuide_02_notes, Overview: Streams, Scores, Parts, and Measures, Overview: Importing File and Data Formats, and Overview: Post-Tonal Tools provide an excellent introduction to the music21 toolkit.