.. _what:

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

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 ``python3`` (or, better,
``ipython``) and load it by typing:

.. code:: ipython3

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

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



.. image:: what_6_0.png
   :width: 211px
   :height: 36px


Need a whole line of notes? Even easier:

.. code:: ipython3

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



.. image:: what_8_0.png
   :width: 371px
   :height: 49px


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

    littleMelody.show('midi')



.. raw:: html

    
    <div id="midiPlayerDiv213"></div>
    <link rel="stylesheet" href="https://cuthbertLab.github.io/music21j/css/m21.css">
    
    <script
    src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"
    ></script>
    
    <script>
    function midiPlayerDiv213_play() {
        const rq = require.config({
            paths: {
                'music21': 'https://cuthbertLab.github.io/music21j/releases/music21.debug',
            }
        });
        rq(['music21'], function(music21) {
            mp = new music21.miditools.MidiPlayer();
            mp.addPlayer("#midiPlayerDiv213");
            mp.base64Load("data:audio/midi;base64,TVRoZAAAAAYAAQACJ2BNVHJrAAAAFAD/UQMHoSAA/1gEAwIYCM5g/y8ATVRyawAAAE0A/wMAAOAAQM5gkDxazmCAPAAAkD5apzCAPgAAkEFapzCAQQAAkENak1iAQwAAkEVak1iARQAAkENak1iAQwAAkEJak1iAQgDOYP8vAA==");
        });
    }
    if (typeof require === 'undefined') {
        setTimeout(midiPlayerDiv213_play, 2000);
    } else {
        midiPlayerDiv213_play();
    }
    </script>


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

.. code:: ipython3

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

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

.. code:: ipython3

    dicant.measures(1, 10).show()



.. image:: what_15_0.png
   :width: 708px
   :height: 260px


This example, and many below, come from the ``music21`` built-in corpus
of thousands of pieces that come with the system to help you get started
right from the beginning. We believe in “Batteries Included” as a core
principle. So for instance, every Bach chorale is included, so that you
can do things like add the note name in german to every note in Bach
chorale, BWV295:

.. code:: ipython3

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



.. image:: what_17_0.png
   :width: 708px
   :height: 448px


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

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



.. image:: what_19_0.png
   :width: 708px
   :height: 284px



.. image:: what_19_1.png
   :width: 674px
   :height: 282px



.. image:: what_19_2.png
   :width: 674px
   :height: 270px



.. image:: what_19_3.png
   :width: 674px
   :height: 256px


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

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




.. 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, https://groups.google.com/g/music21list/.

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