DOCSEARCHbyAlgolia
Submit Docs

music21

repository·master·Indexed 25 days ago

https://github.com/cuthbertlab/music21

A comprehensive toolkit for computer-aided musical analysis and computational musicology. music21 allows developers to programmatically interact with, analyze, and manipulate musical scores. It supports various data formats including MusicXML, MIDI, JSON, and CSV, and provides tools for parsing, transposing, and validating musical stream structures.

Tokens
49.1K
Snippets
138
Records
266
Agent score
80%

What's inside music21

  1. Strategies for storing music21 data

    master

    music21 does not have a single native data format; it is designed to manipulate existing data. Depending on your needs, use the following strategies for storage:

    • Recreatable data: Store the script used to generate the data and rerun it.
    • Music notation: Use MusicXML for high-fidelity notation, or MIDI / Lilypond->PNG for audio or graphics.
    • Non-recreatable data (Short-term): Use Python's pickle module. To ensure maximum preservation of the object structure, use s.freeze() before pickling and s.thaw() after loading. For more complex needs, use s.setupSerializationScaffold() before pickle.dump() and s.teardownSerializationScaffold() after pickle.load().
    • Non-recreatable data (Long-term/Sharing): Save relevant parts in XML, JSON, or CSV. While music21 has partial support for JSON storage of Streams, it is not complete.

  2. Licensing and copyright for music21

    master

    music21 Toolkit

    music21 code (excluding content encoded in the corpus) is free and open-source software licensed under the BSD License.

    music21 Corpus

    The music21 corpus consists of encoded compositions distributed with permission from encoders and/or composers.

    Important Note on Usage:

    • Some encodings in the corpus may have restrictions (e.g., non-commercial use). Always check the licenses embedded within individual compositions or directories for specific details.
    • While the project aims to include works that are out of copyright in the US, EU, and Canada, copyright status can vary by jurisdiction. Users should verify the copyright status of works in their specific region before use.

  3. Preserving enharmonics during transposition

    master

    When using .transpose(i) with an integer i, music21 treats the interval as a music21.interval.ChromaticInterval. Chromatic intervals do not prioritize specific enharmonics and may change the note's enharmonic spelling based on context.

    To force specific enharmonics, use a string representing a music21.interval.DiatonicInterval (e.g., "P8" for a perfect octave or "m-3" for a minor third). This will honor your enharmonic preference unless the resulting note requires quintuple sharps or flats.

  4. Control visibility of doctest code in documentation

    master

    Since music21 uses doctests (code preceded by >>>), you can control what appears in the generated documentation versus what is executed during tests using specific markers. Note: These markers must be in ALL CAPS.

    • OMIT_FROM_Docs: Everything following this line in a docstring will be excluded from the generated documentation but will still be executed during tests.
    • #_DOCS_Hide: Place this at the end of a line to hide that specific line from the documentation while keeping it in the test suite.
    • #_DOCS_Show: Text following this on a line is removed from the documentation, but the line itself (and subsequent lines) will be included in the documentation until the marker is encountered.
    '''
>>> from music21 import *
>>> c1 = note.Note('C#')
>>> c1.step
'C'

OMIT_FROM_Docs

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

# Or using line-level markers:
'''
>>> d1 = note.Note("D-")
>>> assert(d1.name == 'D-')  #_DOCS_Hide
>>> #_DOCS_Show d1.show('lily.png')
'''

  5. How to contribute to music21

    master

    The music21 project welcomes contributions from musicologists, programmers, psychologists, composers, game designers, performers, and music enthusiasts.

    If you are interested in contributing documentation, tests, or new features, you should contact the lead author on GitHub or through the music21 list (Google Groups).

    You can also share how music21 has helped your work or report problems with the toolkit via the community mailing list.

  6. Send a pull request to the official music21 repository

    master

    A pull request is a request for the music21 team to pull changes from your fork into the centralized version. To submit one:

    1. Log into GitHub and navigate to your fork of music21.
    2. Click the green Compare & review button located under the repository summary header.
    3. If your fork differs from the official repository, click the banner that says "Click to create a pull request for this comparison".
    4. Write a detailed description of your changes. Include what the changes accomplish, which issue they address (if any), and whether they are enhancements or new functionality.
    5. Click the Send pull request button.

  7. Edit documentation using Jupyter Notebooks

    master

    The majority of new music21 documentation should be written in Jupyter Notebook (.ipynb) format. These files should be edited using a Jupyter Notebook environment running Python 3.7 or higher rather than being edited directly as raw files.

    To set up and run a notebook environment:

    1. Install Jupyter via pip.
    2. Navigate to your target directory.
    3. Launch the notebook server.

  8. Install Git and PyCharm for music21 development

    master

    To contribute to the music21 codebase, follow these installation steps:

    1. Install Git: Download binaries for Windows, OSX, or Unix from https://git-scm.com/. Alternatively, use the GitHub Desktop app at https://desktop.github.com.
    2. Install PyCharm: While not strictly required to edit Python files, PyCharm is the only supported environment for receiving technical assistance from the music21 team. It is used to enforce coding standards (whitespace, unused variables) and facilitate debugging.

  9. Check Python version compatibility for music21

    master

    The current version of music21 (v10) requires Python 3.12+.

    If you are using an older version of Python, you must use a corresponding older version of music21:

    • Python 2: Use music21 v4
    • Python 3.4: Use music21 v4
    • Python 3.5: Use music21 v5
    • Python 3.6: Use music21 v6
    • Python 3.7: Use music21 v7
    • Python 3.8/3.9: Use music21 v8
    • Python 3.10: Use music21 v9
    • Python 3.11: Use music21 v10

  10. Install music21 on Windows

    master

    To install music21 on Windows, ensure you have Python 3.12 or higher installed. You can download the Windows installer from python.org.

    Once Python is installed, open a command prompt and run the following command to install music21 via pip:

    pip install music21

    If you already have music21 installed and want to upgrade to the latest version, use:

    pip install --upgrade music21

  11. Install music21 on macOS

    master

    To install music21 on macOS, use pip3 via the Terminal. It is recommended to use a Python 3 version downloaded from python.org rather than Conda or Enthought Canopy to ensure full compatibility with matplotlib for plotting functions.

    Installation Command

    Open 'Terminal' (found in Applications -> Utilities) and run:

    sudo pip3 install music21

    Upgrading music21

    To upgrade an existing installation, use:

    sudo pip3 install --upgrade music21

  12. Merge inherited `_DOC_ATTR` documentation

    master

    If you need to explicitly merge the _DOC_ATTR dictionary inherited from a parent class with a locally defined _DOC_ATTR dictionary, use the Python update() method. This is useful when you want to override specific attribute descriptions while keeping others from the parent class.

    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