music21 Documentation

`music21` was made possible by generous research funding
from the **Seaver Institute** and
the **National Endowment for the Humanities**/Digging into Data research fund.

In addition, we acknowledge previous support from `M.I.T.`_, the
`School of Humanities Arts and Social Sciences`_, and the
`Music and Theater Arts`_ section.

.. _M.I.T.: https://web.mit.edu/
.. _School of Humanities Arts and Social Sciences: https://shass.mit.edu/
.. _Music and Theater Arts: https://mta.mit.edu/

Colleagues and Institutions

Additionally, the following individuals have contributed materials or knowledge
to this project.  Their contributions and generosity are greatly appreciated.

* Thomas Bonte, Nicholas Froment, and Werner Schweer of `MuseScore`_ for their
   support and for their contributions to the open source music notation projects,
   including the Bach Goldberg Variations and the Handel Arias included.

* `Jacob Walls`_, contributed greatly to the type-safety, speed, and test coverage
   of `music21`.  If your music21 program "just works" without needing to guess what
   any argument goes where, Jacob is to thank.

* `Donald Byrd`_, researcher on University of Indiana who created
   a schema for computer-aided musicology (along with the source of all sorts of
   examples of how music notation is difficult).

* `Jack Campin`_ has kindly given permission to distribute his ABC editions of the Aird
  Collection, the Northumbrian Minstrelsy, and the Colonial and Civil War American
  Fife Music Collection.

* `John Chambers`_ has provided ABC editions to distribute with music21, including the
  Aird Collection, the O'Neill's Music of Ireland Collection, and Ryan's Mammoth Collection
  of fiddle tunes.

* `Laura E. Conrad`_ has kindly given permission to distribute her ABC editions of
  renaissance polyphony from Serpent Publications.

* `Ewa Dahlig-Turek`_ has kindly given permission to distribute the
   Essen folksong database with music21.

* `Margaret Greentree` kindly gave permission for distribution of her edited
   collection of the Bach chorales in MusicXML format as part of the music21 corpus.
   Her website contains all these chorales in additional formats.
   Any discoveries we make regarding these chorales are done in her memory.

* Bret Aarden for kindly contributing his conversions of Palestrina Mass corpus to `music21`.

* Walter B. Hewlett and Craig Sapp of Stanford's CCARH for support.

* `Justin London` compiled and maintained the list of Second-Viennese
   row forms that form the original backbone of serial.py.

* `McGill University`_ ELVIS project for including the MEI parser. Special thanks to Julie
   Cumming, Andrew Hankinson, Ichiro Fujinaga, and especially Christopher Antila for contributing.

* `Manuel Op de Coul`_ has kindly gave permission to use the Scala
   scale archive of nearly 4000 scales in music21.

* `Seymour Shlien`_ has kindly given permission to distribute his ABC
   encodings of the Essen folksong database with music21.

* `Bryen Travis`_ has kindly gave permission to use his collection of
   Bach MIDI data in `music21`.  It is no longer included in the Corpus, but we
   continue to thank him for his generosity.

* `Project Gutenberg`_ houses public domain music, including the quartets of Beethoven,
  Haydn, and Mozart, in musicxml format which we have been able to include in music21.

.. _Donald Byrd: https://web.archive.org/web/20220610200930/https://homes.luddy.indiana.edu/donbyrd/CMNExtremes.htm
.. _Jacob Walls: https://jacobtylerwalls.com/
.. _Laura E. Conrad: http://www.serpentpublications.org/drupal7/
.. _MuseScore: https://musescore.com/
.. _Bryen Travis: http://www.bachcentral.com/
.. _Ewa Dahlig-Turek: https://www.esac-data.org
.. _Seymour Shlien: https://ifdo.ca/~seymour/runabc/esac/esacdatabase.html
.. _Manuel Op de Coul: https://www.huygens-fokker.org/scala
.. _John Chambers: http://trillian.mit.edu/~jc/music/book
.. _Jack Campin: https://web.archive.org/web/20090226015201/http://www.campin.me.uk/
.. _McGill University: https://works.hcommons.org/records/c6ew2-tth07
.. _Project Gutenberg: https://www.gutenberg.org/browse/categories/4


How to Contribute
-----------------

We are always interested in working with interested musicologists,
programmers, psychologists, composers, game-designers,
performers, amateur music enthusiasts, etc.  In particular, we're interested
in hearing about how `music21` helped you
advance your work ... or in problems with `music21` itself or contributions you've made.

You can contact the larger `music21` community through the `music21 list`_.

.. _music21 list: https://groups.google.com/g/music21list

In particular, if you are interested in contributing documentation, tests,
or new features to music21, please contact the lead author on GitHub or through the
list.


Licensing and Copyright
---------------------------------

The `music21` Toolkit

The BSD-licensed `music21` software is distributed with a corpus of encoded
compositions which are distributed
with the permission of the encoders (and, where needed, the composers
or arrangers) and where permitted
under United States copyright law. Some encodings included in the corpus
may not be used for commercial uses
or have other restrictions: please see the licenses embedded in individual
compositions or directories for more details.

To the best of our knowledge, the music (if not the encodings)
in the corpus are either out of copyright
in the United States and/or are licensed for non-commercial use.  We also
aim to have all files out of copyright in the EU and Canada as well.
These works, along with any works linked
to in the virtual corpus, may or may not be free in your jurisdiction.
If you believe this message to be in
error regarding one or more works please contact Michael Cuthbert at
the address provided on the contact page.

---

### Documentation Source About Applications (`documentation/source/about/applications.rst`)

.. _applications:


Applications and Extensions of `music21`
=============================================

`Music21` has been used in numerous research tasks already, and will continue
to offer researchers many tools with which to explore new domains.


Papers, Presentations, and Publications
---------------------------------------------------

The following papers and publications make extensive use of `music21`. Start here:

Cuthbert, Michael Scott Cuthbert and Christopher Ariza. 2010. "`music21`: A
Toolkit for Computer-Aided Musicology and Symbolic Music Data." In
*Proceedings of the International Society for Music Information Retrieval*.
https://www.trecento.com/research/Cuthbert_Ariza_Music21_ISMIR_2010.pdf


Then continue with:

Church, Maura and Michael Scott Cuthbert. 2014. "Improving Rhythmic
Transcriptions via Probability Models Applied Post-OMR." In *Proceedings of the
International Society for Music Information Retrieval*.
https://www.trecento.com/research/Church_Cuthbert_OMR.pdf

Cuthbert, Michael Scott, Beth Hadley, Lars Johnson, and Christopher Reyes. 2012.
"Interoperable Digital Musicology Research via `music21` Web Applications."
From *Joint CLARIN-D/DARIAH Workshop at Digital Humanities Conference Hamburg*.
https://www.trecento.com/research/Cuthbert_Hadley_Johnson_Reyes_Music21_SOA.pdf

Cuthbert, Michael Scott, Chris Ariza, Jose Cabal-Ugaz, Beth Hadley, and Neena Parikh. 2011.
"Hidden Beyond MIDI’s Reach:Feature Extraction and Machine Learning with Rich Symbolic Formats
in `music21`" In *Proceedings of the Neural Information Processing Systems Conference*.
https://www.trecento.com/research/Cuthbert_Ariza_Cabal-Ugaz_Hadley_Parikh-Hidden-NIPS2011.pdf

Cuthbert, Michael Scott, Chris Ariza, and Lisa D. Friedland. 2011. "Feature Extraction and
Machine Learning on Symbolic Music using the `music21` Toolkit" In
*Proceedings of the International Symposium on Music Information Retrieval*
https://www.trecento.com/research/Cuthbert_Ariza_Friedland_Feature-Extraction_ISMIR_2011.pdf

Jordi Barthomé Guillen and Michael Scott Cuthbert. 2011. "Score Following from
Inaccurate Score and Audio Data using OMR and `music21`." In *Proceedings of the Neural
Information Processing Systems Conference (Music and Machine Learning, Workshop 4*.
https://www.trecento.com/research/Bartolome-Guillen_Cuthbert_ScoreFollower.pdf

Ariza, C. and Michael Scott Cuthbert. 2011. "The `music21` Stream: A New Object
Model for Representing, Filtering, and Transforming Symbolic Musical
Structures." In *Proceedings of the International Computer Music Conference*.
San Francisco: International Computer Music Association, pp. 61-68.
Available online at https://www.trecento.com/research/Ariza_Cuthbert_Stream_ICMC_2011.pdf

Ariza, C. and Michael Scott Cuthbert. 2011. "Analytical and Compositional
Applications of a Network-Based Scale Model in `music21`." In *Proceedings of the
International Computer Music Conference*. San Francisco: International Computer
Music Association, pp. 701-708. Available online at
https://www.trecento.com/research/Ariza_Cuthbert_Scale_ICMC_2011.pdf

Ariza, C. and Michael Scott Cuthbert. 2010. "Modeling Beats, Accents, Beams, and
Time Signatures Hierarchically with `music21` Meter Objects." In *Proceedings of the
International Computer Music Conference*. San Francisco: International Computer Music
Association. 216-223. Available online at
https://www.trecento.com/research/Ariza_Cuthbert_Meter_ICMC_2010.pdf

Future Goals and Potential Applications
---------------------------------------------------

There are numerous applications for music21 that we anticipate, yet simply have not had
time to implement. Consider taking on one of these projects, or write us with new and
interesting suggestions. To contact the authors, visit :ref:`about`.

- Piano-key-visualization

- Slonimsky scale types

- Automatic clarinet fingering generation via ClarFinger font (link: www.trecento.com/fonts/)

- Automatic string fingerings.

- Indian Raga encoding: including ascending, descending, and typical presentations,
  microtonal inflections, common associations, historical context.

- Multiple-simultaneous-tempi to a single tempo conversion (via tuplets).

- Palestrina counterpoint generation (via algorithms of Mary Farbood and others.).

- Beneventan chant similarity indices (thanks to the work of Thomas Forrest Kelly and the
  Exultet encodings made available in `**kern` by Elsa De Luca).

- Identify potential clefs for fragmentary Renaissance and Medieval pieces that are
  missing their clefs. (Use their staff-lines and minimizing number of melodic and
  harmonic tritones).

---

### Documentation Source About Faq (`documentation/source/about/faq.rst`)

.. _faq:

Frequently Asked Questions
==========================

General
-----------

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 https://groups.google.com/g/music21list or post an issue on
    `GitHub <https://github.com/cuthbertLab/music21/issues>`__.
    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 originally created
    while Cuthbert was a professor at MIT
    in the Music and Theater Arts Section there.  At MIT, everything
    has a number, and the department number for music is 21M.  It seemed like
    a nice way to honor where initial support came from, while not tying it
    to one institution.

    (btw: 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.)

So is this a `MUSIC-N` software?

    There was a tradition early on of naming software that dealt with
    music, with "MUSIC" followed by a number (https://en.wikipedia.org/wiki/MUSIC-N).      
    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: https://pypi.org/project/music22

    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, :meth:`~music21.stream.Stream.setupSerializationScaffold` and
      :meth:`~music21.stream.Stream.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 https://docs.python.org/dev/library/plistlib.html
      or https://code.activestate.com:443/recipes/440595. 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. (We might try to use MNX soon as it's stable.)

I'm ready to give it a try, but how do I install `music21`?

    Please see the complete install instructions: 
    :ref:`User's Guide, Chapter 1: Installing music21 <usersGuide_01_installing>`.

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 help to
    Mac and Windows installation. Most AI agents can help you nowadays, however.

Recurring misunderstandings
----------------------------
When I call `.transpose(i)` where `i` is an integer, the enharmonics are wrong, even if `i == 0`.

    Transposing by a number is equivalent to creating an :class:`music21.interval.ChromaticInterval`
    object.  ChromaticIntervals are designed *not* to care about enharmonics.  When transposing
    by a chromatic interval, `music21` will freely change the enharmonic to whatever it feels is
    best in context (maybe right, maybe wrong).

    If you care about enharmonics (I do!) use a string representing a
    :class:`music21.interval.DiatonicInterval`, such as "P8" for up a perfect octave, or
    "m-3" for down a minor third.  Unless the interval causes the note to have quintuple sharps
    or flats (which `music21` does not support), it will always honor your enharmonic.

When I call `.show()` something doesn't work.  Here's my code: `...Score...Measure...Notes`:

    Much of `music21` will work no matter what your Stream structure is, but for certain
    analyses or writing out to formats (including MusicXML), your stream structure needs to
    be well formed.  That is, Scores must contain Parts which must contain Measures.
    Measures can optionally contain Voices.  Only Measures and Voices can contain notes.

    To check if you've done it right call `isWellFormedNotation()` on your stream.  If it
    returns False, try something else.


Uses
---------
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.  (Download it only from its GitHub page,
    https://github.com/Audiveris/audiveris/releases -- other sites offering
    Audiveris downloads are often scams or carry malware.)
    The development team here has had good experience
    with the commercial SmartScore application.  `Music21` does have a
    set of modules for improving the output of OMR after it's done.
    See :ref:`moduleOmrCorrectors`.

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,
    `s.show('midi')`.

    By the way: MuseScore and other software generally do a better job of reading
    performed MIDI files than `music21` does, so for complex tasks, we often
    recommend converting to MusicXML with other software first, and then loading
    those XML files into music21 instead.


Feature requests
-------------------------------
`Music21` doesn't have some feature that I need, how do I get it added?

    You can put a request as an "Issue" on
    `GitHub <https://github.com/cuthbertLab/music21/issues>`__
    (just report it as a request, not a bug).
    In general though, the core team has a priority list based on what we think the widest
    audience is needing (or what we need for our own research), so please don't be surprised if
    no `music21` core devs have time to implement it.
    You can also rally support on the mailing list and hope for an angel programmer to help there.

No, you don't understand, I **really** need this feature!

    The `music21` project does not offer paid consulting.
    But if you really need something done in `music21`, there are people who do `music21` work
    on paid consulting contracts. Often even the main developer wearing a separate hat.
    But be kind, only contact devs if you are willing
    to actually pay consulting rates. (Otherwise, it means you
    don't *really* need the feature.)
    
Is this also what I should do if I need help integrating or using `music21` in my own project?

    Yes, if you're having trouble getting `music21` to do what you want and you've
    tried the mailing list/Agents/StackOverflow, etc. there are often people on the
    music21list who are open to doing work for hire in that realm.


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:

    * https://www.musicxml.com/

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:

    * https://www.humdrum.org
    * https://kern.humdrum.org

---

### Documentation Source About Index (`documentation/source/about/index.rst`)

About `music21`
===============

.. toctree::
   :maxdepth: 1

   what
   about
   applications
   faq
   migratingToV11
   referenceCorpus

---

### Documentation Source About MigratingToV11 (`documentation/source/about/migratingToV11.rst`)

.. _migratingToV11:

Migrating to music21 v11
========================

*(This is an in-progress guide that was automatically generated by Myke's AI Agent.)*

What changed between the v10 line and v11, and what to use instead.  The big, code-breaking items come first, then smaller
improvements by area, then one table of everything removed or deprecated.


Python 3.12 or newer
--------------------

Python 3.11 support is gone; 3.12, 3.13, and 3.14 are tested.  The payoff is
real generics: ``Stream`` and its iterators use the PEP 695 bracket form, so a
type checker can follow ``stream.Stream[note.Note]()`` all the way to
``for n in s: n.pitch``.


Octaves are always integers
---------------------------

**In one line:** ``octave`` is always an ``int``, and ``octaveIsImplicit`` says whether you gave one.

Before v11, ``pitch.Pitch('F#').octave`` was ``None``: a lovely idea (an
F-sharp in *any* octave) that crashed the moment someone wrote
``p.octave + 1``.  The pitch knew all along which octave it would use for
MIDI or a staff.  It kept that in ``implicitOctave``, a property that nobody
remembered.  Now ``octave`` does that job itself:

>>> from music21 import *
>>> anyFSharp = pitch.Pitch('F#')
>>> anyFSharp.octave
4
>>> anyFSharp.octaveIsImplicit
True

Nothing else about an octave-less pitch changes.  It still prints without a
number, transposes without one, and is not equal to an explicit F#4:

>>> anyFSharp
<music21.pitch.Pitch F#>
>>> anyFSharp.transpose('P8')
<music21.pitch.Pitch F#>
>>> anyFSharp == pitch.Pitch('F#4')
False

Give it an octave and the flag flips:

>>> anyFSharp.octave = 5
>>> anyFSharp.octaveIsImplicit
False
>>> anyFSharp
<music21.pitch.Pitch F#5>

Notes follow along: ``note.Note('B-').octave`` is ``4``, and the flag lives
on the note's pitch, ``n.pitch.octaveIsImplicit``.

.. list-table::
   :header-rows: 1
   :widths: 50 50

   * - Before v11
     - v11
   * - ``if p.octave is None:``
     - ``if p.octaveIsImplicit:``
   * - ``p.octave = None``
     - ``p.octaveIsImplicit = True``  (the old spelling is deprecated; removed in v13)
   * - ``p.implicitOctave``
     - ``p.octave``
   * - ``if p.octave is None: p.octave = p.implicitOctave``
     - ``p.octaveIsImplicit = False``
   * - ``octave: int | None``
     - ``octave: int``

``p.octave + 1`` and ``f'{p.name}{p.octave}'`` no longer crash.  The few
methods that need a pitch's *own* octave, such as
:meth:`~music21.pitch.Pitch.transposeAboveTarget`, still raise for an
implicit one; set ``.octave`` first.  ``implicitOctave`` stays as a synonym
so nothing breaks today, but it is deprecated and starts warning in v12.


KeySignature.sharps is always an int
------------------------------------

Similar idea to Octave.  ``KeySignature.sharps`` (and ``Key.sharps``) is an
``int`` you can add to and subtract from.  A non-traditional signature is a
flag plus a list of pitches.  ``sharps=None`` still works but warns:

>>> unusual = key.KeySignature()
>>> unusual.isNonTraditional = True
>>> unusual.alteredPitches = ['E-', 'G#4']
>>> unusual
<music21.key.KeySignature of pitches: [E-, G#4]>


Chord indexing gets simpler
---------------------------

``c[1]``, ``c['G4']`` and ``c[somePitch]`` still return the chord's
:class:`~music21.note.Note`; everything fancier is gone.  Attribute paths
such as ``c['2.tie']`` and ``c['D-4.style.color']`` no longer work, a Note is
no longer accepted as a key (use its pitch), and the per-note getters and
setters (``getTie``, ``setColor``, ``getNotehead``, and their siblings) are
deprecated.  Index, then use the Note:

>>> c = chord.Chord('C4 E4 G4')
>>> c['E4'].tie = tie.Tie('start')
>>> c[1].tie
<music21.tie.Tie start>


VoiceLeadingQuartet needs its four notes
----------------------------------------

``voiceLeading.VoiceLeadingQuartet(v1n1, v1n2, v2n1, v2n2)`` requires all
four notes up front, the first Music21Object ever to insist on arguments.  In
return they are always Notes, never ``None``.  ``analyticKey`` is now
``key``, ``vIntervals`` and ``hIntervals`` are tuples, and two dogmatic names
got truer ones: ``opensIncorrectly()`` is ``not modalOpening()`` and
``closesIncorrectly()`` is ``not clausulaVera()``.


Roman numerals
--------------

* ``romanNumeralFromChord`` keeps the sharp on major-quality chords built on
  the raised sixth and seventh degrees in minor: ``#VI``, not ``VI#63``.
  ``correctRNAlterationForMinor`` gained a ``chordHasMajorThird`` keyword for
  the same reason.
* Figures containing ``x``, ``y`` or ``z`` raise.  ``RomanNumeral('IIIx')``
  used to be a III13 chord by accident.
* ``FigureTuple`` and ``PitchFigureTuple`` are typed NamedTuples, and
  ``FigureTuple.fromPitchAndReference()`` replaces ``figureTupleSolo``.


Durations and sorting
---------------------

* Two Durations with ``expressionIsInferred`` True are equal when their
  quarterLengths match; type, dots and tuplets are free to be re-expressed.
* ``sorting.SortTuple`` is a modern NamedTuple.  ``priority`` and
  ``classSortOrder`` may be floats, and ``modify()`` with a bad field name
  raises ``ValueError``.
* tinyNotation's undocumented ``0`` duration (a whole bar plus a fermata) is
  deprecated.


Streams
-------

* New ``Stream.isAtEnd(el)`` says whether ``storeAtEnd`` put ``el`` there.
* ``Stream.hasElement(el)`` is removed: write ``el in s``.
  ``hasElementOfClass`` is deprecated: write ``if s.getElementsByClass(X):``.


Pitches
-------

``pitch.simplifyMultipleEnharmonics`` takes ``criterion`` and ``keyContext``
as keyword-only arguments.


File formats
------------

* **ABC**: ``w:`` lyric lines are imported, with hyphenation and ``*`` skips.
  ``abcToStreamOpus`` always returns an Opus.
* **Humdrum**: grace notes keep their written duration instead of becoming
  eighths; duration parsing lives in a new ``hdStringToDuration``; a token
  with no duration warns when a quarter is assumed; ``GlobalReference`` is no
  longer a Music21Object.
* **LilyPond**: output targets current LilyPond (``\tuplet``, modern barline
  names, ``\markuplist``), and every ``stringOutput()`` returns a ``str``.
* **MIDI**: ``midiEventsToInstrument`` is removed; use
  ``midiEventToInstrument``.
* **Vexflow**: the ``music21.vexflow`` module is gone.  It had not worked in
  a decade; music21j is the way to draw in a browser.
* **configure**: choosing MuseScore as the MusicXML reader also sets
  ``musescoreDirectPNGPath``.


figuredBass, features, tree
---------------------------

* figuredBass: ``hiddenFifth`` and ``hiddenOctave`` are now ``hiddenFifths``
  and ``hiddenOctaves``, matching ``parallelFifths``.  ``FiguredBassScale``'s
  first argument is ``scaleTonic``, not ``scaleValue``.  Rests inside a
  possibility are typed sentinels rather than the string ``'RT'``.
* features: ``Feature.vector`` starts as ``[]`` rather than ``None``, and
  ``FeatureExtractor.dimensions`` defaults to 1.
* tree: ``ElementTimespan`` and ``PitchedTimespan`` take their arguments in
  the same order as ``Timespan``; ``offset``, ``endTime`` and ``element`` are
  required.


For developers
--------------

* Type annotations across nearly the whole library, with ``t.cast()`` for
  narrowing and ``@property`` decorators throughout.
* ``common.enums.ContainsEnum`` is not needed: Python 3.12's ``StrEnum``
  suffices, or ``HexEnum`` for hex values such as MIDI.  The alias leaves in
  v12.  ``common.defaultlist`` is deprecated.
* The test runners import modules the normal way, so a module's tests no
  longer need ``from music21.key import KeySignature`` to compare types.
* AI agents get their own instructions, skills and shared memory in
  ``AGENTS.md`` and ``.agents/``.


Removed and deprecated
----------------------

.. list-table:: Removed in v11
   :header-rows: 1
   :widths: 50 50

   * - Gone
     - Use instead
   * - Python 3.11
     - Python 3.12 or newer
   * - ``music21.vexflow``
     - music21j
   * - ``midi.translate.midiEventsToInstrument``
     - ``midiEventToInstrument``
   * - ``Stream.hasElement(el)``
     - ``el in s``
   * - ``musicxml.xmlToM21.MusicXMLImporter.identificationToMetadata``
     - ``addIdentificationToMetadata``
   * - a string for ``musicxml.xmlToM21.MeasureParser.getStaffNumber``
     - an ``int``
   * - ``VoiceLeadingQuartet.unison`` / ``.fifth`` / ``.octave``
     - ``interval.Interval('P1')`` and friends
   * - ``c['2.tie']`` attribute paths into a Chord
     - ``c[2].tie``
   * - a Note as a Chord index, ``c[someNote]``
     - ``c[someNote.pitch]``

.. list-table:: Deprecated in v11 (removed in v12 unless noted)
   :header-rows: 1
   :widths: 50 50

   * - Deprecated
     - Use instead
   * - ``Stream.hasElementOfClass(X)``
     - ``if s.getElementsByClass(X):``
   * - ``Chord.getTie``, ``setTie``, ``getColor``, ``setColor``,
       ``getNotehead``, ``setNotehead``, ``getNoteheadFill``,
       ``setNoteheadFill``, ``getStemDirection``, ``setStemDirection``
     - ``c[i].tie``, ``c[i].style.color``, ``c[i].notehead``,
       ``c[i].noteheadFill``, ``c[i].stemDirection``
   * - ``roman.figureTupleSolo``
     - ``FigureTuple.fromPitchAndReference()``
   * - ``VoiceLeadingQuartet.opensIncorrectly()`` / ``closesIncorrectly()``
     - ``not modalOpening()`` / ``not clausulaVera()``
   * - ``KeySignature(sharps=None)``
     - ``ks.isNonTraditional = True``
   * - ``variant.addVariant(replacementDuration=...)``
     - ``replacementQuarterLength=...``
   * - ``common.defaultlist``
     - a ``list`` or a ``dict``
   * - ``common.enums.ContainsEnum``
     - not needed: ``enum.StrEnum`` suffices, or ``HexEnum`` for hex values such as MIDI
   * - tinyNotation ``0`` duration
     - the duration plus an ``expressions.Fermata``
   * - ``Pitch.implicitOctave``
     - ``Pitch.octave``  (warns from v12, removed later)

---

### Documentation Source DeveloperReference BuildingDocumentation (`documentation/source/developerReference/buildingDocumentation.rst`)

.. _buildingDocumentation:


Building Documentation
==================================

Creating or updating the music21 documentation requires a
few additional programs to be installed,
most importantly one called Sphinx. Sphinx is a documentation generator that uses
reStructuredText (rst) as its markup language and outputs HTML documents.

In addition, you will need a copy of the git repository
(https://github.com/cuthbertLab/music21).


**1) Install uv and run uv sync**

Get uv at https://docs.astral.sh/uv/ and then, in the music21 directory, run `uv sync`.
This installs Sphinx, Jupyter, and nbconvert, which turns the Jupyter notebooks
used in the tutorials and User's Guide into .rst files.

**2) Install pandoc**

Pandoc is a universal documentation converter that we use (nbconvert needs it).
You can get pandoc at: https://pandoc.org/installing.html

Note that pandoc 1.14-1.15.0 do not work.  1.15.1 and newer are recommended.

**3) Run documentation/make.py**

From the music21 directory run `uv run documentation/make.py`, which will automatically
build all the music modules in
music21 into the "autogenerated" folder and from there into the "build/html" folder.
It should also open your web browser automatically.

The first time you build the documentation, it'll take a long time.  Subsequent
builds, however, only build the parts that have changed.  If you need to build from
scratch, run `uv run documentation/make.py clean` and you will have a clean directory to
build again.

---

### Documentation Source DeveloperReference Documenting (`documentation/source/developerReference/documenting.rst`)

.. _documenting:


Documenting `music21`
=============================================

`Music21`'s documentation system uses a combination of a few handwritten documentation pages (like this one),
a lot of Jupyter notebooks (mainly in the User's Guide sections),
and documentation automatically generated from the documentation found in modules (in moduleReference).

The handwritten pages and Jupyter notebooks are found in the `/documentation/source/` directories.  The
automatically generated documentation is found in each `.py` module.

To build `music21` documentation, go to the `/documentation/` folder and run::

   python3 make.py

(At present, only MIT affiliates can run the `upload.py` script.)


.rst format files
----------------------------------------------
The handwritten .rst files are written using the reStructuredText_ format,
which is a pretty simple way of defining structure of documents with things such as hyperlinks, emphasis,
etc.  It is somewhat similar to Markdown format.   These files should *not* contain code examples, since
they will not be tested. (You may find some older files that do contain code; we should be translating these
in the future).

.. _reStructuredText: https://docutils.sourceforge.io/rst.html

These files get converted to .html when you run `/documentation/make.py` so long as the excellent module
Sphinx_ has been installed.

.. _Sphinx: https://www.sphinx-doc.org/en/master

You can also edit these .rst files directly in Jupyter notebook, which will make them show the
layout as well.


Jupyter Notebook (.ipynb) files
-------------------------------------------
Since 2013, the majority of new documentation should be written in Jupyter Notebook (formerly
IPython Notebook) format.  These files should never be edited directly, but instead should be
edited using Jupyter Notebook running Python 3.7 or higher.

A lot of the music21 documentation is automatically generated from the documentation strings
found in music21 modules.  We strongly encourage other module
writers to create documentation that works
the same way.  In fact, we won't add your module to the music21 repository without documentation
in this form -- there's a test that ensures that code coverage increases with each build -- but
we'll help you learn the ropes.  This doc explains some of the main features (and potential Gotchas!)
of our automatic documentation system.

`uv sync` in the music21 directory installs Jupyter. Run it from the music21 directory with::

    uv run jupyter notebook

When editing examples with code be sure, at least the first time, to run each code excerpt individually
and pay attention to changes in output and unexpected errors.



Documenting modules and classes
=================================

music21 documentation for modules is found inside the module itself, at the very top and before the import statements.
This module-level documentation, usually in triple-quoted strings, might look like this::

    '''
    I am documentation for this module!
    '''

The buildDoc/build.py script creates RST files for modules, which are processed
by Sphinx.   Place all documentation for public modules, module-level
functions, classes, and class-level attributes, properties, and methods
as close to the relevant code as possible.

If you're going to edit docs you'll need Sphinx, which `uv sync` installs.

Sphinx uses special characters to identify formatting styles in documentation.
Helpful tips on Sphinx formatting may be found here:  `Sphinx Cheat Sheet <https://matplotlib.org/sampledoc/cheatsheet.html>`_

For example, the heading of this section was created by writing::

    Documenting modules and classes
    ===============================

To write boldface you would write::

    **This is bold**

The documentation looks like this:
**This is bold**

To italicize, you would write::

    *This is italics*

The documentation looks like this:
*This is italics*

This is a one-line code sample::

    ``print variableName``

The documentation looks like this:
``print variableName``

You may also use links in your documentation. For example, if in one method you'd like to link to
another method's documentation, write::

    :meth:`~music21.note.GeneralNote.addLyric`

The documentation looks like this:
:meth:`~music21.note.GeneralNote.addLyric`

Or to link to another class, write::

    :class:`~music21.note.Note`

The documentation looks like this: :class:`~music21.note.Note`

Sometimes pictures are useful to visually describe code to readers or to show the results of a .show() method call, etc.
This is easy with sphinx. Just copy and paste the picture you'd like to use into the buildDoc/rst/images folder,
and reference it in your documentation like this::

    .. image:: images/completebach.*
        :width: 300

The documentation looks like this:

.. image:: images/completebach.*
    :width: 300

Finally, if there is a section of your documentation that you'd rather Sphinx
not format at all, append two colons to the last line of formatted text,
followed by a space, followed by the *indented* text block, followed by a
space. Text written after this space will be formatted. This is useful for
block-quoting example code. For example, in your code write::

    ...blah blah blah this text is formatted. Now I want to block-quote
    some example code, so I put two colons::

        this text IS NOT formatted
        it must be indented

        line breaks AND spacing will be preserved
        **bold** sphinx formatting unobserved

    Now I am back to Sphinx formatting, outside the block. **now this is bold!**

The documentation looks like this:

...blah blah blah this text is formatted. Now I want to block-quote
some example code, so I put two colons::

    this text IS NOT formatted
    it must be indented

    line breaks AND spacing will be preserved
    **bold** sphinx formatting unobserved

Now I am back to Sphinx formatting, outside the block. **now this is bold!**


Displaying only some of the test code in the documentation
----------------------------------------------------------

We use doctests a lot in music21 -- if you run /music21/test/test.py, it will
run not only all the code in class Test() but also all the code in the
documentation preceded by '>>>' marks.  This way our documentation and our
test code doesn't get out of sync with each other.  Pretty cool, eh?

Here's the thing: good programming means that you test as much as possible in
the code, but good documentation means showing enough example code that the
readers get it, but not so much that they want to claw out their own eyeballs.
So how to proceed?  Simply add the line "OMIT_FROM_Docs"  in ALL CAPS
instead of lowercase. (I can't write it in all caps here or nothing else will display!)

Anything after that line in your documentation code won't display.  For instance,
say we wanted to demonstrate the difference between note.name and note.step, but also wanted
to test to make sure that flats and sharps both were equally eliminated.  We
could write documentation/test-code like this (but with all caps)

::

   '''
   >>> from music21 import *
   >>> c1 = note.Note('C#')
   >>> c1.step
   'C'

   OMIT_FROM_Docs

   (N.B. That should be capital DOCS above...)

   >>> c2 = note.Note('C-')
   >>> c2.step
   'C'
   '''

and what you'll get in your documentation is:

::

   >>> from music21 import *
   >>> c1 = note.Note('C#')
   >>> c1.step
   'C'

Lines can be omitted on an individual basis by adding the expression
"#_DOCS_Hide" (again in all caps) somewhere on the line.  On the other hand, the text
"#_DOCS_Show" (again in all caps) is removed from any line before it appears in the
documentation.  So you could use some of the same lines to test
code and also to give an example like so::

   >>> d1 = note.Note("D-")
   >>> assert(d1.name == 'D-')  #_DOCS_Hide
   >>> #_DOCS_Show d1.show('lily.png')

in this case, the assertion code is omitted from the documentation
generated from the module, while the lilypond file is not generated
during doctests.  It will look to your users like:

::

   >>> d1 = note.Note("D-")
   >>> d1.show('lily.png')


Together with OMIT_FROM_Docs, it's a great way to
have your cake and eat it too. (remember that these need to be in all caps)

Ordering Module-Level Class Names and Module-Level Functions
-----------------------------------------------------------------------------

Classes are by default presented in the order in which they appear in the module. Module-level functions
are by default sorted alphabetically. If that's not what you want, then create a list called `_DOC_ORDER`
which is a list of the class and/or function names in the module. These values are given as evaluated names, not strings.

Since this list uses classes and not strings, this list must come at the end of the module, after the Test classes
and before calling `music21.mainTest()`

At the end of note.py for instance, we write::

    _DOC_ORDER = [Note, Rest]

    if __name__ == "__main__":
        music21.mainTest(Test)


Ordering Class-Level Names
------------------------------------------------------

Classes can define a `_DOC_ORDER` attribute which functions the same as the module-level
`_DOC_ORDER`, that is it defines the order of attributes, properties, and/or methods in the class.

Unlike for top-level names, these values are given as **strings**, not evaluated names.
The `_DOC_ORDER` attribute must be defined outside of the `__init__()` method to ensure that
these values can be read from a Class object and not just instances.

The following abbreviated example is from pitch.py::

    class Pitch(music21.Music21Object):
        '''Class doc strings.
        '''
        # define order to present names in documentation; use strings
        _DOC_ORDER = ['name', 'nameWithOctave', 'step', 'pitchClass', 'octave', 'midi']

        def __init__(self, name=None):
            pass

Documenting Class-Level Properties
---------------------------------------------------

To document a property do something like this:

::

    def _getName(self):
       return self._storedName

    def _setName(self, newName):
       if newName == 'Cuthbert':
           raise ValueError("what a dumb name!")
       else:
           self._storedName = newName

    name = property(_getName, _setName, doc = '''
          The name property stores a name for the object
          unless the name is something truly idiotic.
          '''

Documenting Class-Level Attributes
--------------------------------------------------------------

Class-level attributes, names that are neither properties not methods,
can place their documentation in a dictionary called `_DOC_ATTR`.  The keys of the dictionary
are strings (not evaluated names) corresponding to the name of the attribute, and the value
is the documentation.

Like `_DOC_ORDER`, don't put this in `__init__()`.

Here's an example from note.py::

    class Note(NotRest):
        '''
        Class doc string goes here.
        '''
        isNote = True
        isRest = False

        # define order to present names in documentation; use strings
        _DOC_ORDER = ['duration', 'quarterLength', 'nameWithOctave', 'pitchClass']

        # documentation for all attributes (that are not properties or methods)
        _DOC_ATTR = {
        'isNote': 'Boolean read-only value describing if this object is a Note.',
        'isRest': 'Boolean read-only value describing if this is a Rest.',
        'beams': 'A :class:`music21.note.Beams` object.',
        'pitch': 'A :class:`music21.pitch.Pitch` object.',
        }

        def __init__(self, *arguments, **keywords):
            pass

If a `_DOC_ATTR` attribute is not defined, the most-recently inherited `_DOC_ATTR`
attribute will be used.  To explicitly merge an inherited `_DOC_ATTR` attribute with
a locally defined `_DOC_ATTR`, use the dictionary's `update()` method.

The following abbreviated example, showing the updating of the `_DOC_ATTR` inherited from NotRest,
is from chord.py::

    class Chord(note.NotRest):
        '''
        Class doc strings.
        '''
        isChord = True
        isNote = False
        isRest = False

        # define order to present names in documentation; use strings
        _DOC_ORDER = ['pitches']
        # documentation for all attributes (not properties or methods)
        _DOC_ATTR = {
        'isNote': 'Boolean read-only value describing if this object is a Chord.',
        'isRest': 'Boolean read-only value describing if this is a Rest.',
        'beams': 'A :class:`music21.note.Beams` object.',
        }
        # update inherited _DOC_ATTR dictionary
        _DOC_ATTR.update(note.NotRest._DOC_ATTR)

        def __init__(self, notes = [], **keywords):
            pass

However, you will rarely need to do this, since the documentation will point to
the inherited docs automatically.

Documenting Class-Level Methods
-----------------------------------------------------------------

This is the most common type of documentation, and it ensures both excellent
documentation and doctests. A typical example of source code might look like this::

    class ClassName(base.Music21Object):

        [instance variables, __init__, etc.]

        def myNewMethod(self,parameters):
            '''
            This is documentation for this method

            >>> myInstance = ClassName()
            >>> myInstance.myNewMethod(someParameters)
            >>> myUnicorn.someInstanceVariable
            'value'
            '''
            [method code]

---

### Documentation Source DeveloperReference Index (`documentation/source/developerReference/index.rst`)

Developer Reference
===================

..  toctree::
    :maxdepth: 2

    developerGuidelines
    testing
    documenting
    buildingDocumentation
    releasing
    installJupyter

    usingGit
    musicxmlTest
    
    startingOver

---

### Documentation Source DeveloperReference Releasing (`documentation/source/developerReference/releasing.rst`)

.. _releasing:

Releasing a New Version
=======================

The steps for releasing a new version of `music21` are in
`RELEASING.md <https://github.com/cuthbertLab/music21/blob/master/RELEASING.md>`_.

---

### Documentation Source DeveloperReference UsingGit (`documentation/source/developerReference/usingGit.rst`)

.. _usingGit:

Using `music21` with Git
======================================

`Music21` stores its master code base in the Git code format at the GitHub
website (`https://github.com/cuthbertLab/music21 <https://github.com/cuthbertLab/music21>`_ ).
In order to have the latest, unreleased, versions of `music21`, which often incorporate new
bug fixes, users will need to be familiar with Git.

**IMPORTANT: BEFORE BEGINNING, UNINSTALL ALL EXISTING VERSIONS OF `music21`.
ADDITIONAL VERSIONS OF MUSIC21 INSTALLED IN OTHER LOCATIONS CAN CAUSE DIRECTORY
ROUTING PROBLEMS.**


Installing Git
--------------

First, make sure you have Git installed. You can find binaries for Windows, OSX
and Unix at `https://git-scm.com/ <https://git-scm.com/>`_.

But the best way to do almost everything with Git and `music21` today is with the
GitHub Desktop app, at `https://desktop.github.com <https://desktop.github.com>`.


Install PyCharm
------------------

Developers of `music21` who want access to support or committing
to the code base need to
use an IDE called PyCharm, which allows for easy debugging and
enforcing of coding standards
such as consistent whitespace, no unused variable names, and
simple error catching. Thus, while
PyCharm is not strictly necessary to editing the Python
files that make up `music21`, it is the
only supported environment for receiving technical assistance.
Thus students and others who
wish to be part of the development team for `music21` will
need to follow the instructions below
on using Git for PyCharm.


Forking music21 on GitHub
-------------------------

The main development paradigm in Git is to create a "Fork" or individualized
copy of the music21 code base under your own name and make modifications there.
You may "Pull" changes that we have made to the main music21 version into your
own fork so that your fork stays up to date.  If you'd like to contribute your
changes back to the main codebase, you will initiate something called a "pull
request" later.

To fork the official music21 repository, simply navigate to
`https://github.com/cuthbertLab/music21
<https://github.com/cuthbertLab/music21>`_ on GitHub while signed in to your
GitHub account, and click **Fork** in the upper right-hand corner of the page.

..  image:: images/usingGit/github__forking__01.png



Committing, pushing and pulling
-------------------------------

This used to be really hard...now look at the instructions
for the **Github Desktop** app.


Sending pull requests to the official `music21` repository
-------------------------------------------------------------

To get your changes into the official `music21` repository, you'll have to make a
**pull request** via the GitHub **web site** or the desktop app.

A **pull request** is just what it sounds like:
a request to another repository (the music21 team's copy) for them
to pull in changes from your repository and add them to the centralized version.

Making pull requests is easy:

1.  Log into GitHub and find your fork of music21. Under the repository summary
    header you'll see a green button with two arrows, labeled "Compare &
    review".

    Click that button:

    ..  image:: images/usingGit/github__pull_requests__1.png

2.  If your repository differs from the official `music21` repository, you'll be
    shown the diff stats, as well as a large banner with the text ``Click to
    create a pull request for this comparison``.

    Click on that banner to continue:

    ..  image:: images/usingGit/github__pull_requests__2.png

3.  Almost done. Now you can write a description of what your pull request
    involves. While the `music21` team can and will review the diffs for your
    request, please provide a useful description. What do your changes
    accomplish?  Do they address one of the issues in the official issue
    tracker? Which issue?  Do they represent an enhancement, or new
    functionality?

    When you've finished writing your description, click on the ``Send pull
    request`` button. You've sent your pull request!

    ..  image:: images/usingGit/github__pull_requests__3.png


Getting your pull requests accepted
------------------------------------

Once you've sent a pull request to the `music21` team they'll need to review the
changes you've suggested.  They can opt to accept some, all or none of the
commits you've included in your pull request. If the work looks good, they'll
merge your changes into the official repository.

What do we mean by the "if the work looks good"? The first and highest priority
is that if the code expands `music21` in any way that it is well documented
(see :ref:`documenting`) and includes tests that ensure that future changes to
the system will not break the code.  You will need to run test/multiprocessTest.py
which will update the file test/lastResults.txt to show that the tests have passed.
To run these tests you will need to install the optional modules such as NumPy,
matplotlib, etc. The tests you have written cannot add appreciatively to the amount
of time it takes to run the test suite (so a few milliseconds for a tiny addition, at
most a second or two for a major contribution).  The code needs to be well placed
within the structure of the library so as not to add unneeded complexity. For instance,
if your new methods will only apply to a small number of users working on a constrained
repertory (such as chorales, jazz, medieval music, etc.) it should not add ten new methods
to Note or Stream. The contributions cannot require any new external dependencies and
even optional dependencies should be discussed with the music21 team before attempting
a Pull Request.  The code should work on Mac, Windows (watch out for file system calls),
and Unix equally well.  It sounds hard, but after a while looking out for these caveats
becomes second nature and will help ensure the toolkit is viable for at least a decade
to come.

---

### Documentation Source Installing Index (`documentation/source/installing/index.rst`)

Installation
============

.. toctree::
   :maxdepth: 1

   installMac
   installWindows
   installLinux
   installAdditional

---

### Documentation Source Installing InstallAdditional (`documentation/source/installing/installAdditional.rst`)

.. _installAdditional:


Extending `music21` with Additional Software
=======================================================

Installing Additional Software Components
-----------------------------------------------

Additional functionality of `music21` is available with the
installation of numerous helper applications. While not essential
for all applications, these tools will aid in working with `music21`.



MuseScore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MuseScore offers a free, full-featured, cross-platform (Windows, Mac OS, Ubuntu,
Debian, and Fedora) application for viewing and editing music notation.
MuseScore can import and export MusicXML, and provides an excellent way to view,
edit, and export musical data for working in `music21`.
Downloading MuseScore (version 2 or higher)
is highly recommended for working with `music21`.

https://musescore.org/en



Lilypond
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lilypond is a free, open-source music display program that can produce
beautiful scores.  `Music21` can generate PDF or PNG (like JPG) files
automatically if Lilypond is installed on your system.  Download it at:

http://lilypond.org/



Installing Additional Python Modules
-----------------------------------------------

`Music21` can do more things, such as plotting graphs, if you
install additional Python libraries.

The following topics cover additional software used by `music21`.
For each library, visit the websites listed below, download the
additional python libraries, and install them just as you did with
`music21` (with `uv add`, in your `m21play` folder, or whatever you named it).
If you don't feel like installing them now, no worries: you can always install them later.

It's best not to install these until you have `music21` working without
additional modules.

Note: as of `music21` v.6, some of these additional modules are bundled
with `music21`.


Matplotlib

*(included with music21 by default)*

Numeric extensions to Python.  Included with Matplotlib.

In your `m21play` folder, run::

    uv add numpy

and you should be set.



scipy

uv add scipy

Allows for recording within python.  We use it for the audioSearch module, and nowhere else.
Not essential. Requires `portaudio` and, on the Mac, the XCode command-line development tools.

On the Mac, run::

    xcode-select --install
    brew install portaudio
    uv add pyaudio


pygame

uv add pygame

uv init --bare
uv add music21

uv run python -m music21.configure

from music21 import environment
environment.set('musicxmlPath', '/usr/bin/mscore')
environment.set('musescoreDirectPNGPath', '/usr/bin/mscore')

curl -LsSf https://astral.sh/uv/install.sh | sh

mkdir ~/m21play
cd ~/m21play
uv init --bare
uv add music21
uv add notebook

uv run python -m music21.configure

uv run jupyter notebook

from music21 import *
n = note.Note('A4')
n.pitch.frequency

cd ~/m21play
uv run jupyter notebook

uv add --upgrade music21

winget install --id=astral-sh.uv -e

mkdir ~\m21play
cd ~\m21play
uv init --bare
uv add music21
uv add notebook

uv run python -m music21.configure

uv run jupyter notebook

from music21 import *
n = note.Note('A4')
n.pitch.frequency

cd ~\m21play
uv run jupyter notebook

uv add --upgrade music21

usersGuide_33_expressions
usersGuide_34_instruments
usersGuide_36_clientWeakref
usersGuide_41_figuredBass
usersGuide_43_searching1
usersGuide_46_streams3
usersGuide_56_searching2
usersGuide_57_speed

devTest_unconvertedExamples
devTest_timespans
devTest_inversions

devTest_plots_no_m21
devTest_plots_w_m21
devTest_widgets
notebook_show_tests

midi

`music21` was made possible by generous research funding
from the **Seaver Institute** and
the **National Endowment for the Humanities**/Digging into Data research fund.

In addition, we acknowledge previous support from `M.I.T.`_, the
`School of Humanities Arts and Social Sciences`_, and the
`Music and Theater Arts`_ section.

.. _M.I.T.: https://web.mit.edu/
.. _School of Humanities Arts and Social Sciences: https://shass.mit.edu/
.. _Music and Theater Arts: https://mta.mit.edu/

Colleagues and Institutions

Additionally, the following individuals have contributed materials or knowledge
to this project.  Their contributions and generosity are greatly appreciated.

* Thomas Bonte, Nicholas Froment, and Werner Schweer of `MuseScore`_ for their
   support and for their contributions to the open source music notation projects,
   including the Bach Goldberg Variations and the Handel Arias included.

* `Jacob Walls`_, contributed greatly to the type-safety, speed, and test coverage
   of `music21`.  If your music21 program "just works" without needing to guess what
   any argument goes where, Jacob is to thank.

* `Donald Byrd`_, researcher on University of Indiana who created
   a schema for computer-aided musicology (along with the source of all sorts of
   examples of how music notation is difficult).

* `Jack Campin`_ has kindly given permission to distribute his ABC editions of the Aird
  Collection, the Northumbrian Minstrelsy, and the Colonial and Civil War American
  Fife Music Collection.

* `John Chambers`_ has provided ABC editions to distribute with music21, including the
  Aird Collection, the O'Neill's Music of Ireland Collection, and Ryan's Mammoth Collection
  of fiddle tunes.

* `Laura E. Conrad`_ has kindly given permission to distribute her ABC editions of
  renaissance polyphony from Serpent Publications.

* `Ewa Dahlig-Turek`_ has kindly given permission to distribute the
   Essen folksong database with music21.

* `Margaret Greentree` kindly gave permission for distribution of her edited
   collection of the Bach chorales in MusicXML format as part of the music21 corpus.
   Her website contains all these chorales in additional formats.
   Any discoveries we make regarding these chorales are done in her memory.

* Bret Aarden for kindly contributing his conversions of Palestrina Mass corpus to `music21`.

* Walter B. Hewlett and Craig Sapp of Stanford's CCARH for support.

* `Justin London` compiled and maintained the list of Second-Viennese
   row forms that form the original backbone of serial.py.

* `McGill University`_ ELVIS project for including the MEI parser. Special thanks to Julie
   Cumming, Andrew Hankinson, Ichiro Fujinaga, and especially Christopher Antila for contributing.

* `Manuel Op de Coul`_ has kindly gave permission to use the Scala
   scale archive of nearly 4000 scales in music21.

* `Seymour Shlien`_ has kindly given permission to distribute his ABC
   encodings of the Essen folksong database with music21.

* `Bryen Travis`_ has kindly gave permission to use his collection of
   Bach MIDI data in `music21`.  It is no longer included in the Corpus, but we
   continue to thank him for his generosity.

* `Project Gutenberg`_ houses public domain music, including the quartets of Beethoven,
  Haydn, and Mozart, in musicxml format which we have been able to include in music21.

.. _Donald Byrd: https://web.archive.org/web/20220610200930/https://homes.luddy.indiana.edu/donbyrd/CMNExtremes.htm
.. _Jacob Walls: https://jacobtylerwalls.com/
.. _Laura E. Conrad: http://www.serpentpublications.org/drupal7/
.. _MuseScore: https://musescore.com/
.. _Bryen Travis: http://www.bachcentral.com/
.. _Ewa Dahlig-Turek: http://www.esac-data.org
.. _Seymour Shlien: https://ifdo.ca/~seymour/runabc/esac/esacdatabase.html
.. _Manuel Op de Coul: https://www.huygens-fokker.org/scala
.. _John Chambers: http://trillian.mit.edu/~jc/music/book
.. _Jack Campin: http://www.campin.me.uk/
.. _McGill University: https://works.hcommons.org/records/c6ew2-tth07
.. _Project Gutenberg: https://www.gutenberg.org/browse/categories/4


How to Contribute
-----------------

We are always interested in working with interested musicologists,
programmers, psychologists, composers, game-designers,
performers, amateur music enthusiasts, etc.  In particular, we're interested
in hearing about how `music21` helped you
advance your work ... or in problems with `music21` itself or contributions you've made.

You can contact the larger `music21` community through the `music21 list`_.

.. _music21 list: https://groups.google.com/g/music21list

In particular, if you are interested in contributing documentation, tests,
or new features to music21, please contact the lead author on GitHub or through the
list.


Licensing and Copyright
---------------------------------

The `music21` Toolkit

The BSD-licensed `music21` software is distributed with a corpus of encoded
compositions which are distributed
with the permission of the encoders (and, where needed, the composers
or arrangers) and where permitted
under United States copyright law. Some encodings included in the corpus
may not be used for commercial uses
or have other restrictions: please see the licenses embedded in individual
compositions or directories for more details.

To the best of our knowledge, the music (if not the encodings)
in the corpus are either out of copyright
in the United States and/or are licensed for non-commercial use.  We also
aim to have all files out of copyright in the EU and Canada as well.
These works, along with any works linked
to in the virtual corpus, may or may not be free in your jurisdiction.
If you believe this message to be in
error regarding one or more works please contact Michael Cuthbert at
the address provided on the contact page.

---

### Documentation Source About .Ipynb Checkpoints Applications Checkpoint (`documentation/source/about/.ipynb_checkpoints/applications-checkpoint.rst`)

.. _applications:


Applications and Extensions of `music21`
=============================================

`Music21` has been used in numerous research tasks already, and will continue
to offer researchers many tools with which to explore new domains.


Papers, Presentations, and Publications
---------------------------------------------------

The following papers and publications make extensive use of `music21`. Start here:

Cuthbert, Michael Scott Cuthbert and Christopher Ariza. 2010. "`music21`: A
Toolkit for Computer-Aided Musicology and Symbolic Music Data." In
*Proceedings of the International Society for Music Information Retrieval*.
https://www.trecento.com/research/Cuthbert_Ariza_Music21_ISMIR_2010.pdf


Then continue with:

Church, Maura and Michael Scott Cuthbert. 2014. "Improving Rhythmic
Transcriptions via Probability Models Applied Post-OMR." In *Proceedings of the
International Society for Music Information Retrieval*.
https://www.trecento.com/research/Church_Cuthbert_OMR.pdf

Cuthbert, Michael Scott, Beth Hadley, Lars Johnson, and Christopher Reyes. 2012.
"Interoperable Digital Musicology Research via `music21` Web Applications."
From *Joint CLARIN-D/DARIAH Workshop at Digital Humanities Conference Hamburg*.
https://www.trecento.com/research/Cuthbert_Hadley_Johnson_Reyes_Music21_SOA.pdf

Cuthbert, Michael Scott, Chris Ariza, Jose Cabal-Ugaz, Beth Hadley, and Neena Parikh. 2011.
"Hidden Beyond MIDI’s Reach:Feature Extraction and Machine Learning with Rich Symbolic Formats
in `music21`" In *Proceedings of the Neural Information Processing Systems Conference*.
https://www.trecento.com/research/Cuthbert_Ariza_Cabal-Ugaz_Hadley_Parikh-Hidden-NIPS2011.pdf

Cuthbert, Michael Scott, Chris Ariza, and Lisa D. Friedland. 2011. "Feature Extraction and
Machine Learning on Symbolic Music using the `music21` Toolkit" In
*Proceedings of the International Symposium on Music Information Retrieval*
https://www.trecento.com/research/Cuthbert_Ariza_Friedland_Feature-Extraction_ISMIR_2011.pdf

Jordi Barthomé Guillen and Michael Scott Cuthbert. 2011. "Score Following from
Inaccurate Score and Audio Data using OMR and `music21`." In *Proceedings of the Neural
Information Processing Systems Conference (Music and Machine Learning, Workshop 4*.
https://www.trecento.com/research/Bartolome-Guillen_Cuthbert_ScoreFollower.pdf

Ariza, C. and Michael Scott Cuthbert. 2011. "The `music21` Stream: A New Object
Model for Representing, Filtering, and Transforming Symbolic Musical
Structures." In *Proceedings of the International Computer Music Conference*.
San Francisco: International Computer Music Association, pp. 61-68.
Available online at https://www.trecento.com/research/Ariza_Cuthbert_Stream_ICMC_2011.pdf

Ariza, C. and Michael Scott Cuthbert. 2011. "Analytical and Compositional
Applications of a Network-Based Scale Model in `music21`." In *Proceedings of the
International Computer Music Conference*. San Francisco: International Computer
Music Association, pp. 701-708. Available online at
https://www.trecento.com/research/Ariza_Cuthbert_Scale_ICMC_2011.pdf

Ariza, C. and Michael Scott Cuthbert. 2010. "Modeling Beats, Accents, Beams, and
Time Signatures Hierarchically with `music21` Meter Objects." In *Proceedings of the
International Computer Music Conference*. San Francisco: International Computer Music
Association. 216-223. Available online at
https://www.trecento.com/research/Ariza_Cuthbert_Meter_ICMC_2010.pdf

Future Goals and Potential Applications
---------------------------------------------------

There are numerous applications for music21 that we anticipate, yet simply have not had
time to implement. Consider taking on one of these projects, or write us with new and
interesting suggestions. To contact the authors, visit :ref:`about`.

- Piano-key-visualization

- Slonimsky scale types

- Automatic clarinet fingering generation via ClarFinger font (link: www.trecento.com/fonts/)

- Automatic string fingerings.

- Indian Raga encoding: including ascending, descending, and typical presentations,
  microtonal inflections, common associations, historical context.

- Multiple-simultaneous-tempi to a single tempo conversion (via tuplets).

- Palestrina counterpoint generation (via algorithms of Mary Farbood and others.).

- Beneventan chant similarity indices (thanks to the work of Thomas Forrest Kelly and the
  Exultet encodings made available in `**kern` by Elsa De Luca).

- Identify potential clefs for fragmentary Renaissance and Medieval pieces that are
  missing their clefs. (Use their staff-lines and minimizing number of melodic and
  harmonic tritones).

---

--- METRICS ---
- Files Extracted: 21
- Estimated Token Budget: ~23455 tokens
- Canonical Reference: https://codewiki.google/github.com/cuthbertLab/music21