music21.converter.subConverters

SubConverters parse or display a single format.

Each subConverter should inherit from the base SubConverter object and have at least a parseData method that sets self.stream.

ConverterABC

class music21.converter.subConverters.ConverterABC(**keywords)

Simple class wrapper for parsing ABC.

Input only

ConverterABC bases

ConverterABC read/write properties

Read/write properties inherited from SubConverter:

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(filePath: Path | str, number: int | None = None, **keywords)

Get ABC 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 an X: tag, just the specified work will be returned.

Methods inherited from SubConverter:

ConverterBraille

class music21.converter.subConverters.ConverterBraille(**keywords)

ConverterBraille bases

ConverterBraille read/write properties

Read/write properties inherited from SubConverter:

ConverterBraille methods

ConverterBraille.show(obj, fmt, app=None, subformats=(), **keywords)

Write the data, then show the generated data, using .launch() or printing to a console.

Some simple formats that do not need launching, may skip .launch() and simply return the output.

ConverterBraille.write(obj, fmt, fp=None, subformats=(), **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterCapella

class music21.converter.subConverters.ConverterCapella(**keywords)

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

ConverterCapella bases

ConverterCapella read/write properties

Read/write properties inherited from SubConverter:

ConverterCapella methods

ConverterCapella.parseData(strData, number=None)

parse a data stream of uncompressed capella xml

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

ConverterCapella.parseFile(filePath: str | Path, number: int | None = None, **keywords)

Parse a Capella file

Methods inherited from SubConverter:

ConverterClercqTemperley

class music21.converter.subConverters.ConverterClercqTemperley(**keywords)

Wrapper for parsing harmonic definitions in Trevor de Clercq and David Temperley’s format.

ConverterClercqTemperley bases

ConverterClercqTemperley read/write properties

Read/write properties inherited from SubConverter:

ConverterClercqTemperley methods

ConverterClercqTemperley.parseData(strData: str | Path, number=None)

Called when a string (or binary) data is encountered.

This method MUST be implemented to do anything in parsing.

Return self.stream in the end

ConverterClercqTemperley.parseFile(filePath: Path | str, number=None, **keywords)

Called when a file is encountered. If all that needs to be done is loading the file and putting the data into parseData then there is no need to implement this method. Just set self.readBinary to True | False.

Methods inherited from SubConverter:

ConverterHumdrum

class music21.converter.subConverters.ConverterHumdrum(**keywords)

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

ConverterHumdrum bases

ConverterHumdrum read/write properties

Read/write properties inherited from SubConverter:

ConverterHumdrum methods

ConverterHumdrum.parseData(humdrumString, number=None)

Open Humdrum data from a string – calls parse().

>>> humData = ('**kern\n*M2/4\n=1\n24r\n24g#\n24f#\n24e\n24c#\n' +
...     '24f\n24r\n24dn\n24e-\n24gn\n24e-\n24dn\n*-')
>>> c = converter.subConverters.ConverterHumdrum()
>>> s = c.parseData(humData)
>>> c.stream.show('text')
{0.0} <music21.metadata.Metadata object at 0x7f33545027b8>
{0.0} <music21.stream.Part spine_0>
    {0.0} <music21.humdrum.spineParser.MiscTandem **kern>
    {0.0} <music21.stream.Measure 1 offset=0.0>
        {0.0} <music21.meter.TimeSignature 2/4>
        {0.0} <music21.note.Rest 1/6ql>
        {0.1667} <music21.note.Note G#>
        {0.3333} <music21.note.Note F#>
        {0.5} <music21.note.Note E>
        {0.6667} <music21.note.Note C#>
        {0.8333} <music21.note.Note F>
        {1.0} <music21.note.Rest 1/6ql>
        {1.1667} <music21.note.Note D>
        {1.3333} <music21.note.Note E->
        {1.5} <music21.note.Note G>
        {1.6667} <music21.note.Note E->
        {1.8333} <music21.note.Note D>
ConverterHumdrum.parseFile(filePath: Path | str, number: int | None = None, **keywords)

Open Humdrum data from a file path.

Calls humdrum.parseFile on filepath.

Number is ignored here.

Methods inherited from SubConverter:

ConverterIPython

class music21.converter.subConverters.ConverterIPython(**keywords)

Meta-subConverter for displaying image data in a Notebook using either png (via MuseScore or LilyPond) or directly via Vexflow/music21j, or MIDI using music21j.

ConverterIPython bases

ConverterIPython read/write properties

Read/write properties inherited from SubConverter:

ConverterIPython methods

ConverterIPython.show(obj, fmt, app=None, subformats=(), **keywords)

show a specialized for Jupyter Notebook using the appropriate subformat.

For MusicXML runs it through MuseScore and returns the PNG data. (use multipageWidget to get an experimental interactive page display).

For MIDI: loads a music21j-powered MIDI player in to the Notebook.

Methods inherited from SubConverter:

ConverterLilypond

class music21.converter.subConverters.ConverterLilypond(**keywords)

Convert to Lilypond and from there usually to png, pdf, or svg.

Note: that the proper format for displaying Lilypond in Jupyter notebook in v9 is ipython.lily.png and not lily.ipython.png

ConverterLilypond bases

ConverterLilypond read/write properties

Read/write properties inherited from SubConverter:

ConverterLilypond methods

ConverterLilypond.show(obj, fmt, app=None, subformats=(), **keywords)

Call .write (write out the lilypond (.ly) file; convert to .png/.pdf, etc.) then launch the appropriate viewer for .png/.pdf (graphicsPath) or .svg (vectorPath)

ConverterLilypond.write(obj, fmt, fp=None, subformats=(), *, coloredVariants: bool = False, **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterMEI

class music21.converter.subConverters.ConverterMEI(**keywords)

Converter for MEI. You must use an “.mei” file extension for MEI files because music21 will parse “.xml” files as MusicXML.

ConverterMEI bases

ConverterMEI read/write properties

Read/write properties inherited from SubConverter:

ConverterMEI methods

ConverterMEI.checkShowAbility(**keywords)

MEI export is not yet implemented.

ConverterMEI.parseData(dataString: str, number=None) → Stream

Convert a string with an MEI document into its corresponding music21 elements.

  • dataString: The string with XML to convert.

  • number: Unused in this class. Default is None.

Returns the music21 objects corresponding to the MEI file.

ConverterMEI.parseFile(filePath: str | Path, number: int | None = None, **keywords) → Stream

Convert a file with an MEI document into its corresponding music21 elements.

  • filePath: Full pathname to the file containing MEI data as a string or Path.

  • number: Unused in this class. Default is None.

Returns the music21 objects corresponding to the MEI file.

ConverterMEI.show(obj, fmt, app=None, subformats=(), **keywords)

Write the data, then show the generated data, using .launch() or printing to a console.

Some simple formats that do not need launching, may skip .launch() and simply return the output.

ConverterMEI.write(obj, fmt, fp=None, subformats=(), **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterMidi

class music21.converter.subConverters.ConverterMidi(**keywords)

Simple class wrapper for parsing MIDI and sending MIDI data out.

ConverterMidi bases

ConverterMidi read/write properties

Read/write properties inherited from SubConverter:

ConverterMidi methods

ConverterMidi.parseData(strData, number=None)

Get MIDI data from a binary string representation.

Calls midi.translate.midiStringToStream.

Keywords to control quantization: quantizePost controls whether to quantize the output. (Default: True) quarterLengthDivisors allows for overriding the default quantization units in defaults.quantizationQuarterLengthDivisors. (Default: (4, 3)).

ConverterMidi.parseFile(filePath: Path | str, number: int | None = None, **keywords)

Get MIDI data from a file path.

Calls midi.translate.midiFilePathToStream.

Keywords to control quantization: quantizePost controls whether to quantize the output. (Default: True) quarterLengthDivisors allows for overriding the default quantization units in defaults.quantizationQuarterLengthDivisors. (Default: (4, 3)).

ConverterMidi.write(obj, fmt, fp=None, subformats=(), *, addStartDelay: bool = False, **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterMuseData

class music21.converter.subConverters.ConverterMuseData(**keywords)

Simple class wrapper for parsing MuseData.

ConverterMuseData bases

ConverterMuseData read/write properties

Read/write properties inherited from SubConverter:

ConverterMuseData methods

ConverterMuseData.parseData(strData, number=None)

Get musedata from a string representation.

ConverterMuseData.parseFile(filePath: str | Path, number: int | None = None, **keywords)

parse fp (a pathlib.Path()) and number

Methods inherited from SubConverter:

ConverterMusicXML

class music21.converter.subConverters.ConverterMusicXML(**keywords)

Converter for MusicXML using the 2015 ElementTree system.

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

ConverterMusicXML bases

ConverterMusicXML read/write properties

Read/write properties inherited from SubConverter:

ConverterMusicXML methods

ConverterMusicXML.parseData(xmlString: str, number=None)

Open MusicXML data from a string.

ConverterMusicXML.parseFile(filePath: str | Path, number: int | None = None, **keywords)

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.show(obj, fmt, app=None, subformats=(), **keywords)

Override to do something with png

ConverterMusicXML.write(obj: music21.Music21Object, fmt, fp=None, subformats=(), *, makeNotation=True, compress: bool | None = None, **keywords)

Write to a .musicxml file.

Set makeNotation=False to prevent fixing up the notation, and where possible, to prevent making additional deepcopies. (This option cannot be used if obj is not a Score.) makeNotation=True generally solves common notation issues, whereas makeNotation=False is intended for advanced users facing special cases where speed is a priority or making notation reverses user choices.

Set compress=True to immediately compress the output to a .mxl file. Set to True automatically if format=’mxl’ or if fp is given and ends with .mxl

ConverterMusicXML.writeDataStream(fp, dataStr: str | bytes, **keywords) → Path

Writes dataStr which must be bytes to fp. Adds .musicxml suffix to fp if it does not already contain some suffix.

  • Changed in v7: returns a pathlib.Path

Methods inherited from SubConverter:

ConverterNoteworthy

class music21.converter.subConverters.ConverterNoteworthy(**keywords)

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 converter.parse(‘file.nwctxt’)

>>> paertPath = converter.parse(r'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 bases

ConverterNoteworthy read/write properties

Read/write properties inherited from SubConverter:

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.subConverters.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(filePath: Path | str, number: int | None = None, **keywords)

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

>>> paertPath = converter.parse('d:/desktop/arvo_part_o_weisheit.nwctxt')
>>> c = converter.subConverters.ConverterNoteworthy()
>>> c.parseFile(filePath)
>>> c.stream.show()

Methods inherited from SubConverter:

ConverterNoteworthyBinary

class music21.converter.subConverters.ConverterNoteworthyBinary(**keywords)

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 bases

ConverterNoteworthyBinary read/write properties

Read/write properties inherited from SubConverter:

ConverterNoteworthyBinary methods

ConverterNoteworthyBinary.parseData(nwcData)

Called when a string (or binary) data is encountered.

This method MUST be implemented to do anything in parsing.

Return self.stream in the end

ConverterNoteworthyBinary.parseFile(filePath: Path | str, number: int | None = None, **keywords)

Called when a file is encountered. If all that needs to be done is loading the file and putting the data into parseData then there is no need to implement this method. Just set self.readBinary to True | False.

Methods inherited from SubConverter:

ConverterRomanText

class music21.converter.subConverters.ConverterRomanText(**keywords)

Simple class wrapper for parsing roman text harmonic definitions.

ConverterRomanText bases

ConverterRomanText read/write properties

Read/write properties inherited from SubConverter:

ConverterRomanText methods

ConverterRomanText.parseData(strData, number=None)

Called when a string (or binary) data is encountered.

This method MUST be implemented to do anything in parsing.

Return self.stream in the end

ConverterRomanText.parseFile(filePath: Path | str, number: int | None = None, **keywords)

Called when a file is encountered. If all that needs to be done is loading the file and putting the data into parseData then there is no need to implement this method. Just set self.readBinary to True | False.

ConverterRomanText.write(obj, fmt, fp=None, subformats=(), **keywords)

Writes ‘RomanText’ files (using the extension .rntxt) from a music21.stream.

Methods inherited from SubConverter:

ConverterScala

class music21.converter.subConverters.ConverterScala(**keywords)

ConverterScala bases

ConverterScala read/write properties

Read/write properties inherited from SubConverter:

ConverterScala methods

Methods inherited from SubConverter:

ConverterText

class music21.converter.subConverters.ConverterText(**keywords)

standard text presentation has line breaks, is printed.

Two keyword options are allowed: addEndTimes=Boolean and useMixedNumerals=Boolean

ConverterText bases

ConverterText read/write properties

Read/write properties inherited from SubConverter:

ConverterText methods

ConverterText.show(obj, fmt, app=None, subformats=(), **keywords)

Write the data, then show the generated data, using .launch() or printing to a console.

Some simple formats that do not need launching, may skip .launch() and simply return the output.

ConverterText.write(obj, fmt, fp=None, subformats=(), **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterTextLine

class music21.converter.subConverters.ConverterTextLine(**keywords)

a text line compacts the complete recursive representation into a single line of text; most for debugging. returned, not printed

>>> s = corpus.parse('bwv66.6')
>>> s.measures(1, 4).show('textline')
"{0.0} <music21.stream.Part Soprano> / {0.0} <music21.instrument.Instrument '... 1'>..."

ConverterTextLine bases

ConverterTextLine read/write properties

Read/write properties inherited from SubConverter:

ConverterTextLine methods

ConverterTextLine.show(obj, fmt, app=None, subformats=(), **keywords)

Write the data, then show the generated data, using .launch() or printing to a console.

Some simple formats that do not need launching, may skip .launch() and simply return the output.

ConverterTextLine.write(obj, fmt, fp=None, subformats=(), **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterTinyNotation

class music21.converter.subConverters.ConverterTinyNotation(**keywords)

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

Input only for now.

ConverterTinyNotation bases

ConverterTinyNotation read/write properties

Read/write properties inherited from SubConverter:

ConverterTinyNotation methods

ConverterTinyNotation.parseData(tnData, number=None)

Open TinyNotation data from a string

>>> tnData = "3/4 E4 r f# g=lastG trip{b-8 a g} c"
>>> c = converter.subConverters.ConverterTinyNotation()
>>> s = c.parseData(tnData)
>>> c.stream.show('text')
{0.0} <music21.stream.Measure 1 offset=0.0>
    {0.0} <music21.clef.TrebleClef>
    {0.0} <music21.meter.TimeSignature 3/4>
    {0.0} <music21.note.Note E>
    {1.0} <music21.note.Rest quarter>
    {2.0} <music21.note.Note F#>
{3.0} <music21.stream.Measure 2 offset=3.0>
    {0.0} <music21.note.Note G>
    {1.0} <music21.note.Note B->
    {1.3333} <music21.note.Note A>
    {1.6667} <music21.note.Note G>
    {2.0} <music21.note.Note C>
    {2.5} <music21.bar.Barline type=final>

Methods inherited from SubConverter:

ConverterVexflow

class music21.converter.subConverters.ConverterVexflow(**keywords)

ConverterVexflow bases

ConverterVexflow read/write properties

Read/write properties inherited from SubConverter:

ConverterVexflow methods

ConverterVexflow.write(obj, fmt, fp=None, subformats=(), *, local: bool = False, **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

ConverterVolpiano

class music21.converter.subConverters.ConverterVolpiano(**keywords)

Reads or writes volpiano (Chant encoding).

Normally, just use ‘converter’ and .show()/.write()

>>> p = converter.parse('volpiano: 1---c-d-ef----4')
>>> p.show('text')
{0.0} <music21.stream.Measure 0 offset=0.0>
    {0.0} <music21.clef.TrebleClef>
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note D>
    {2.0} <music21.note.Note E>
    {3.0} <music21.note.Note F>
    {4.0} <music21.volpiano.Neume <music21.note.Note E><music21.note.Note F>>
    {4.0} <music21.bar.Barline type=double>
>>> p.show('volpiano')
1---c-d-ef----4

ConverterVolpiano bases

ConverterVolpiano read/write properties

Read/write properties inherited from SubConverter:

ConverterVolpiano methods

ConverterVolpiano.getDataStr(obj, **keywords)

Get the raw data, for storing as a variable.

ConverterVolpiano.parseData(dataString, number: int | None = None, *, breaksToLayout: bool = False, **keywords)

Called when a string (or binary) data is encountered.

This method MUST be implemented to do anything in parsing.

Return self.stream in the end

ConverterVolpiano.show(obj, fmt, app=None, subformats=(), **keywords)

Write the data, then show the generated data, using .launch() or printing to a console.

Some simple formats that do not need launching, may skip .launch() and simply return the output.

ConverterVolpiano.write(obj, fmt, fp=None, subformats=(), **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

Methods inherited from SubConverter:

SubConverter

class music21.converter.subConverters.SubConverter(**keywords)

Class wrapper for parsing data or outputting data.

All other Converter types should inherit from this and have ways of dealing with various data formats.

Attributes that should be set:

readBinary = True or False (default False)
registerFormats = tuple of formats that can be handled; eg: ('musicxml',)
registerShowFormats = tuple of format calls that can be handled in .show() and .write()
registerInputExtensions = tuple of input extensions that should be handled in converter
registerOutputExtensions = tuple of output extensions that can be written. Order matters:
    the first will be used in calls to .write()
canBePickled = True or False (default True; does not do anything yet)
codecWrite = True or False (default False) if encodings need to be used to write
stringEncoding = string (default 'utf-8'). If codecWrite is True, this specifies what
    encoding to use

SubConverter read/write properties

SubConverter.stream

Returns or sets the stream in the converter. Must be defined for subConverter to work.

SubConverter methods

SubConverter.checkShowAbility(**keywords) → bool

return bool on whether the system is equipped to show in this format.

Default True. Might be False if, say a Lilypond converter is used and Lilypond is not installed.

SubConverter.getExtensionForSubformats(subformats: Iterable[str] = ()) → str

Given a default format or subformats, give the file extension it should have:

>>> c = converter.subConverters.ConverterMidi()
>>> c.getExtensionForSubformats()
'.mid'
SubConverter.getTemporaryFile(subformats: Iterable[str] = ()) → pathlib.Path

Return a temporary file with an extension appropriate for the format.

>>> c = corpus.parse('bwv66.6')
>>> lpConverter = converter.subConverters.ConverterLilypond()
>>> tf = str(lpConverter.getTemporaryFile(subformats=['png']))
>>> tf.endswith('.png')
True

  • Changed in v6: returns pathlib.Path

SubConverter.launch(filePath: Path, fmt=None, options: str = '', app: str | None = None, launchKey=None)

Opens the appropriate viewer for the file generated by .write()

app is the path to an application to launch. Specify it and/or a launchKey. launchKey is the specific key in .music21rc (such as graphicsPath), etc. to search for the application. If it’s not specified then there might be a default one for the converter in self.launchKey. If it can’t find it there then environLocal.formatToApp(fmt) will be used.

Not needed for formats for which .show() just prints to the console.

SubConverter.parseData(dataString, number: int | None = None)

Called when a string (or binary) data is encountered.

This method MUST be implemented to do anything in parsing.

Return self.stream in the end

SubConverter.parseFile(filePath: str | Path, number: int | None = None, **keywords)

Called when a file is encountered. If all that needs to be done is loading the file and putting the data into parseData then there is no need to implement this method. Just set self.readBinary to True | False.

SubConverter.show(obj, fmt: str | None, app=None, subformats=(), **keywords) → None

Write the data, then show the generated data, using .launch() or printing to a console.

Some simple formats that do not need launching, may skip .launch() and simply return the output.

SubConverter.toData(obj, fmt: str | None, subformats: Iterable[str] = (), **keywords) → str | bytes

Write the object out in the given format and then read it back in and return the object (str or bytes) returned.

SubConverter.write(obj: music21.base.Music21Object, fmt: str | None, fp: str | pathlib.Path | IOBase | None = None, subformats: Iterable[str] = (), **keywords)

Calls .writeDataStream on the repr of obj, and returns the fp returned by it.

SubConverter.writeDataStream(fp: str | Path | IOBase | None, dataStr: str | bytes, **keywords) → Path

Writes the data stream to fp or to a temporary file and returns the Path object of the filename written.