Previous topic

music21.contour

Next topic

music21.corpus

Table Of Contents

Table Of Contents

This Page

music21.converter

music21.converter contains tools for loading music from various file formats, whether from disk, from the web, or from text, into music21.stream.:class:~music21.stream.Score objects (or other similar stream objects).

The most powerful and easy to use tool is the parse() function. Simply provide a filename, URL, or text string and, if the format is supported, a Score will be returned.

This is the most general public interface for all formats. Programmers adding their own formats to the system should provide an interface here to their own parsers (such as humdrum, musicxml, etc.)

The second and subsequent times that a file is loaded it will likely be much faster since we store a parsed version of each file as a “pickle” object in the temp folder on the disk.

>>> s = converter.parse('d:/mydocs/schubert.krn')
>>> s
<music21.stream.Score ...>

Functions

music21.converter.parse(value, *args, **keywords)

Given a file path, encoded data in a Python string, or a URL, attempt to parse the item into a Stream. Note: URL downloading will not happen automatically unless the user has set their Environment “autoDownload” preference to “allow”.

Keywords can include number which specifies a piece number in a file of multipiece file.

format specifies the format to parse the line of text or the file as.

A string of text is first checked to see if it is a filename that exists on disk. If not it is searched to see if it looks like a URL. If not it is processed as data.

The data is normally interpreted as a line of TinyNotation with the first argument being the time signature:

TODO: SHOW FILE TODO: SHOW URL

>>> s = converter.parse("tinyNotation: 3/4 E4 r f# g=lastG trip{b-8 a g} c")
>>> s.getElementsByClass(meter.TimeSignature)[0]
<music21.meter.TimeSignature 3/4>
>>> s2 = converter.parse("E8 f# g#' G f g# g G#", "2/4")
>>> s2.show('text')
{0.0} <music21.meter.TimeSignature 2/4>
{0.0} <music21.note.Note E>
{0.5} <music21.note.Note F#>
{1.0} <music21.note.Note G#>
{1.5} <music21.note.Note G>
{2.0} <music21.note.Note F>
{2.5} <music21.note.Note G#>
{3.0} <music21.note.Note G>
{3.5} <music21.note.Note G#>
music21.converter.parseFile(fp, number=None, format=None, forceSource=False)

Given a file path, attempt to parse the file into a Stream.

music21.converter.parseData(dataStr, number=None, format=None)

Given musical data represented within a Python string, attempt to parse the data into a Stream.

music21.converter.parseURL(url, number=None, format=None, forceSource=False)

Given a URL, attempt to download and parse the file into a Stream. Note: URL downloading will not happen automatically unless the user has set their Environment “autoDownload” preference to “allow”.

music21.converter.freeze(streamObj, fmt=None, fp=None, fastButUnsafe=False, zipType='zlib')

Given a StreamObject and a file path, serialize and store the Stream to a file.

This function is based on the StreamFreezer object.

The serialization format is defined by the fmt argument; ‘pickle’ (the default) is only one presently supported. ‘json’ or ‘jsonnative’ will be used once jsonpickle is good enough.

If no file path is given, a temporary file is used.

The file path is returned.

>>> c = converter.parse('c4 d e f', '4/4')
>>> c.show('text')
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note D>
{2.0} <music21.note.Note E>
{3.0} <music21.note.Note F>
>>> fp = converter.freeze(c, fmt='pickle')
>>> fp
'/tmp/music21/sjiwoe.pgz'

The file can then be “thawed” back into a Stream using the thaw() method.

>>> d = converter.thaw(fp)
>>> d.show('text')
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note D>
{2.0} <music21.note.Note E>
{3.0} <music21.note.Note F>
music21.converter.thaw(fp, zipType='zlib')

Given a file path of a serialized Stream, defrost the file into a Stream.

This function is based on the StreamFreezer object.

See the documentation for freeze() for demos.

music21.converter.freezeStr(streamObj, fmt=None)

Given a StreamObject serialize and return a serialization string.

This function is based on the StreamFreezer object.

The serialization format is defined by the fmt argument; ‘pickle’ (the default), is the only one presently supported.

>>> c = converter.parse('c4 d e f', '4/4')
>>> c.show('text')
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note D>
{2.0} <music21.note.Note E>
{3.0} <music21.note.Note F>
>>> data = converter.freezeStr(c, fmt='pickle')
>>> len(data) > 20 # pickle implementation dependent
True
>>> d = converter.thawStr(data)
>>> d.show('text')
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note D>
{2.0} <music21.note.Note E>
{3.0} <music21.note.Note F>
music21.converter.thawStr(strData)

Given a serialization string, defrost into a Stream.

This function is based on the StreamFreezer object.

Converter

class music21.converter.Converter

A class used for converting all supported data formats into music21 objects.

Not a subclass, but a wrapper for different converter objects based on format.

Converter read-only properties

Converter.stream

Returns the .subConverter.stream object.

Converter methods

Converter.formatFromHeader(dataStr)

if dataStr begins with a text header such as “tinyNotation:” then return that format plus the dataStr with the head removed.

Else, return (None, dataStr) where dataStr is the original untouched.

Not case sensitive.

>>> c = converter.Converter()
>>> c.formatFromHeader('tinynotation: C4 E2')
('tinyNotation', 'C4 E2')
>>> c.formatFromHeader('C4 E2')
(None, 'C4 E2')
Converter.getFormatFromFileExtension(fp)

gets the format from a file extension.

Converter.parseData(dataStr, number=None, format=None, forceSource=False)

Given raw data, determine format and parse into a music21 Stream.

Converter.parseFile(fp, number=None, format=None, forceSource=False, storePickle=True)

Given a file path, parse and store a music21 Stream.

If format is None then look up the format from the file extension using common.findFormatFile.

Will load from a pickle unless forceSource is True Will store as a pickle unless storePickle is False

Converter.parseFileNoPickle(fp, number=None, format=None, forceSource=False)

Given a file path, parse and store a music21 Stream.

If format is None then look up the format from the file extension using common.findFormatFile.

Does not use or store pickles

Converter.parseURL(url, format=None, number=None)

Given a url, download and parse the file into a music21 Stream stored in the stream property of the converter object.

Note that this checks the user Environment autoDownlaad setting before downloading.

TODO: replace with free version of jeanieLightBrownHair

>>> jeanieLightBrownURL = 'http://www.wikifonia.org/node/4391'
>>> c = converter.Converter()
>>> c.parseURL(jeanieLightBrownURL)
>>> jeanieStream = c.stream
Converter.setSubconverterFromFormat(format, forceSource=False)

sets the .subConverter according to the format of format:

>>> convObj = converter.Converter()
>>> convObj.setSubconverterFromFormat('humdrum')
>>> convObj.subConverter
<music21.converter.ConverterHumdrum object at 0x...>

Converter instance variables

Converter.subConverter

a ConverterXXX object that will do the actual converting.

ConverterMusicXML

class music21.converter.ConverterMusicXML(forceSource)

Converter for MusicXML

ConverterMusicXML read-only properties

ConverterMusicXML.stream

ConverterMusicXML methods

ConverterMusicXML.load()

Load all parts from a MusicXML object representation. This determines the order parts are found in the stream

ConverterMusicXML.parseData(xmlString, number=None)

Open MusicXML data from a string.

ConverterMusicXML.parseFile(fp, number=None)

Open from a file path; check to see if there is a pickled version available and up to date; if so, open that, otherwise open source.

ConverterMusicXML.partIdToNameDict()

ConverterHumdrum

class music21.converter.ConverterHumdrum

Simple class wrapper for parsing Humdrum data provided in a file or in a string.

ConverterHumdrum methods

ConverterHumdrum.parseData(humdrumString, number=None)

Open Humdrum data from a string

>>> humdata = '**kern\n*M2/4\n=1\n24r\n24g#\n24f#\n24e\n24c#\n24f\n24r\n24dn\n24e-\n24gn\n24e-\n24dn\n*-'
>>> c = converter.ConverterHumdrum()
>>> s = c.parseData(humdata)
ConverterHumdrum.parseFile(filepath, number=None)

Open Humdram data from a file path.

ArchiveManager

class music21.converter.ArchiveManager(fp, archiveType='zip')

Before opening a file path, this class can check if this is an archived file collection, such as a .zip or or .mxl file. This will return the data from the archive.

ArchiveManager methods

ArchiveManager.getData(name=None, dataFormat='musicxml')

Return data from the archive by name. If no name is given, a default may be available.

For ‘musedata’ format this will be a list of strings. For ‘musicxml’ this will be a single string.

ArchiveManager.getNames()

Return a list of all names contained in this archive.

ArchiveManager.isArchive()

Return True or False if the filepath is an archive of the supplied archiveType.

ConverterABC

class music21.converter.ConverterABC

Simple class wrapper for parsing ABC.

ConverterABC read-only properties

ConverterABC.stream

ConverterABC methods

ConverterABC.parseData(strData, number=None)

Get ABC data, as token list, from a string representation. If more than one work is defined in the ABC data, a Opus object will be returned; otherwise, a Score is returned.

ConverterABC.parseFile(fp, number=None)

Get MIDI data from a file path. If more than one work is defined in the ABC data, a Opus object will be returned; otherwise, a Score is returned.

If number is provided, and this ABC file defines multiple works with a X: tag, just the specified work will be returned.

ConverterCapella

class music21.converter.ConverterCapella

Simple class wrapper for parsing Capella .capx XML files. See capella/fromCapellaXML.

ConverterCapella read-only properties

ConverterCapella.stream

ConverterCapella methods

ConverterCapella.parseData(strData, number=None)

parse a data stream of uncompessed capella xml

N.B. for web parsing, it gets more complex.

ConverterCapella.parseFile(fp, number=None)

ConverterMidi

class music21.converter.ConverterMidi

Simple class wrapper for parsing MIDI.

ConverterMidi read-only properties

ConverterMidi.stream

ConverterMidi methods

ConverterMidi.parseData(strData, number=None)

Get MIDI data from a binary string representation.

Calls midi.translate.midiStringToStream.

ConverterMidi.parseFile(fp, number=None)

Get MIDI data from a file path.

Calls midi.translate.midiFilePathToStream.

ConverterMuseData

class music21.converter.ConverterMuseData

Simple class wrapper for parsing MuseData.

ConverterMuseData read-only properties

ConverterMuseData.stream

ConverterMuseData methods

ConverterMuseData.parseData(strData, number=None)

Get musedata from a string representation.

ConverterMuseData.parseFile(fp, number=None)

ConverterNoteworthy

class music21.converter.ConverterNoteworthy

Simple class wrapper for parsing NoteworthyComposer data provided in a file or in a string.

Gets data with the file format .nwctxt

Users should not need this routine. The basic format is

>>> nwcTranslatePath = common.getSourceFilePath() + os.path.sep + 'noteworthy'
>>> paertPath = converter.parse('d:/desktop/arvo_part_o_weisheit.nwctxt')
>>> paertStream = converter.parse(paertPath)
>>> len(paertStream.parts)
4

For developers: see the documentation for parseData() and parseFile() to see the low-level usage.

ConverterNoteworthy methods

ConverterNoteworthy.parseData(nwcData)

Open Noteworthy data from a string or list

>>> nwcData = "!NoteWorthyComposer(2.0)\n|AddStaff\n|Clef|Type:Treble\n|Note|Dur:Whole|Pos:1^"
>>> c = converter.ConverterNoteworthy()
>>> c.parseData(nwcData)
>>> c.stream.show('text')
{0.0} <music21.stream.Part ...>
    {0.0} <music21.stream.Measure 0 offset=0.0>
        {0.0} <music21.clef.TrebleClef>
        {0.0} <music21.note.Note C>
ConverterNoteworthy.parseFile(fp, number=None)

Open Noteworthy data (as nwctxt) from a file path.

>>> nwcTranslatePath = common.getSourceFilePath() + os.path.sep + 'noteworthy'
>>> paertPath = converter.parse('d:/desktop/arvo_part_o_weisheit.nwctxt')
>>> c = converter.ConverterNoteworthy()
>>> c.parseFile(filePath)
>>> c.stream.show()

ConverterNoteworthyBinary

class music21.converter.ConverterNoteworthyBinary

Simple class wrapper for parsing NoteworthyComposer binary data provided in a file or in a string.

Gets data with the file format .nwc

Users should not need this routine. Call converter.parse directly

ConverterNoteworthyBinary methods

ConverterNoteworthyBinary.parseData(nwcData)
ConverterNoteworthyBinary.parseFile(fp, number=None)

ConverterRomanText

class music21.converter.ConverterRomanText

Simple class wrapper for parsing roman text harmonic definitions.

ConverterRomanText read-only properties

ConverterRomanText.stream

ConverterRomanText methods

ConverterRomanText.parseData(strData, number=None)
ConverterRomanText.parseFile(fp, number=None)

ConverterTinyNotation

class music21.converter.ConverterTinyNotation

Simple class wrapper for parsing TinyNotation data provided in a file or in a string.

ConverterTinyNotation methods

ConverterTinyNotation.parseData(tnData, number=None)

Open TinyNotation data from a string or list

>>> tnData = ["E4 r f# g=lastG trip{b-8 a g} c", "3/4"]
>>> c = converter.ConverterTinyNotation()
>>> s = c.parseData(tnData)
ConverterTinyNotation.parseFile(fp, number=None)

Open TinyNotation data from a file path.

PickleFilter

class music21.converter.PickleFilter(fp, forceSource=False, number=None)

Before opening a file path, this class checks to see if there is an up-to-date version of the file pickled and stored in the scratch directory.

If the user has not specified a scratch directory, or if forceSource is True then a pickle path will not be created.

PickleFilter methods

PickleFilter.status()

Given a file path specified with __init__, look for an up to date pickled version of this file path. If it exists, return its fp, otherwise return the original file path.

Return arguments are file path to load, boolean whether to write a pickle, and the file path of the pickle.

Does not check that fp exists or create the pickle file.

>>> fp = '/Users/Cuthbert/Desktop/musicFile.mxl'
>>> pickfilt = converter.PickleFilter(fp)
>>> pickfilt.status()
('/Users/Cuthbert/Desktop/musicFile.mxl', True, '/var/folders/x5/rymq2tx16lqbpytwb1n_cc4c0000gn/T/music21/m21-18b8c5a5f07826bd67ea0f20462f0b8d.pgz')