nCoda Lychee Docs

External Format Converters

An external format converter changes the symbolic representation of musical data. Inbound converters produce a Lychee-MEI document as an lxml.etree.Element object, while outbound converters consume a Lychee-MEI Element and produce data in an external format. Some outbound converters produce non-musical data, like vcs_outbound, which effectively serializes version control data from Mercurial into a JSON object.

At the moment, most of the format converters are incomplete, and therefore do not accept all possible documents. In addition, we intend to supplement these with more formats in the future.

Converter Module Interface

To maximize flexibility, each converter module is designed in the way most suitable for the module author, and exposes only the convert() function described here. This allows different programming paradigms and, more importantly, the use of external libraries.

convert(document, **kwargs)

Convert any part of a document into the corresponding document portion in another format.

Parameters:
  • document – For inbound converters this is the document (portion) in an external format, usually a string. For outbound converters this is the Lychee-MEI document (portion), usually an lxml.etree.Element. Refer to each module for its expected argument type.
  • kwargs – Additional keyword arguments must be accepted and must be ignored.
Returns:

The corresponding document (portion) after conversion.

Return type:

For inbound converters, this must be an lxml.etree.Element. For outbound converters, this is usually a string. Refer to each module for the return type.

Raises:

Not yet decided.

This function should accept the smallest and largest portions of notation that can reasonably be thought of as “one document” or “part of one document,” and produce the corresponding output without guessing or removing context. For example, two complete musical scores is not acceptable. A single note should probably be accepted, but a single accidental (not attached to a note) is probably too small.

The allowable document portions varies between converters, depending on the needs of the two data formats involved. In addition, a “round trip” conversion may not result in an identical document. For example, an LMEI <measure> converted to LilyPond and back to LMEI is unlikely to result in an LMEI <measure>. Consider the LilyPond snippet fis4 gis4 a2 | which does end with a bar-check symbol, but it’s not clear whether this should be one measure in 4/4 meter, two measures in 2/4 meter, or something else. The LilyPond-to-LMEI converter therefore should not assume the snippet is a <measure>. It is still reasonable to include a <barLine> element at the end.

Note

Some converter modules do not comply with this interface yet.

How to Use the Converters

If you are using a converter from outside Lychee:

  1. Use the converter’s convert() function.
  2. If you must use another part of the converter, including by copying and reusing code, we recommend contacting the converter’s author in order to find a mutually beneficial way to manage this situation.

If you are a Lychee developer:

  1. If you are working on a converters submodule, you should prefer to use other converters via their convert() function, but you may use any function if required.
  2. If you are working on the lychee.workflow.steps module, use convert() only. If this isn’t possible, there is a design problem that should be discussed and solved so that convert() can be used.
  3. If you are working on another module, you should use a function in the steps module. If this isn’t possible, there is a design problem that should be discussed and solved so the steps module can be used.

Converter Modules

Note

The dictionaries may be changed before version 1.0.

lychee.converters.INBOUND_CONVERTERS = {'abjad': <function convert at 0x2b6a1d0d19b0>, 'lilypond': <function convert at 0x2b6a1d178938>, 'mei': <function convert at 0x2b6a1d1a99b0>}

Mapping from the lowercase name of an inbound converter format to the convert() function that converts from that format to Lychee-MEI.

lychee.converters.OUTBOUND_CONVERTERS = {'abjad': <function convert at 0x2b6a1d1bc398>, 'document': <function convert at 0x2b6a1d1c6d70>, 'lilypond': <function convert at 0x2b6a1d1cb668>, 'mei': <function convert at 0x2b6a1d1cbc08>, 'python': <function convert at 0x2b6a1d1df1b8>, 'vcs': <function convert at 0x2b6a1d1bcde8>, 'verovio': <function convert at 0x2b6a1d1d7f50>}

Mapping from the lowercase name of an outbound converter format to the convert() function that converts from Lychee-MEI into hat format.

Inbound Converters