ly.musicxml package

Module contents

MusicXML functionality.

This subpackage is created to convert LilyPond text to MusicXML with the help of the tree structure created by ly.music. But it is constructed in such a way that you can use some of the submodules for generic MusicXML creation and manipulation.

ly.musicxml.writer()

Convert LilyPond text to MusicXML

Example:

import ly.musicxml
e = ly.musicxml.writer()
e.parse_text(lilypond_text)
xml = e.musicxml()
xml.write(filename)         # or: xml.tostring()
# xml.tree is the ElementTree xml tree.

Submodules

ly.musicxml.create_musicxml module

Uses xml.etree to create a Music XML document.

Example:

musxml = create_musicxml.CreateMusicXML()
musxml.create_part()
musxml.create_measure(divs=1)
musxml.new_note('C', 4, 'whole', 4)
xml = musxml.musicxml()
xml.write(filename)

class ly.musicxml.create_musicxml.CreateMusicXML

Bases: object

Creates the XML nodes according to the Music XML standard.

add_accidental(alter, caut=False, parenth=False)

Create accidental.

add_articulations()

Common function for creating all types of articulations.

add_backup(duration)

add_bar_style(multirest=None)

add_barline(bl_type, repeat=None)

add_beam(nr, beam_type)

Add beam.

add_chord()

add_clef(sign, line, nr=0, oct_ch=0)

add_creator(creator, name)

Add creator to score info.

add_direction(pos='above')

add_dirwords(words)

Add words in direction, e. g. a tempo mark.

add_div_duration(divdur)

Create new duration

add_divisions(div)

add_dot()

Create a dot

add_duration_type(durtype)

Create new type

add_dynamic_dashes(text)

Add dynamics dashes.

add_dynamic_mark(dyn)

Add specified dynamic mark.

add_dynamic_text(text)

Add dynamic text.

add_dynamic_wedge(wedge_type)

Add dynamic wedge/hairpin.

add_fingering(finger_nr)

add_gliss(linetype, endtype, nr)

add_grace(slash)

Create grace node

add_key(key, mode)

add_lyric(txt, syll, nr, ext=False)

Add lyric element.

add_mark(mark)

Add rehearsal mark in direction

add_metron_dir(unit, beats, dots)

add_mordent()

add_named_artic(artic)

Add articulation with specified name.

add_named_notation(notate)

Fermata, etc.

add_notations()

add_octave_shift(plac, octdir, size)

Add octave shift.

add_ornaments()

add_pitch(step, alter, octave)

Create new pitch.

add_prall()

add_rest()

Create rest.

add_rest_w_pos(step, octave)

Create rest with display position.

add_rights(rights, type=None)

Add rights to score info.

add_skip(duration, forward=True)

add_slur(nr, sl_type)

Add slur.

add_sound_dir(midi_tempo)

add_staff(staff)

add_staves(staves)

add_technical()

add_tie(tie_type)

Create node tie (used for sound of tie)

add_tied(tie_type)

Create node tied (used for notation of tie)

add_time(timesign)

add_time_modify(fraction)

Create time modification

add_tremolo(trem_type, lines)

add_trill()

add_tuplet_type(nr, ttype, actnr=0, acttype='', normnr=0, normtype='')

Create tuplet with type attribute

add_turn()

add_unpitched(step, octave)

Create unpitched.

add_voice(voice)

add_wavyline(end_type)

adjust_time_modify(timemod_node, fraction)

Adjust existing time-modification node.

change_div_duration(newdura)

Set new duration when tuplet

create_bar_attr()

Create node attributes

create_measure(pickup=False, **bar_attrs)

Create new measure

create_new_node(parentnode, nodename, txt)

The Music XML language is extensive. This function can be used to create a non basic node not covered elsewhere in this script.

TODO: add attributes

create_note()

Create new note.

create_part(name='unnamed', abbr=False, midi=False)

Create a new part

create_partgroup(gr_type, num, name=None, abbr=None, symbol=None)

Create a new part group.

create_score_info(tag, info, attr={})

Create score info.

create_tempo(words, metronome, sound, dots)

create_title(title)

Create score title.

get_time_modify()

Check if time-modification node already exists.

musicxml(prettyprint=True)

new_adv_ornament(ornament, args)

Add more complex ornament.

new_articulation(artic)

Add specified articulation.

new_bar_attr(clef=0, mustime=0, key=None, mode=0, divs=0, multirest=0)

Create all bar attributes set.

new_note(step, octave, durtype, divdur, alter=0, acc_token=0, voice=1, dot=0, chord=0, grace=(0, 0), stem_dir=0)

Create all nodes needed for a normal note.

new_rest(duration, durtype, pos, dot, voice)

Create all nodes needed for a rest.

new_simple_ornament(ornament)

Add specified ornament.

new_system(force_break)

new_unpitched_note(step, octave, durtype, divdur, voice=1, dot=0, chord=0, grace=(0, 0))

Create all nodes needed for an unpitched note.

set_stem_dir(dir)

tie_note(tie_type)

tuplet_note(fraction, bs, ttype, nr, divs, atyp='', ntyp='')

Convert current note to tuplet

class ly.musicxml.create_musicxml.MusicXML(tree)

Bases: object

Represent a generated MusicXML tree.

indent(indent='  ')

Add indent and linebreaks to the created XML tree.

tostring(encoding='UTF-8')

Output etree as a XML document.

write(file, encoding='UTF-8', doctype=True)

Write XML to a file (file obj or filename).

ly.musicxml.create_musicxml.get_tag_index(node, tag)

Return the (first) index of tag in node.

If tag is not found, -1 is returned.

ly.musicxml.ly2xml_mediator module

The information of the parsed source is organised into an object structure with help of the classes in ly.musicxml.xml_objs.

class ly.musicxml.ly2xml_mediator.Mediator

Bases: object

Help class that acts as mediator between the ly source parser and the XML creating modules.

add_break()

add_snippet(snippet_name)

Adds snippet to previous barlist. A snippet can be shorter than a full bar, so this can also mean continuing a previous bar.

add_staff_id(staff_id)

add_to_bar(obj)

bijective(n)

encodes an int to a sequence of letters

calc_tupl_den(tfraction, length)

Calculate the tuplet denominator from fraction and duration of tuplet.

change_group_bracket(system_start)

change_to_tuplet(tfraction, ttype, nr, length=None)

Change the current note into a tuplet note.

change_tuplet_type(index, newtype)

check_current_note(rel=False, rest=False, is_unpitched=False)

Perform checks common for all new notes and rests.

check_divs()

The new duration is checked against current divisions

check_duration(rest)

Check the duration for the current note.

check_lyrics(voice_id)

Check the finished lyrics section and merge it into the referenced voice.

check_name(name, nr=1)

check_part()

Adds the latest active section to the part.

check_score()

Check score

If no part were created, place first variable (fallback) as part.

Apply the latest global section.

check_simultan()

Check done after simultanoues (<< >>) section.

check_voices()

Checks active sections. The two latest created are merged. Also checks for empty sections.

check_voices_by_nr()

Used for snippets. Merges all active snippets created after the stored voice number.

chord_end()

Actions when chord is parsed.

clear_chord()

close_group()

copy_barnote_basics(bar_note)

Create a copy of a xml_objs.BarNote.

copy_prev_chord(duration)

create_barline(bl)

create_barnote_from_note(note)

Create a xml_objs.BarNote from ly.music.items.Note.

create_unpitched(unpitched)

Create a xml_objs.Unpitched from ly.music.items.Unpitched.

do_action_onnext(note)

Perform the stored action on the next note.

duration_from_tokens(tokens)

Calculate dots and multibar rests from tokens.

end_gliss(note, line)

get_first_var()

get_part_by_id(pid, partholder=None)

get_var_byname(name)

increase_bar_dura(duration)

new_articulation(art_token)

An articulation, fingering, string number, or other symbol.

Grouped as articulations, ornaments, technical and others.

new_bar(fill_prev=True)

new_chord(note, duration=None, rel=False, chord_base=True)

new_chord_grace(slash=0)

new_chordbase(note, duration, rel=False)

new_chordnote(note, rel)

new_clef(clefname)

new_duration_token(token, tokens)

new_dynamics(dynamics)

new_gliss(line=None)

new_grace(slash=0)

new_group()

new_header_assignment(name, value)

Distributing header information.

new_iso_dura(note, rel=False, is_unpitched=False)

Isolated durations in music sequences.

An isolated duration in LilyPond is rendered as a normal note but the pitch information is missing and has to be filled in by some other means, usually by the previous pitch. (RhythmicStaff is an exception since it ignores specified pitches anyway).

new_key(key_name, mode)

new_lyric_nr(num)

new_lyric_section(name, voice_id)

new_lyrics_item(item)

new_lyrics_text(txt)

new_mark(num_mark=None)

new_note(note, rel=False, is_unpitched=False)

new_ottava(octdiff)

new_part(pid=None, to_part=None, piano=False)

new_repeat(rep)

new_rest(rest)

new_section(name, glob=False)

new_snippet(name)

new_tempo(unit, dur_tokens, tempo, string)

new_time(num, den, numeric=False)

new_trill_spanner(end=None)

new_word(word)

note2rest()

Note used as rest position transformed to rest.

part_not_empty()

revert_voicenr()

scale_rest(bs)

create multiple whole bar rests

sections

default and initial values

set_by_property(prprty, value, group=False)

Generic setter for different properties.

set_groupabbr(abbr)

set_groupname(name)

set_mult_rest()

set_mult_rest_bar(dur)

add multiple-rest attribute to bar

set_octave(relative)

Set octave by getting the octave of an absolute note + 3.

set_ottava(note, plac, octdir, size)

set_partabbr(abbr)

set_partmidi(midi)

set_partname(name)

set_pickup()

set_relative(note)

set_slur(nr, slur_type, phrasing=False)

Set the slur start or stop for the current note. phrasing should be set to True if the slur is meant to be a phrasing mark.

set_staffnr(staffnr, staff_id=None)

set_tremolo(trem_type='single', duration=0, repeats=0)

set_tuplspan_dur(token=None, tokens=None, fraction=None)

Catch duration set by the tupletSpannerDuration property.

Set the fraction directly or calculate it from tokens.

set_voicenr(command=None, add=False, nr=0, piano=0)

stem_direction(direction)

tie_to_next()

unset_tuplspan_dur()

Reset tuplet duration sum and tuplet spanner duration.

ly.musicxml.ly2xml_mediator.artic_token2xml_name(art_token)

From Articulations in ly.music.items. Grouped as articulations, ornaments and others.

To add an articulation look up the name or abbreviation in LilyPond and the corresponding node name in musicXML. Add it to the python dictionary below.

ly.musicxml.ly2xml_mediator.calc_trem_dur(repeats, base_scaling, duration)

Calculate tremolo duration from number of repeats and initial duration.

ly.musicxml.ly2xml_mediator.clefname2clef(clefname)

To add a clef look up the clef name in LilyPond and the corresponding definition in musicXML. Add it to the python dictionary below.

ly.musicxml.ly2xml_mediator.durval2type(durval)

Convert LilyPond duration to MusicXML duration type.

ly.musicxml.ly2xml_mediator.getNoteName(index)

ly.musicxml.ly2xml_mediator.get_fifths(key, mode)

ly.musicxml.ly2xml_mediator.get_group_symbol(lily_sys_start)

ly.musicxml.ly2xml_mediator.get_line_style(style)

ly.musicxml.ly2xml_mediator.get_mult(num, den)

ly.musicxml.ly2xml_mediator.get_voice(c)

ly.musicxml.ly2xml_mediator.get_xml_alter(alter)

Convert alter to the specified format, i e int if it’s int and float otherwise. Also multiply with 2.

ly.musicxml.lymus2musxml module

Using the tree structure from ly.music to initiate the conversion to MusicXML.

Uses functions similar to ly.music.items.Document.iter_music() to iter through the node tree. But information about where a node branch ends is also added. During the iteration the information needed for the conversion is captured.

class ly.musicxml.lymus2musxml.End(node)

Bases: object

Extra class that gives information about the end of Container elements in the node list.

class ly.musicxml.lymus2musxml.ParseSource

Bases: object

creates the XML-file from the source code according to the Music XML standard

Articulation(art)

An articulation, fingering, string number, or other symbol.

Assignment(a)

Variables should already have been substituted so this need only cover other types of assignments.

Beam(beam)

Change(change)

A change music expression. Changes the staff number.

Chord(chord)

ChordMode(chordmode)

A chordmode or chords expression.

Clef(clef)

Clef clef

Command(command)

bar, rest etc

Context(context)

context

DrumMode(drummode)

A drummode or drums expression.

If the shorthand form drums is found, DrumStaff is implicit.

DrumNote(drumnote)

A note in DrumMode.

Duration(duration)

A written duration

Dynamic(dynamic)

Any dynamic symbol.

End(end)

FigureMode(figmode)

A figuremode or figures expression.

Grace(grace)

KeySignature(key)

LyricItem(lyrics_item)

Another lyric item (skip, extender, hyphen or tie).

LyricMode(lyricmode)

A lyricmode, lyrics or addlyrics expression.

LyricText(lyrics_text)

A lyric text (word, markup or string), with a Duration.

LyricsTo(lyrics_to)

A lyricsto expression.

Markup(markup)

MarkupList(markuplist)

MarkupWord(markupWord)

MusicList(musicList)

Note(note)

notename, e.g. c, cis, a bes …

NoteMode(notemode)

A notemode or notes expression.

Number(number)

Override(override)

An override command.

Partial(partial)

PathItem(item)

An item in the path of an override or revert command.

PhrasingSlur(phrslur)

A ( or ).

PipeSymbol(barcheck)

PipeSymbol = |

Postfix(postfix)

Q(q)

Relative(relative)

A relative music expression.

Repeat(repeat)

Rest(rest)

rest, r or R. Note: NOT by command, i.e. rest

Scaler(scaler)

times tuplet scaleDurations

Scheme(scheme)

A Scheme expression inside LilyPond.

SchemeItem(item)

Any scheme token.

SchemeQuote(quote)

A ‘ in scheme.

Set(cont_set)

A set command.

Skip(skip)

invisible rest/spacer rest (s or command skip)

Slur(slur)

Slur, ‘(’ = start, ‘)’ = stop.

String(string)

Tempo(tempo)

Tempo direction, e g ‘4 = 80’

Tie(tie)

tie ~

TimeSignature(timeSign)

Tremolo(tremolo)

A tremolo item “:”.

Unpitched(unpitched)

A note without pitch, just a standalone duration.

UserCommand(usercommand)

Music variables are substituted so this must be something else.

VoiceSeparator(voice_sep)

With(cont_with)

A with … construct.

check_context(context, context_id=None, token='')

Check context and do appropriate action (e.g. create new part).

check_note(note)

Generic check for all notes, both pitched and unpitched.

check_tuplet()

Generic tuplet check.

find_score_sub(doc)

Find substitute for scorenode. Takes first music node that isn’t an assignment.

gen_med_caller(func_name, *args)

Call any function in the mediator object.

get_previous_node(node)

Returns the nodes previous node or false if the node is first in its branch.

get_score(node)

Returns (first) Score node or false if no Score is found.

iter_header(tree)

Iter only over header nodes.

iter_score(scorenode, doc)

Iter over score.

Similarly to items.Document.iter_music user commands are substituted.

Furthermore repeat unfold expressions are unfolded.

look_ahead(node, find_node)

Looks ahead in a container node and returns True if the search is successful.

look_behind(node, find_node)

Looks behind on the parent node(s) and returns True if the search is successful.

musicxml(prettyprint=True)

parse_document(ly_doc, relative_first_pitch_absolute=False)

Parse the LilyPond source specified as a ly.document document.

If relative_first_pitch_absolute is set to True, the first pitch in a

elative expression without startpitch is considered to be absolute

(LilyPond 2.18+ behaviour).

parse_nodes(nodes)

Work through all nodes by calling the function with the same name as the nodes class.

parse_text(ly_text, filename=None)

Parse the LilyPond source specified as text.

If you specify a filename, it can be used to resolve include commands correctly.

parse_tree(mustree)

Parse the LilyPond source as a ly.music node tree.

simple_node_gen(node)

Unlike iter_score are the subnodes yielded without substitution.

unfold_repeat(repeat_node, repeat_count, doc)

Iter over node which represent a repeat unfold expression and do the unfolding directly.

ly.musicxml.xml_objs module

Classes that holds information about a musical score, suitable for converting to musicXML.

When the score structure is built, it can easily be used to create a musicXML.

Example:

from ly.musicxml import create_musicxml, xml_objs

musxml = create_musicxml.CreateMusicXML()

score = xml_objs.Score()
part = xml_objs.ScorePart()
score.partlist.append(part)
bar = xml_objs.Bar()
part.barlist.append(bar)
ba = xml_objs.BarAttr()
ba.set_time([4,4])
bar.obj_list.append(ba)
c = xml_objs.BarNote('c', 0, 0, (1,1))
c.set_octave(4)
c.set_durtype(1)
bar.obj_list.append(c)

xml_objs.IterateXmlObjs(score, musxml, 1)
xml = musxml.musicxml()
xml.write(filename)

class ly.musicxml.xml_objs.Bar

Bases: object

Representing the bar/measure. Contains also information about how complete it is.

add(obj)

create_backup()

Calculate and create backup object.

has_attr()

Check if bar contains attribute.

has_music()

Check if bar contains music.

inject_voice(new_voice, override=False, active_slur_count=None)

Adding new voice to bar. Omitting double or conflicting bar attributes as long as override is false. Omitting also bars with only skips.

is_skip(obj_list=None)

Check if bar has nothing but skips.

class ly.musicxml.xml_objs.BarAttr

Bases: object

object that keep track of bar attributes, e.g. time sign, clef, key etc

add_break(force_break)

has_attr()

merge_attr(barattr, override=False)

Merge in attributes (from another bar). Existing attributes will only be replaced when override is set to true.

set_barline(bl)

set_clef(clef)

set_key(muskey, mode)

set_mark(mark)

set_multp_rest(size=0)

set_tempo(unit=0, unittype='', beats=0, dots=0, text='')

set_time(fractlist, numeric=True)

set_word(words)

class ly.musicxml.xml_objs.BarBackup(duration)

Bases: object

Object that stores duration for backup

class ly.musicxml.xml_objs.BarMus(duration, voice=1)

Bases: object

Common class for notes and rests.

add_dot()

add_other_notation(other)

has_attr()

set_dynamics_dashes(sign, before=True)

set_dynamics_mark(sign, before=True)

set_dynamics_text(sign, before=True)

set_dynamics_wedge(sign, before=True)

set_oct_shift(plac, octdir, size)

set_staff(staff)

set_tuplet(fraction, ttype, nr, acttype='', normtype='')

class ly.musicxml.xml_objs.BarNote(pitch_note, alter, accidental, duration, voice=1)

Bases: ly.musicxml.xml_objs.BarMus

object to keep track of note parameters

add_adv_ornament(ornament, end_type='start')

add_articulation(art_name)

add_fingering(finger_nr)

add_lyric(lyric_list)

add_ornament(ornament)

change_lyric_nr(index, nr)

change_lyric_syll(index, syll)

set_duration(duration, durtype='')

set_durtype(durtype)

set_gliss(line, endtype='start', nr=1)

set_grace(slash)

set_octave(octave)

set_slur(nr, slur_type, phrasing=False, slur_start_node=None)

set_stem_direction(direction)

set_tie(tie_type)

set_tremolo(trem_type, duration=False)

class ly.musicxml.xml_objs.BarRest(duration, voice=1, show_type=True, skip=False, pos=0)

Bases: ly.musicxml.xml_objs.BarMus

object to keep track of different rests and skips

set_duration(duration, durtype='')

set_durtype(durtype)

class ly.musicxml.xml_objs.Dynamics(sign, before=True)

Bases: object

Stores information about dynamics.

class ly.musicxml.xml_objs.DynamicsDashes(sign, before=True)

Bases: ly.musicxml.xml_objs.Dynamics

Dynamics dashes.

class ly.musicxml.xml_objs.DynamicsMark(sign, before=True)

Bases: ly.musicxml.xml_objs.Dynamics

A dynamics mark.

class ly.musicxml.xml_objs.DynamicsText(sign, before=True)

Bases: ly.musicxml.xml_objs.Dynamics

A dynamics text.

class ly.musicxml.xml_objs.DynamicsWedge(sign, before=True)

Bases: ly.musicxml.xml_objs.Dynamics

A dynamics wedge/hairpin.

class ly.musicxml.xml_objs.IterateXmlObjs(score, musxml, div)

Bases: object

A ly.musicxml.xml_objs.Score object is iterated and the Music XML node tree is constructed.

after_note(obj)

Xml-nodes after note.

before_note(obj)

Xml-nodes before note.

count_duration(base_scaling, divs)

gener_xml_mus(obj)

Nodes generic for both notes and rests.

iterate_bar(bar)

The objects in the bar are output to the xml-file.

iterate_part(part)

The part is iterated.

iterate_partgroup(group)

Loop through a group, recursively if nested.

new_xml_bar_attr(obj)

Create bar attribute xml-nodes.

new_xml_note(obj)

Create note specific xml-nodes.

new_xml_rest(obj)

Create rest specific xml-nodes.

class ly.musicxml.xml_objs.LyricsSection(name, voice_id)

Bases: ly.musicxml.xml_objs.ScoreSection

Holds the lyrics information. Will eventually be merged to the corresponding note in the section set by the voice id.

class ly.musicxml.xml_objs.OctaveShift(plac, octdir, size)

Bases: object

Class for octave shifts.

class ly.musicxml.xml_objs.Score

Bases: object

Object that keep track of a whole score.

add_right(value, type)

debug_score(attr=[])

Loop through score and print all elements for debugging purposes.

Additionally print element attributes by adding them to the argument ‘attr’ list.

is_empty()

Check if score is empty.

merge_globally(section, override=False)

Merge section to all parts.

class ly.musicxml.xml_objs.ScorePart(staves=0, part_id=None, to_part=None, name='')

Bases: ly.musicxml.xml_objs.ScoreSection

object to keep track of part

extract_global_to_section(name)

Extract only elements that is relevant for the score globally into a given section.

merge_part_to_part()

Merge the part with the one indicated.

set_first_bar(divisions)

class ly.musicxml.xml_objs.ScorePartGroup(num, bracket)

Bases: object

Object to keep track of part group.

merge_voice(voice, override=False)

Merge in a ScoreSection into all parts.

set_bracket(bracket)

class ly.musicxml.xml_objs.ScoreSection(name, glob=False)

Bases: object

object to keep track of music section

merge_lyrics(lyrics)

Merge in lyrics in music section.

merge_voice(voice, override=False)

Merge in other ScoreSection.

class ly.musicxml.xml_objs.Slur(nr, slurtype, phrasing=False, start_node=None)

Bases: object

Stores information about slur. start_node is only interesting if slurtype is ‘stop’. start_node must be None or a Slur instance.

class ly.musicxml.xml_objs.SlurCount

Bases: object

Utility class meant for keeping count of started slurs in a section

dec()

inc()

class ly.musicxml.xml_objs.Snippet(name, merge_into)

Bases: ly.musicxml.xml_objs.ScoreSection

Short section intended to be merged. Holds reference to the barlist to be merged into.

class ly.musicxml.xml_objs.TempoDir(unit, unittype, beats, dots, text)

Bases: object

Object that stores tempo direction information

set_midi_tempo(unit, beats, dots)

class ly.musicxml.xml_objs.Tuplet(fraction, ttype, nr, acttype, normtype)

Bases: object

Stores information about tuplet.

class ly.musicxml.xml_objs.Unpitched(duration, step=None, voice=1)

Bases: ly.musicxml.xml_objs.BarNote

Object to keep track of unpitched notes.

ly.musicxml.xml_objs.convert_barl(bl)

ly.musicxml.xml_objs.dur2lines(dur)