ly.music package¶

Module contents¶

An api to read music from the tokens of a ly.document.Document into a tree structure.

This is meant to quickly read music from a document, to perform modifications on the document, and to interpret music and markup and to convert or export it to other formats.

All nodes are a subclass of items.Item, (which inherits from node.WeakNode).

Tree structures are created from nested LilyPond structures, markup and scheme code. Some Item types have special methods to query information. The Music type, for example, has a length() method that returns the duration of the music fragment.

Using the Music.events() method and the events module, it is possible to iterate in musical time over the music tree, e.g. to convert music to another format.

This package is not yet capable to construct documents entirely from scratch. This needs to be developed. Until that time, the ly.dom module can be used instead.

Some Item types can have a list of child items, but the tree structure is as linear as possible.

A convenience function is available to create a ly.music.items.Document instance for the specified ly.document.Document.

Here is an example:

>>> import ly.document
>>> import ly.music
>>> d=ly.document.Document(r'''
\version "2.18.0"

music = \relative {
  \time 4/4
  \key d \minor
  d4 e f g
  a g f e
  d2
}

\score {
  \new Staff <<
    \music
  >>
}
''')
>>> m=ly.music.document(d)
>>> print m.dump()
<Document>
  <Version u'\\version'>
    <String u'"'>
  <Assignment u'music'>
    <Relative u'\\relative'>
      <MusicList u'{'>
        <TimeSignature u'\\time'>
        <KeySignature u'\\key'>
          <Note u'd'>
          <Command u'\\minor'>
        <Note u'd'>
        <Note u'e'>
        <Note u'f'>
        <Note u'g'>
        <Note u'a'>
        <Note u'g'>
        <Note u'f'>
        <Note u'e'>
        <Note u'd'>
  <Score u'\\score'>
    <Context u'\\new'>
      <MusicList u'<<'>
        <UserCommand u'\\music'>
>>> m[2][0][0]
<MusicList u'<<'>
>>> m[2][0][0].length()
Fraction(5, 2)
>>>

ly.music.document(doc)[source]¶: Return a music.items.Document instance for the ly.document.Document.

Submodules¶

ly.music.event module¶

Translates a music.items.Document tree into lists of events.

class ly.music.event.Events[source]¶

Bases: object

Traverses a music tree and records music events from it.

read(node, time=0, scaling=1)[source]¶: Read events from the node and all its child nodes; return time.

traverse(node, time, scaling)[source]¶: Traverse node and call event handlers; record and return the time.

unfold_repeats = False¶

ly.music.items module¶

The items a music expression is constructed with in a tree structure.

Whitespace and comments are left out.

All nodes (instances of Item) have a ‘position’ attribute that indicates where the item starts in the source text. Almost all items have the token that starts the expression in the ‘token’ attribute and possibly other tokens in the ‘tokens’ attribute, as a tuple.

The ‘end_position()’ method returns the position where the node (including its child nodes) ends.

You can get the whole tree structure of a LilyPond document by instantiating a Document with the ly.document.Document instance. (It will read all the tokens from the document using the Reader from the read module.) As a convenience, the ly.music.document(doc) function does this.

If you want to add new Item types, you should also add a method to read.Reader to construct those items.

class ly.music.items.Absolute(parent=None)[source]¶

Bases: ly.music.items.Music

An absolute music expression. Has one child (normally Music).

class ly.music.items.AfterGrace(parent=None)[source]¶

Bases: ly.music.items.Music

The afterGrace function with its two arguments.

Only the duration of the first is counted.

class ly.music.items.Alternative(parent=None)[source]¶

Bases: ly.music.items.Music

An alternative expression.

class ly.music.items.Articulation(parent=None)[source]¶

ly.music package¶

Module contents¶

Submodules¶

ly.music.event module¶

ly.music.items module¶

ly.music.read module¶