Previous topic

music21.converter

Next topic

music21.corpus.chorales

Table Of Contents

Table Of Contents

This Page

music21.corpus

The music21 corpus includes a collection of freely distributable music in MusicXML, Humdrum, and other representations. The corpus package is an interface for easily working with this data.

To see a complete listing of the works in the music21 corpus, visit List of Works Found in the music21 Corpus. Note that music21 does not own most of the music in the corpus – it has been licensed to us (or in a free license). It may not be free in all parts of the world, but to the best of our knowledge is true for the US.

Functions

music21.corpus.addPath(filePath)

Add a directory path to the Local Corpus on a temporary basis, i.e., just for the current Python session.

All directories contained within the provided directory will be searched for files with file extensions matching the currently readable file types. Any number of file paths can be added one at a time.

An error will be raised if the file path does not exist, is already defined as a temporary, or is already being searched by being defined with the Environment ‘localCorpusSettings’ setting.

To permanently add a path to the list of stored local corpus paths, set the ‘localCorpusPath’ or ‘localCorpusSettings’ setting of the UserSettings object.

>>> corpus.addPath('~/Documents')

Alternatively, add a directory permanently (see link above for more details):

>>> us = environment.UserSettings()
>>> us['localCorpusPath'] = 'd:/desktop/'

Restart music21 after adding paths.

music21.corpus.cacheMetadata(corpusNames=(u'local', ))

Rebuild the metadata cache.

music21.corpus.compressAllXMLFiles(deleteOriginal=False)

Takes all filenames in corpus.paths and runs music21.corpus.compressXML() on each. If the musicXML files are compressed, the originals are deleted from the system.

music21.corpus.compressXML(filename, deleteOriginal=False)

Takes a filename, and if the filename corresponds to a musicXML file with an .xml extension, creates a corresponding compressed .mxl file in the same directory.

If deleteOriginal is set to True, the original musicXML file is deleted from the system.

music21.corpus.getBachChorales(fileExtensions=u'xml')

Return the file name of all Bach chorales.

By default, only Bach Chorales in xml format are returned, because the quality of the encoding and our parsing of those is superior.

N.B. Look at the module corpus.chorales for many better ways to work with the chorales.

>>> from music21 import corpus
>>> a = corpus.getBachChorales()
>>> len(a) > 400
True
>>> a = corpus.getBachChorales('krn')
>>> len(a) > 10
False
>>> a = corpus.getBachChorales('xml')
>>> len(a) > 400
True
>>> a[0]
u'/Users/cuthbert/Documents/music21/corpus/bach/bwv1.6.mxl'
music21.corpus.getBeethovenStringQuartets(fileExtensions=None)

Return a list of all Beethoven String Quartet filenames.

>>> from music21 import corpus
>>> a = corpus.getBeethovenStringQuartets()
>>> len(a) > 10
True
>>> a = corpus.getBeethovenStringQuartets('krn')
>>> len(a) < 10 and len(a) > 0
True
>>> a = corpus.getBeethovenStringQuartets('xml')
>>> len(a) > 400
False
music21.corpus.getComposer(composerName, fileExtensions=None)

Return all filenames in the corpus that match a composer’s or a collection’s name. An fileExtensions, if provided, defines which extensions are returned. An fileExtensions of None (default) returns all extensions.

Note that xml and mxl are treated equivalently.

>>> from music21 import corpus
>>> a = corpus.getComposer('beethoven')
>>> len(a) > 10
True
>>> a = corpus.getComposer('mozart')
>>> len(a) > 10
True
>>> a = corpus.getComposer('bach', 'krn')
>>> len(a) < 10
True
>>> a = corpus.getComposer('bach', 'xml')
>>> len(a) > 10
True
music21.corpus.getComposerDir(composerName)

Given the name of a composer, get the path to the top-level directory of that composer:

>>> import os
>>> from music21 import corpus
>>> a = corpus.getComposerDir('beethoven')
>>> a.endswith(os.path.join('corpus', os.sep, 'beethoven'))
True
>>> a = corpus.getComposerDir('bach')
>>> a.endswith(os.path.join('corpus', os.sep, 'bach'))
True
>>> a = corpus.getComposerDir('mozart')
>>> a.endswith(os.path.join('corpus', os.sep, 'mozart'))
True
music21.corpus.getCorePaths(fileExtensions=None, expandExtensions=True)

Get all paths in the corpus that match a known extension, or an extenion provided by an argument.

If expandExtensions is True, a format for an extension, and related extensions, will replaced by all known input extensions.

This is convenient when an input format might match for multiple extensions.

>>> from music21 import corpus
>>> corpusFilePaths = corpus.getCorePaths()
>>> len(corpusFilePaths)
3045
>>> kernFilePaths = corpus.getCorePaths('krn')
>>> len(kernFilePaths) >= 500
True
>>> abcFilePaths = corpus.getCorePaths('abc')
>>> len(abcFilePaths) >= 100
True
music21.corpus.getHandelMessiah(fileExtensions=u'md')

Return a list of the filenames of all parts of Handel’s Messiah.

>>> from music21 import corpus
>>> a = corpus.getHandelMessiah()
>>> len(a)
43
music21.corpus.getLocalPaths(fileExtensions=None, expandExtensions=True)

Access files in additional directories supplied by the user and defined in environment settings in the ‘localCorpusSettings’ list.

If additional paths are added on a per-session basis with the addPath() function, these paths are also returned with this method.

music21.corpus.getMonteverdiMadrigals(fileExtensions=u'xml')

Return a list of the filenames of all Monteverdi madrigals.

>>> from music21 import corpus
>>> a = corpus.getMonteverdiMadrigals()
>>> len(a) > 40
True
music21.corpus.getPaths(fileExtensions=None, expandExtensions=True, name=(u'local', u'core', u'virtual'))

Get paths from core, virtual, and/or local corpora. This is the public interface for getting all corpus paths with one function.

music21.corpus.getVirtualPaths(fileExtensions=None, expandExtensions=True)

Get all paths in the virtual corpus that match a known extension.

An extension of None will return all known extensions.

>>> from music21 import corpus
>>> len(corpus.getVirtualPaths()) > 6
True
music21.corpus.getVirtualWorkList(workName, movementNumber=None, fileExtensions=None)

Given a work name, search all virtual works and return a list of URLs for any matches.

>>> from music21 import corpus
>>> corpus.getVirtualWorkList('bach/bwv1007/prelude')
['http://kern.ccarh.org/cgi-bin/ksdata?l=cc/bach/cello&file=bwv1007-01.krn&f=xml']
>>> corpus.getVirtualWorkList('junk')
[]
music21.corpus.getWork(workName, movementNumber=None, fileExtensions=None)

Search the corpus, then the virtual corpus, for a work, and return a file path or URL. N.B. does not parse the work: but it’s suitable for passing to converter.parse.

This method will return either a list of file paths or, if there is a single match, a single file path. If no matches are found an Exception is raised.

>>> import os
>>> from music21 import corpus
>>> a = corpus.getWork('opus74no2', 4)
>>> a.endswith(os.path.sep.join([
...     'haydn', 'opus74no2', 'movement4.mxl']))
True
>>> a = corpus.getWork(['haydn', 'opus74no2', 'movement4.xml'])
>>> a.endswith(os.path.sep.join([
...     'haydn', 'opus74no2', 'movement4.mxl']))
True
>>> trecentoFiles = corpus.getWork('trecento')
>>> len(trecentoFiles) > 100 and len(trecentoFiles) < 200
True
music21.corpus.getWorkList(workName, movementNumber=None, fileExtensions=None)

Search the corpus and return a list of filenames of works, always in a list.

If no matches are found, an empty list is returned.

>>> from music21 import corpus
>>> len(corpus.getWorkList('beethoven/opus18no1'))
8
>>> len(corpus.getWorkList('beethoven/opus18no1', 1))
2
>>> len(corpus.getWorkList('beethoven/opus18no1', 1, '.krn'))
1
>>> len(corpus.getWorkList('beethoven/opus18no1', 1, '.xml'))
1
>>> len(corpus.getWorkList('beethoven/opus18no1', 0, '.xml'))
0
>>> len(corpus.getWorkList('handel/hwv56', '1-02', '.md'))
1
>>> len(corpus.getWorkList('handel/hwv56', (2,1), '.md'))
1
>>> len(corpus.getWorkList('bach/artOfFugue_bwv1080', 2, '.md'))
1

Make sure that ‘verdi’ just gets the single Verdi piece and not the Monteverdi pieces:

>>> len(corpus.getWorkList('verdi'))
1
music21.corpus.getWorkReferences(sort=True)

Return a data dictionary for all works in the corpus and (optionally) the virtual corpus. Returns a list of reference dictionaries, each each dictionary for a each composer. A ‘works’ dictionary for each composer provides references to dictionaries for all associated works.

This is used in the generation of corpus documentation

>>> from music21 import corpus
>>> post = corpus.getWorkReferences()
music21.corpus.parse(workName, movementNumber=None, number=None, fileExtensions=None, forceSource=False)

The most important method call for corpus.

Similar to the parse() method of converter (which takes in a filepath on the local hard drive), this method searches the corpus (including the virtual corpus) for a work fitting the workName description and returns a music21.stream.Stream.

If movementNumber is defined, and a movement is included in the corpus, that movement will be returned.

If number is defined, and the work is a collection with multiple components, that work number will be returned. For instance, some of our ABC documents contain dozens of folk songs within a single file.

Advanced: if forceSource is True, the original file will always be loaded freshly and pickled (e.g., pre-parsed) files will be ignored. This should not be needed if the file has been changed, since the filetime of the file and the filetime of the pickled version are compared. But it might be needed if the music21 parsing routine has changed.

Example, get a chorale by Bach. Note that the source type does not need to be specified, nor does the name Bach even (since it’s the only piece with the title BWV 66.6)

>>> from music21 import corpus
>>> bachChorale = corpus.parse('bwv66.6')
>>> len(bachChorale.parts)
4

After parsing, the file path within the corpus is stored as .corpusFilePath

>>> bachChorale.corpusFilepath
u'bach/bwv66.6.mxl'
music21.corpus.parseWork(*arguments, **keywords)

This function exists for backwards compatibility.

All calls should use parse() instead.

music21.corpus.search(query, field=None, corpusNames=(u'core', u'virtual', u'local'), fileExtensions=None)

Search all stored metadata and return a list of file paths; to return a list of parsed Streams, use searchParse().

The name parameter can be used to specify one of three corpora: core (included with music21), virtual (defined in music21 but hosted online), and local (hosted on the user’s system (not yet implemented)).

This method uses stored metadata and thus, on first usage, will incur a performance penalty during metadata loading.

>>> corpus.search('china')
<music21.metadata.bundles.MetadataBundle {1235 entries}>
>>> corpus.search('bach', field='composer')
<music21.metadata.bundles.MetadataBundle {21 entries}>
>>> corpus.search('coltrane', corpusNames=('virtual',))
<music21.metadata.bundles.MetadataBundle {1 entry}>
music21.corpus.uncompressMXL(filename, deleteOriginal=False)

Takes a filename, and if the filename corresponds to a compressed musicXML file with an .mxl extension, creates a corresponding uncompressed .xml file in the same directory.

If deleteOriginal is set to True, the original compressed musicXML file is deleted from the system.