music21.corpus.corpora¶
Corpus¶
-
class
music21.corpus.corpora.
Corpus
¶ Abstract base class of all corpora subclasses.
Corpus
read-only properties
-
Corpus.
directoryInformation
¶ Returns a tuple of DirectoryInformation objects for a each directory in self._directoryInformation.
>>> core = corpus.corpora.CoreCorpus() >>> diBrief = core.directoryInformation[0:4] >>> diBrief (<music21.corpus.corpora.DirectoryInformation airdsAirs>, <music21.corpus.corpora.DirectoryInformation bach>, <music21.corpus.corpora.DirectoryInformation beethoven>, <music21.corpus.corpora.DirectoryInformation ciconia>) >>> diBrief[3].directoryTitle 'Johannes Ciconia'
-
Corpus.
metadataBundle
¶ The metadata bundle for a corpus:
>>> from music21 import corpus >>> corpus.CoreCorpus().metadataBundle <music21.metadata.bundles.MetadataBundle 'core': {144... entries}>
-
Corpus.
name
¶ The name of a given corpus.
Corpus
methods
-
static
Corpus.
fromName
(name)¶ Instantiate a specific corpus based on name:
>>> corpus.Corpus.fromName('core') <music21.corpus.corpora.CoreCorpus>
>>> corpus.Corpus.fromName('virtual') <music21.corpus.corpora.VirtualCorpus>
>>> corpus.Corpus.fromName('local') <music21.corpus.corpora.LocalCorpus: 'local'>
>>> corpus.Corpus.fromName('test') <music21.corpus.corpora.LocalCorpus: 'test'>
-
Corpus.
getPaths
()¶ The paths of the files in a given corpus.
-
static
Corpus.
listSearchFields
()¶ List all available search field names:
>>> for field in corpus.Corpus.listSearchFields(): ... field ... 'alternativeTitle' 'ambitus' 'composer' 'date' 'keySignatureFirst' 'keySignatures' 'localeOfComposition' 'movementName' 'movementNumber' 'noteCount' 'number' 'opusNumber' 'pitchHighest' 'pitchLowest' 'quarterLength' 'tempoFirst' 'tempos' 'timeSignatureFirst' 'timeSignatures' 'title'
-
static
Corpus.
parse
(workName, movementNumber=None, number=None, fileExtensions=None, forceSource=False, format=None)¶ 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 amusic21.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.Corpus.parse('bwv66.6') >>> len(bachChorale.parts) 4
After parsing, the file path within the corpus is stored as
.corpusFilePath
>>> bachChorale.corpusFilepath 'bach/bwv66.6.mxl'
-
static
Corpus.
search
(query, field=None, corpusNames=None, fileExtensions=None)¶ Search all stored metadata bundles and return a list of file paths.
The
names
parameter can be used to specify which corpora to search, for example:>>> corpus.Corpus.search( ... 'bach', ... corpusNames=('core', 'virtual'), ... ) <music21.metadata.bundles.MetadataBundle {150 entries}>
If
names
is None, all corpora known to music21 will be searched.This method uses stored metadata and thus, on first usage, will incur a performance penalty during metadata loading.
-
Corpus.
updateMetadataBundle
()¶ Update a corpus’ metadata bundle from its stored JSON file on disk.
CoreCorpus¶
-
class
music21.corpus.corpora.
CoreCorpus
¶ A model of the core corpus.
>>> coreCorpus = corpus.CoreCorpus()
CoreCorpus
bases
CoreCorpus
read-only properties
-
CoreCorpus.
name
¶
-
CoreCorpus.
noCorpus
¶ Return True or False if this is a corpus or noCoprus distribution.
>>> from music21 import corpus >>> corpus.CoreCorpus().noCorpus False
Read-only properties inherited from Corpus
:
CoreCorpus
read/write properties
-
CoreCorpus.
manualCoreCorpusPath
¶ Set music21’s core corpus to a directory, and save that information in the user settings.
This is specifically for use with “no corpus” music21 packages, where the core corpus was not included with the rest of the package functionality, and had to be installed separately.
Set it to a directory:
>>> coreCorpus = corpus.CoreCorpus() >>> coreCorpus.manualCoreCorpusPath = '~/Desktop'
Unset it:
>>> coreCorpus.manualCoreCorpusPath = None >>> coreCorpus.manualCoreCorpusPath is None True
CoreCorpus
methods
-
CoreCorpus.
getBachChorales
(fileExtensions='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 >>> coreCorpus = corpus.CoreCorpus() >>> a = coreCorpus.getBachChorales() >>> len(a) > 400 True
>>> a = coreCorpus.getBachChorales('krn') >>> len(a) > 10 False
>>> a = coreCorpus.getBachChorales('xml') >>> len(a) > 400 True
>>> a[0] '/Users/cuthbert/Documents/music21/corpus/bach/bwv1.6.mxl'
-
CoreCorpus.
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 >>> coreCorpus = corpus.CoreCorpus() >>> a = coreCorpus.getComposer('bach') >>> len(a) > 100 True
>>> a = coreCorpus.getComposer('bach', 'krn') >>> len(a) < 10 True
>>> a = coreCorpus.getComposer('bach', 'xml') >>> len(a) > 10 True
-
CoreCorpus.
getComposerDirectoryPath
(composerName)¶ Given the name of a composer, get the path to the top-level directory of that composer:
>>> import os >>> from music21 import corpus >>> coreCorpus = corpus.CoreCorpus() >>> a = coreCorpus.getComposerDirectoryPath('ciconia') >>> a.endswith(os.path.join('corpus', os.sep, 'ciconia')) True
>>> a = coreCorpus.getComposerDirectoryPath('bach') >>> a.endswith(os.path.join('corpus', os.sep, 'bach')) True
>>> a = coreCorpus.getComposerDirectoryPath('handel') >>> a.endswith(os.path.join('corpus', os.sep, 'handel')) True
-
CoreCorpus.
getMonteverdiMadrigals
(fileExtensions='xml')¶ Return a list of the filenames of all Monteverdi madrigals.
>>> from music21 import corpus >>> coreCorpus = corpus.CoreCorpus() >>> a = coreCorpus.getMonteverdiMadrigals() >>> len(a) > 40 True
-
CoreCorpus.
getPaths
(fileExtensions=None, expandExtensions=True)¶ Get all paths in the core 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 >>> coreCorpus = corpus.CoreCorpus() >>> corpusFilePaths = coreCorpus.getPaths() >>> len(corpusFilePaths) 2567
>>> kernFilePaths = coreCorpus.getPaths('krn') >>> len(kernFilePaths) >= 500 True
>>> abcFilePaths = coreCorpus.getPaths('abc') >>> len(abcFilePaths) >= 100 True
-
CoreCorpus.
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 >>> coreCorpus = corpus.CoreCorpus()
# returns 1 even though there is a ‘.mus’ file, which cannot be read...
>>> len(coreCorpus.getWorkList('cpebach/h186')) 1 >>> len(coreCorpus.getWorkList('cpebach/h186', None, '.xml')) 1
>>> len(coreCorpus.getWorkList('schumann_clara/opus17', 3)) 1 >>> len(coreCorpus.getWorkList('schumann_clara/opus17', 2)) 0
Make sure that ‘verdi’ just gets the single Verdi piece and not the Monteverdi pieces:
>>> len(coreCorpus.getWorkList('verdi')) 1
-
CoreCorpus.
search
(query, field=None, fileExtensions=None)¶ Search the core corpus for metadata entries:
>>> corpus.CoreCorpus().search('3/4') <music21.metadata.bundles.MetadataBundle {1866 entries}>
>>> corpus.CoreCorpus().search( ... 'bach', ... field='composer', ... ) <music21.metadata.bundles.MetadataBundle {21 entries}>
>>> predicate = lambda noteCount: noteCount < 20 >>> corpus.CoreCorpus().search( ... predicate, ... field='noteCount', ... ) <music21.metadata.bundles.MetadataBundle {132 entries}>
Methods inherited from Corpus
:
LocalCorpus¶
-
class
music21.corpus.corpora.
LocalCorpus
(name=None)¶ A model of a local corpus.
>>> localCorpus = corpus.LocalCorpus()
The default local corpus is unnamed, but an arbitrary number of independent, named local corpora can be defined and persisted:
>>> namedLocalCorpus = corpus.LocalCorpus('with a name')
LocalCorpus
bases
LocalCorpus
read-only properties
-
LocalCorpus.
directoryPaths
¶ The directory paths in use by a given local corpus.
-
LocalCorpus.
existsInSettings
¶ True if this local corpus has a corresponding entry in music21’s user settings, otherwise false.
-
LocalCorpus.
name
¶ The name of a given local corpus.
>>> from music21 import corpus >>> corpus.LocalCorpus().name 'local'
>>> corpus.LocalCorpus(name='Bach Chorales').name 'Bach Chorales'
Read-only properties inherited from Corpus
:
LocalCorpus
methods
-
LocalCorpus.
addPath
(directoryPath)¶ Add a directory path to a local corpus:
>>> localCorpus = corpus.LocalCorpus('a new corpus') >>> localCorpus.addPath('~/Desktop')
Paths added in this way will not be persisted from session to session unless explicitly saved by a call to
LocalCorpus.save()
.
-
LocalCorpus.
delete
()¶ Delete a non-default local corpus from the user settings.
-
LocalCorpus.
getPaths
(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.
-
static
LocalCorpus.
listLocalCorporaNames
()¶ List the names of all user-defined local corpora.
The entry for None refers to the default local corpus.
-
LocalCorpus.
removePath
(directoryPath)¶ Remove a directory path from a local corpus.
If that path is included in the list of persisted paths for the given corpus, it will be removed permanently.
-
LocalCorpus.
save
()¶ Save the current list of directory paths in use by a given corpus in the user settings.
-
LocalCorpus.
search
(query, field=None, fileExtensions=None)¶ Search a local corpus.
See
music21.corpus.corpora.Corpus.search
for examples, as the interface is the same.
Methods inherited from Corpus
:
VirtualCorpus¶
-
class
music21.corpus.corpora.
VirtualCorpus
¶ A model of the virtual corpus. that stays online...
>>> virtualCorpus = corpus.VirtualCorpus()
VirtualCorpus
bases
VirtualCorpus
read-only properties
-
VirtualCorpus.
name
¶ The name of the virtual corpus:
>>> corpus.VirtualCorpus().name 'virtual'
Read-only properties inherited from Corpus
:
VirtualCorpus
methods
-
VirtualCorpus.
getPaths
(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.VirtualCorpus().getPaths()) > 6 True
-
VirtualCorpus.
getWorkList
(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 >>> virtualCorpus = corpus.VirtualCorpus() >>> virtualCorpus.getWorkList('bach/bwv1007/prelude') ['http://kern.ccarh.org/cgi-bin/ksdata?l=cc/bach/cello&file=bwv1007-01.krn&f=xml']
>>> virtualCorpus.getWorkList('junk') []
-
VirtualCorpus.
search
(query, field=None, fileExtensions=None)¶ Search the virtual corpus.
See
music21.corpus.corpora.Corpus.search
for examples, as the interface is the same.
Methods inherited from Corpus
:
CorpusFile¶
-
class
music21.corpus.corpora.
CorpusFile
(path, title, filename, format, ext)¶
CorpusFile
read-only properties
-
CorpusFile.
ext
¶ Alias for field number 4
-
CorpusFile.
filename
¶ Alias for field number 2
-
CorpusFile.
format
¶ Alias for field number 3
-
CorpusFile.
path
¶ Alias for field number 0
-
CorpusFile.
title
¶ Alias for field number 1
CorpusWork¶
-
class
music21.corpus.corpora.
CorpusWork
(title, files, virtual)¶
CorpusWork
read-only properties
-
CorpusWork.
files
¶ Alias for field number 1
-
CorpusWork.
title
¶ Alias for field number 0
-
CorpusWork.
virtual
¶ Alias for field number 2
DirectoryInformation¶
-
class
music21.corpus.corpora.
DirectoryInformation
(dirName='', dirTitle='', isComposer=True, corpusObject=None)¶ returns information about a directory in a Corpus. Called from
only tested with CoreCorpus so far.
DirectoryInformation
methods
-
DirectoryInformation.
findWorks
()¶ populate other information about the directory such as files and filenames.
>>> di = corpus.corpora.DirectoryInformation('schoenberg') >>> di.findWorks() OrderedDict([(...'opus19', CorpusWork(title='Opus 19', files=[CorpusFile(path='schoenberg/opus19/movement2.mxl', title='Movement 2', filename='movement2.mxl', format='musicxml', ext='.mxl'), CorpusFile(path='schoenberg/opus19/movement6.mxl', title='Movement 6', filename='movement6.mxl', format='musicxml', ext='.mxl')], virtual=False))])
VirtualCorpusFile¶
-
class
music21.corpus.corpora.
VirtualCorpusFile
(path, title, url, format)¶
VirtualCorpusFile
read-only properties
-
VirtualCorpusFile.
format
¶ Alias for field number 3
-
VirtualCorpusFile.
path
¶ Alias for field number 0
-
VirtualCorpusFile.
title
¶ Alias for field number 1
-
VirtualCorpusFile.
url
¶ Alias for field number 2