.. _what:

.. WARNING: DO NOT EDIT THIS FILE:
   AUTOMATICALLY GENERATED.
   PLEASE EDIT THE .py FILE DIRECTLY.


    %matplotlib inline

What is ``music21``?
====================

``Music21`` is a Python-based toolkit for computer-aided musicology.

People use ``music21`` to answer questions from musicology using
computers, to study large datasets of music, to generate musical
examples, to teach fundamentals of music theory, to edit musical
notation, study music and the brain, and to compose music (both
algorithmically and directly).

One of ``music21``'s mottos is "Listen Faster." With the toolkit you
should be able to find interesting moments and get a sense of the
overall profile of a piece or a repertory of pieces. We hope that with
the computer you'll have more time for listening and playing for
enjoyment and use less of your time listening for work.

The system has been around since 2008 and is constantly growing and
expanding. The approaches and traditions in ``music21`` have been used
in many previous software systems. See :ref:`about` for information on
the authors and background of the project.

The *21* in ``music21`` refers to its origins as a project nurtured at
MIT. At MIT all courses have numbers and music, along with some other
humanities departments, are numbered ``21``. The music departments of
MIT, along with Harvard, Smith, and Mount Holyoke Colleges, helped bring
this toolkit from its easiest roots to a mature system.

Finding solutions in a hurry
----------------------------

With ``music21`` adds a collection of specialized tools and objects to
the general-purpose and easy to understand "Python" programming
language. Install ``music21`` and type ``python`` (or, better,
``ipython3``) and load it by typing:

.. code:: python

    from music21 import *

...and thousands of musical tools become available to you. For instance,
want to see a note on the screen? Type these lines:

.. code:: python

    n = note.Note("D#3")
    n.duration.type = 'half'
    n.show()




.. image:: what_7_0.png



Need a whole line of notes? Even easier:

.. code:: python

    littleMelody = converter.parse("tinynotation: 3/4 c4 d8 f g16 a g f#")
    littleMelody.show()




.. image:: what_9_0.png



Want to hear the melody? It's just as easy! (Please give it a second or
two after hitting play for the piano sounds to load):

.. code:: python

    littleMelody.show('midi')



.. raw:: html

    
                    <div id='midiPlayerDiv596'></div>
                    <link rel="stylesheet" href="http://artusi.xyz/music21j/css/m21.css" 
                        type="text/css" />
                    <script>
                    require.config({
                        paths: {'music21': 'http://artusi.xyz/music21j/src/music21'} 
                    }); 
                    require(['music21'], function() { 
                                   mp = new music21.miditools.MidiPlayer();
                                   mp.addPlayer('#midiPlayerDiv596'); 
                                   mp.base64Load('data:audio/midi;base64,TVRoZAAAAAYAAQABBABNVHJrAAAAVQD/AwAA4ABAAP9YBAMCGAiIAJA8WogAgDwAAJA+WoQAgD4AAJBBWoQAgEEAAJBDWoIAgEMAAJBFWoIAgEUAAJBDWoIAgEMAAJBCWoIAgEIAiAD/LwA='); 
                            });
                    </script>


Want to view the opening tone-row of Schoenberg's Fourth String quartet
as a matrix?

.. code:: python

    print (serial.rowToMatrix([2,1,9,10,5,3,4,0,8,7,6,11]) )


.. parsed-literal::
   :class: ipython-result

      0 11  7  8  3  1  2 10  6  5  4  9
      1  0  8  9  4  2  3 11  7  6  5 10
      5  4  0  1  8  6  7  3 11 10  9  2
      4  3 11  0  7  5  6  2 10  9  8  1
      9  8  4  5  0 10 11  7  3  2  1  6
     11 10  6  7  2  0  1  9  5  4  3  8
     10  9  5  6  1 11  0  8  4  3  2  7
      2  1  9 10  5  3  4  0  8  7  6 11
      6  5  1  2  9  7  8  4  0 11 10  3
      7  6  2  3 10  8  9  5  1  0 11  4
      8  7  3  4 11  9 10  6  2  1  0  5
      3  2 10 11  6  4  5  1  9  8  7  0
    


Get a quick graph showing how common various pitches are in a fourteenth
century piece:

.. code:: python

    dicant = corpus.parse('trecento/Fava_Dicant_nunc_iudei')
    dicant.plot('histogram')



.. image:: what_15_0.png


Add the note name in german to every note in Bach chorale, BWV295:

.. code:: python

    bwv295 = corpus.parse('bach/bwv295')
    bwv295 = bwv295.measures(0,6) #_DOCS_HIDE
    for thisNote in bwv295.recurse().notes:
      thisNote.addLyric(thisNote.pitch.german)
    bwv295.show()




.. image:: what_17_0.png



Prepare an incipit index (thematic catalog) of every Bach chorale that
is in 3/4: (we'll just look at the first 25 here)

.. code:: python

    catalog = stream.Opus()
    for work in corpus.chorales.Iterator(1, 26):
        firstTimeSignature = work.parts[0].getTimeSignatures()[0]
        if firstTimeSignature.ratioString == '3/4':
            incipit = work.measures(0,2)
            catalog.insert(0, incipit.implode())
    
    catalog.show()



.. image:: what_19_0.png



.. image:: what_19_1.png



.. image:: what_19_2.png


Advanced analysis tools are included. Want to know how unstable the
rhythmic profile of a piece is? Use Ani Patel's nPVI function on it:

.. code:: python

    s = corpus.parse('AlhambraReel')
    analysis.patel.nPVI(s.flat)




.. parsed-literal::
   :class: ipython-result

    5.755395683453239



Learning ``music21``
--------------------

``Music21`` can be simple to use but it is also extremely powerful. Like
all powerful software (Photoshop compared to MS Paint, AutoCAD, Excel),
there's a bit of a learning curve, especially for people who haven't
programmed before.

To use ``music21``, some familiarity with the "Python" programming
language is needed. Python is widely regarded as one of the easiest
languages to learn and is often taught as a first programming language.
You don't need to be a seasoned programmer; just a little bit of Python
and you will be able to get started and explore music in new ways with
``music21``.

Probably the hardest thing about ``music21`` is getting it installed and
writing the first line of code. The installation instructions at
:ref:`Installing music21 <usersGuide_01_installing>` will help you get
started, and then we can continue with the rest of the User's Guide.

If you need help at any time, there are always helpful ``music21``
fanatics at the mailing list,
http://groups.google.com/forum/#!forum/music21list/.

Continue on to :ref:`Installing music21 <usersGuide_01_installing>` or
learn more about
:ref:`who made the system and who supported it <about>`.