nCoda Lychee Docs

LilyPond

Converts a LilyPond document to a Lychee-MEI document.

Warning

This module is intended for internal Lychee use only, so the API may change without notice. If you wish to use this module outside Lychee, please contact us to discuss the best way.

Tip

We recommend that you use the converters indirectly. Refer to How to Use the Converters for more information.

class lychee.converters.inbound.lilypond.ClefSpec(shape, line)
line

Alias for field number 1

shape

Alias for field number 0

lychee.converters.inbound.lilypond.add_tie(attrib)[source]

Given an attribute dictionary for an LMEI element, add a tie to it.

All tie attributes are initial at this stage of conversion. Medial and final tie attributes are fixed at the layer level.

lychee.converters.inbound.lilypond.check(condition, message=None)[source]

Check that condition is True.

Parameters:
  • condition (bool) – This argument will be checked to be True.
  • message (str) – A failure message to use if the check does not pass.
Raises:

exceptions.LilyPondError when condition is anything other than True.

Use this function to guarantee that something is the case. This function replaces the assert statement but is always executed (not only in debug mode).

Example 1

>>> check(5 == 5)

The 5 == 5 evaluates to True, so the function returns just fine.

Example 2

>>> check(5 == 4)

The 5 == 4 evaluates to False, so the function raises an exceptions.LilyPondError.

lychee.converters.inbound.lilypond.check_version(ly_version)[source]

Guarantees the version is at least somewhat compatible.

If the major version is not ‘2’, raises. If the minor version is other than ‘18’ or ‘19’, warns.

lychee.converters.inbound.lilypond.convert(document, user_settings=None, **kwargs)[source]

Convert a LilyPond document into an MEI document. This is the entry point for Lychee conversions.

Parameters:document (str) – The LilyPond document.
Returns:The corresponding MEI document.
Return type:xml.etree.ElementTree.Element or xml.etree.ElementTree.ElementTree
lychee.converters.inbound.lilypond.convert_no_signals(document, user_settings=None)[source]

It’s the convert() function that returns the converted document rather than emitting it with the CONVERSION_FINISHED signal. Mostly for testing.

lychee.converters.inbound.lilypond.do_chord(l_chord, m_layer, context=None)[source]

Convert a LilyPond chord to an LMEI <chord/>.

Parameters:
  • l_chord (dict) – The LilyPond chord from TatSu.
  • m_layer (lxml.etree.Element) – The MEI <layer> that will hold the chord.
Returns:

The new <chord/> element.

Return type:

lxml.etree.Element

Raises:

exceptions.LilyPondError if l_chord does not contain a TatSu chord

lychee.converters.inbound.lilypond.do_layer(l_layer, m_staff, layer_n, m_staffdef=None, context=None)[source]

Convert a LilyPond Voice context into an LMEI <layer> element.

Parameters:
  • l_layer (list of dict) – The LilyPond Voice context from TatSu.
  • m_staff (lxml.etree.Element) – The MEI <staff> that will hold the layer.
  • layer_n (int) – The @n attribute value for this <layer>.
  • m_staffdef – The initial <staffDef> for the containing staff. This is necessary to

correctly handle key and time signatures.

Returns:The new <layer> element.
Return type:lxml.etree.Element

If the Voice context contains an unknown node type, do_layer() emits a failure log message and continues processing the following nodes in the Voice context.

lychee.converters.inbound.lilypond.do_note(l_note, m_parent, context=None)[source]

Convert a LilyPond note to an LMEI <note/>.

Parameters:
  • l_note (dict) – The LilyPond note from TatSu.
  • m_parent (lxml.etree.Element) – The parent element that will hold the note, either a <layer/> or a <chord/>.
Returns:

The new <note/> element.

Return type:

lxml.etree.Element

Raises:

exceptions.LilyPondError if l_note does not contain a TatSu note

lychee.converters.inbound.lilypond.do_rest(l_rest, m_layer, context=None)[source]

Convert a LilyPond rest to an LMEI <rest/>.

Parameters:
  • l_rest (dict) – The LilyPond rest from TatSu.
  • m_layer (lxml.etree.Element) – The LMEI <layer> that will hold the rest.
Returns:

The new <rest/> element.

Return type:

lxml.etree.Element

Raises:

exceptions.LilyPondError if l_rest does not contain a TatSu rest

lychee.converters.inbound.lilypond.do_score(l_score, context=None)[source]

Convert a LilyPond score to an LMEI <section>.

Parameters:
  • context (dict) – Contains document-wide information such as language.
  • l_score (dict) – The LilyPond score as parsed by TatSu.
Returns:

A converted Lychee-MEI <section> element.

Return type:

lxml.etree.Element

lychee.converters.inbound.lilypond.do_spacer(l_spacer, m_layer, context=None)[source]

Convert a LilyPond spacer rest to an LMEI <space/>.

Parameters:
  • l_spacer (dict) – The LilyPond spacer rest from TatSu.
  • m_layer (lxml.etree.Element) – The LMEI <layer> that will hold the space.
Returns:

The new <space/> element.

Return type:

lxml.etree.Element

Raises:

exceptions.LilyPondError if l_spacer does not contain a TatSu spacer rest

lychee.converters.inbound.lilypond.do_staff(l_staff, m_section, m_staffdef, context=None)[source]
Parameters:
  • l_staff (dict) – The LilyPond Staff context from TatSu.
  • m_section (lxml.etree.Element) – The LMEI <section> that will hold the staff.
  • m_staffdef (lxml.etree.Element) – The LMEI <staffDef> used to define this staff.
Returns:

None

Raises:

exceptions.LilyPondError when the l_staff argument is not a staff.

Raises:

exceptions.LilyPondError when the m_staffdef argument does not have an @n attribute.

Note

This function assumes that the m_staffdef argument is already present in the score. That is, the <staffDef> does not become a child element of the <staff> in this function.

If the Staff context contains unknown staff settings, do_staff() emits a failure log message and continues processing the following settings and Voices in the Staff context.

The @n attribute is taken from the m_staffdef argument. If the @n attribute is missing, do_staff() raises exceptions.LilyPondError.

This function will use a single <staff> element whenever possible. However, each change between monophonic and polyphonic notation produces a new <staff> element. The following example shows a section with two staves; the second staff is split between two <staff> elements for technical reasons, but the @n attribute indicates they should be displayed as the same staff.

<section>
    <staff n="1"><!-- some content --></staff>
    <staff n="2"><!-- some monophonic content --></staff>
    <staff n="2"><!-- some polyphonic content --></staff>
</section>
lychee.converters.inbound.lilypond.fix_accidentals_in_layer(m_layer, m_staffdef)[source]

Using a model of LilyPond’s accidental rendering, fix the @accid/@accid.ges attributes and the temporary @accid.force attributes.

Limitations: doesn’t support key and time changes. Two different accidentals on the same note in the same chord may not be rendered correctly.

Parameters:
  • m_layer (lxml.etree.Element) – The LMEI <layer> object to fix.
  • m_staffdef – The initial <staffDef> settings for the containing staff. This is necessary

to propoerly handle initial settings of key signatures and time signatures. :type m_layer: lxml.etree.Element :returns: None

lychee.converters.inbound.lilypond.fix_slurs_in_layer(m_layer)[source]

Fix @slur attribute values in an LMEI <layer> element.

lychee.converters.inbound.lilypond.fix_ties_in_layer(m_layer)[source]

Fix @tie attribute values in an LMEI <layer> element.

lychee.converters.inbound.lilypond.has_tie(l_thing)[source]

Given a parsed LilyPond note/chord, determine whether it has a tie.

lychee.converters.inbound.lilypond.note_pitch(m_note)[source]

Return a tuple uniquely identifying the pitch of an LMEI node.

lychee.converters.inbound.lilypond.postprocess_staff(m_staff)[source]

Fixes @n in <staffDef> elements so it matches the containing <staff>.

Parameters:m_staff – The LMEI <staff>.
lychee.converters.inbound.lilypond.process_dots(l_node, attrib)[source]

Handle the @dots attribute for a chord, note, rest, or spacer rest.

Parameters:
  • l_node (dict) – The LilyPond node from TatSu.
  • attrib (dict) – The attribute dictionary that will be given to the Element constructor.
Returns:

The attrib dictionary.

Converts the “dots” member of l_node to the appropriate number in attrib. If there is no “dots” member in l_node, submit a “failure” log message and assume there are no dots.

lychee.converters.inbound.lilypond.process_octave(l_oct)[source]

Convert an octave specifier from the parsed LilyPond into an MEI @oct attribute.

Parameters:l_oct (str) – The “octave” part of the LilyPond note as provided by TatSu. May also be None.
Returns:The LMEI octave number.
Return type:str

If the octave is not recognized, process_octave() emits a failure log message and returns the same value as if l_oct were None.

lychee.converters.inbound.lilypond.process_pitch(l_note, note_attrib, accid_attrib, context=None)[source]

Set the pitch of an LMEI note.

Parameters:l_note – The LilyPond note as provided by TatSu. This function reads the keys ‘pitch_name’

and ‘accid_force’. :type l_note: dict :param dict note_attrib: The attributes for the MEI <note/> element before creation. :param dict accid_attrib: The attributes for the MEI <accid/> element before creation. :returns A tuple of the new note_attrib and accid_attrib.

lychee.converters.inbound.lilypond.process_slur(l_thing, attrib)[source]

Handle the @slur attribute for LilyPond nodes. Only emits initial and final slur attributes (medial is handled later), and does not process overlapping slurs.

lychee.converters.inbound.lilypond.set_clef(l_clef, m_staffdef, context=None)[source]

Set the clef for a staff.

Parameters:
  • l_time (dict) – The clef as parsed by TatSu.
  • m_staffdef (lxml.etree.Element) – The LMEI <staffDef> on which to set the clef.
Returns:

None

If the clef type is not recognized, set_initial_clef() emits a failure log message and does not set a clef.

lychee.converters.inbound.lilypond.set_instrument_name(l_name, m_staffdef, context=None)[source]

Set the instrument name for a staff.

Parameters:
  • l_name (dict) – The instrument name as parsed by TatSu.
  • m_staffdef (lxml.etree.Element) – The LMEI <staffDef> on which to set the instrument name.
Returns:

None

lychee.converters.inbound.lilypond.set_key(l_key, m_staffdef, context=None)[source]

Set the key signature for a staff.

Parameters:
  • l_key (dict) – The key specification as parsed by TatSu.
  • m_staffdef (lxml.etree.Element) – The LMEI <staffDef> on which to set the key signature.
Returns:

None

lychee.converters.inbound.lilypond.set_time(l_time, m_staffdef, context=None)[source]

Set the time signature for a staff.

Parameters:
  • l_time (dict) – The time specification as parsed by TatSu.
  • m_staffdef (lxml.etree.Element) – The LMEI <staffDef> on which to set the time signature.
Returns:

None