music21.expressions

This module provides object representations of expressions, that is notational symbols such as Fermatas, Mordents, Trills, Turns, etc. which are stored under a Music21Object’s .expressions attribute

It also includes representations of things such as TextExpressions which are better attached to the Stream itself.

TODO: replace .size with a string representing interval and then create interval.Interval objects only when necessary.

Functions

music21.expressions.realizeOrnaments(srcObject)

given a Music21Object with Ornament expressions, convert them into a list of objects that represents the performed version of the object:

>>> n1 = note.Note("D5")
>>> n1.quarterLength = 1
>>> n1.expressions.append(expressions.WholeStepMordent())
>>> expList = expressions.realizeOrnaments(n1)
>>> st1 = stream.Stream()
>>> st1.append(expList)
>>> st1.show()
../_images/expressionsMordentRealize.png

TextExpression

class music21.expressions.TextExpression(content=None)

A TextExpression is a word, phrase, or similar bit of text that is positioned in a Stream or Measure. Conventional expressive indications are text like “agitato” or “con fuoco.”

>>> te = expressions.TextExpression('testing')
>>> te.size = 24
>>> te.size
24.0
>>> te.style = 'bolditalic'
>>> te.letterSpacing = 0.5

TextExpression bases

TextExpression read-only properties

Read-only properties inherited from Music21Object:

TextExpression read/write properties

TextExpression.content

Get or set the content.

>>> te = expressions.TextExpression('testing')
>>> te.content
'testing'
TextExpression.enclosure

Get or set the enclosure.

>>> te = expressions.TextExpression()
>>> te.justify = 'center'
>>> te.enclosure = None
>>> te.enclosure = 'rectangle'
TextExpression.positionVertical

Get or set the vertical position, where 0 is the top line of the staff and units are in 10ths of a staff space.

Other legal positions are ‘above’ and ‘below’ which are synonyms for 10 and -70 respectively (for 5-line staves; other staves are not yet implemented)

>>> te = expressions.TextExpression()
>>> te.positionVertical = 10
>>> te.positionVertical
10.0

>>> te.positionVertical = 'below'
>>> te.positionVertical
-70.0

Read/write properties inherited from Music21Object:

Read/write properties inherited from TextFormat:

TextExpression methods

TextExpression.getRepeatExpression()

If this TextExpression can be a RepeatExpression, return a new RepeatExpression. object, otherwise, return None.

TextExpression.getTempoText()

Methods inherited from Music21Object:

TextExpression instance variables

Instance variables inherited from Music21Object:

Fermata

class music21.expressions.Fermata

Fermatas by default get appended to the last note if a note is split because of measures. To override this (for Fermatas or for any expression) set .tieAttach to ‘all’ or ‘first’ instead of ‘last’.

>>> p1 = stream.Part()
>>> p1.append(meter.TimeSignature('6/8'))
>>> n1 = note.Note("D-2")
>>> n1.quarterLength = 6
>>> n1.expressions.append(expressions.Fermata())
>>> p1.append(n1)
>>> p1.show()
.. image:: images/expressionsFermata.*
     :width: 193

Fermata bases

Fermata read-only properties

Read-only properties inherited from Music21Object:

Fermata read/write properties

Read/write properties inherited from Music21Object:

Fermata methods

Methods inherited from Music21Object:

Fermata instance variables

Instance variables inherited from Music21Object:

GeneralAppoggiatura

class music21.expressions.GeneralAppoggiatura

GeneralAppoggiatura bases

GeneralAppoggiatura read-only properties

Read-only properties inherited from Music21Object:

GeneralAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

GeneralAppoggiatura methods

GeneralAppoggiatura.realize(srcObj)

realize an appoggiatura

returns a three-element tuple. The first is the notes that the grace note was converted to. The second is the rest of the note The third is an empty list (since there are no notes at the end of an appoggiatura)

>>> n1 = note.Note("C4")
>>> n1.quarterLength = 0.5
>>> a1 = expressions.Appoggiatura()
>>> a1.realize(n1)
([<music21.note.Note D>], <music21.note.Note C>, [])

>>> n2 = note.Note("C4")
>>> n2.quarterLength = 1
>>> a2 = expressions.HalfStepInvertedAppoggiatura()
>>> a2.realize(n2)
([<music21.note.Note B>], <music21.note.Note C>, [])

Methods inherited from Music21Object:

GeneralAppoggiatura instance variables

Instance variables inherited from Music21Object:

GeneralMordent

class music21.expressions.GeneralMordent

Base class for all Mordent types.

GeneralMordent bases

GeneralMordent read-only properties

Read-only properties inherited from Music21Object:

GeneralMordent read/write properties

Read/write properties inherited from Music21Object:

GeneralMordent methods

GeneralMordent.realize(srcObj)

Realize a mordent.

returns a three-element tuple. The first is a list of the two notes that the beginning of the note were converted to. The second is the rest of the note The third is an empty list (since there are no notes at the end of a mordent)

>>> n1 = note.Note("C4")
>>> n1.quarterLength = 0.5
>>> m1 = expressions.Mordent()
>>> m1.realize(n1)
([<music21.note.Note C>, <music21.note.Note B>], <music21.note.Note C>, [])

Note: use one of the subclasses, not the GeneralMordent class

>>> n2 = note.Note("C4")
>>> n2.quarterLength = 0.125
>>> m2 = expressions.GeneralMordent()
>>> m2.realize(n2)
Traceback (most recent call last):
ExpressionException: Cannot realize a mordent if I do not know its direction

Methods inherited from Music21Object:

GeneralMordent instance variables

Instance variables inherited from Music21Object:

Ornament

class music21.expressions.Ornament

Ornament bases

Ornament read-only properties

Read-only properties inherited from Music21Object:

Ornament read/write properties

Read/write properties inherited from Music21Object:

Ornament methods

Ornament.realize(srcObj)

subclassible method call that takes a sourceObject and returns a three-element tuple of a list of notes before the “main note” or the result of the expression if it gobbles up the entire note, the “main note” itself (or None) to keep processing for ornaments, and a list of notes after the “main note”

Methods inherited from Music21Object:

Ornament instance variables

Instance variables inherited from Music21Object:

Tremolo

class music21.expressions.Tremolo

A tremolo ornament represents a single-note tremolo, whether measured or unmeasured.

>>> n = note.Note(type='quarter')
>>> t = expressions.Tremolo()
>>> t.measured = True # default
>>> t.numberOfMarks = 3 # default

>>> t.numberOfMarks = 'Hi'
Traceback (most recent call last):
TremoloException: Number of marks must be a number from 0 to 8

>>> t.numberOfMarks = -1
Traceback (most recent call last):
TremoloException: Number of marks must be a number from 0 to 8

TODO: (someday) realize triplet Tremolos, etc. differently from other tremolos. TODO: deal with unmeasured tremolos.

Tremolo bases

Tremolo read-only properties

Read-only properties inherited from Music21Object:

Tremolo read/write properties

Tremolo.numberOfMarks

The number of marks on the note. Currently completely controls playback.

Read/write properties inherited from Music21Object:

Tremolo methods

Tremolo.realize(srcObj)

Realize the ornament

>>> n = note.Note(type='quarter')
>>> t = expressions.Tremolo()
>>> t.measured = True # default
>>> t.numberOfMarks = 3 # default
>>> t.realize(n)
([<music21.note.Note C>, <music21.note.Note C>, <music21.note.Note C>, 
  <music21.note.Note C>, <music21.note.Note C>, <music21.note.Note C>, 
  <music21.note.Note C>, <music21.note.Note C>], None, [])
>>> c2 = t.realize(n)[0]
>>> [ts.quarterLength for ts in c2]
[0.125, 0.125, 0.125, 0.125, 0.125, 0.125, 0.125, 0.125]

Same thing with Streams:

>>> n = note.Note(type='quarter')
>>> t = expressions.Tremolo()
>>> n.expressions.append(t)
>>> s = stream.Stream()
>>> s.append(n)
>>> s.show('text')
{0.0} <music21.note.Note C>

>>> y = stream.makeNotation.realizeOrnaments(s)
>>> y.show('text')
{0.0} <music21.note.Note C>
{0.125} <music21.note.Note C>
{0.25} <music21.note.Note C>
{0.375} <music21.note.Note C>
{0.5} <music21.note.Note C>
{0.625} <music21.note.Note C>
{0.75} <music21.note.Note C>
{0.875} <music21.note.Note C>        

>>> t.numberOfMarks = 1
>>> y = stream.makeNotation.realizeOrnaments(s)
>>> y.show('text')
{0.0} <music21.note.Note C>
{0.5} <music21.note.Note C>

Methods inherited from Music21Object:

Tremolo instance variables

Instance variables inherited from Music21Object:

TremoloSpanner

class music21.expressions.TremoloSpanner(*arguments, **keywords)

A tremolo that spans multiple notes

>>> ts = expressions.TremoloSpanner()    
>>> n1 = note.Note('C')
>>> n2 = note.Note('D')
>>> ts.addSpannedElements([n1, n2])
>>> ts.numberOfMarks = 2
>>> ts
<music21.expressions.Tremolo <music21.note.Note C><music21.note.Note D>>

>>> ts.numberOfMarks = -1
Traceback (most recent call last):
TremoloException: Number of marks must be a number from 0 to 8

TremoloSpanner bases

TremoloSpanner read-only properties

Read-only properties inherited from Music21Object:

TremoloSpanner read/write properties

TremoloSpanner.numberOfMarks

The number of marks on the note. Will eventually control playback.

Read/write properties inherited from Music21Object:

TremoloSpanner methods

Methods inherited from Spanner:

Methods inherited from Music21Object:

TremoloSpanner instance variables

Instance variables inherited from Music21Object:

Trill

class music21.expressions.Trill

A basic trill marker.

>>> m = expressions.Trill()
>>> m.placement
'above'
>>> m.size
<music21.interval.Interval M2>

Trill bases

Trill read-only properties

Read-only properties inherited from Music21Object:

Trill read/write properties

Read/write properties inherited from Music21Object:

Trill methods

Trill.realize(srcObj)

realize a trill.

returns a three-element tuple. The first is a list of the notes that the note was converted to. The second is None because the trill “eats up” the whole note. The third is a list of the notes at the end if nachschlag is True, and empty list if False.

>>> n1 = note.Note("C4")
>>> n1.quarterLength = 0.5
>>> t1 = expressions.Trill()
>>> t1.realize(n1)
([<music21.note.Note C>, 
  <music21.note.Note D>, 
  <music21.note.Note C>, 
  <music21.note.Note D>], None, [])

>>> n2 = note.Note("D4")
>>> n2.quarterLength = 0.125
>>> t2 = expressions.Trill()
>>> t2.realize(n2)
Traceback (most recent call last):
    ...
ExpressionException: The note is not long enough to realize a trill
Trill.splitClient(noteList)

splitClient is called by base.splitAtQuarterLength() to support splitting trills.

>>> n = note.Note(type='whole')
>>> n.expressions.append(expressions.Trill())
>>> st = n.splitAtQuarterLength(3.0)
>>> n1, n2 = st
>>> st.spannerList
[<music21.expressions.TrillExtension <music21.note.Note C><music21.note.Note C>>]
>>> n1.getSpannerSites()
[<music21.expressions.TrillExtension <music21.note.Note C><music21.note.Note C>>]

Methods inherited from Music21Object:

Trill instance variables

Instance variables inherited from Music21Object:

TrillExtension

class music21.expressions.TrillExtension(*arguments, **keywords)

A wavy line trill extension, placed between two notes. N ote that some MusicXML readers include a trill symbol with the wavy line.

>>> s = stream.Stream()
>>> s.repeatAppend(note.Note(), 8)
>>> # create between notes 2 and 3
>>> te = expressions.TrillExtension(s.notes[1], s.notes[2])
>>> s.append(te) # can go anywhere in the Stream
>>> te.getDurationBySite(s).quarterLength
2.0
>>> print(te)
<music21.expressions.TrillExtension <music21.note.Note C><music21.note.Note C>>

TrillExtension bases

TrillExtension read-only properties

Read-only properties inherited from Music21Object:

TrillExtension read/write properties

TrillExtension.placement

Get or set the placement as either above or below.

>>> s = stream.Stream()
>>> s.repeatAppend(note.Note(), 8)
>>> te = expressions.TrillExtension(s.notes[1], s.notes[2])
>>> te.placement = 'above'
>>> te.placement
'above'

Read/write properties inherited from Music21Object:

TrillExtension methods

Methods inherited from Spanner:

Methods inherited from Music21Object:

TrillExtension instance variables

Instance variables inherited from Music21Object:

Turn

class music21.expressions.Turn

Turn bases

Turn read-only properties

Read-only properties inherited from Music21Object:

Turn read/write properties

Read/write properties inherited from Music21Object:

Turn methods

Turn.realize(srcObject)

realize a turn.

returns a three-element tuple. The first is a list of the four notes that the beginning of the note was converted to. The second is a note of duration 0 because the turn “eats up” the whole note. The third is a list of the notes at the end if nachschlag is True, and empty list if False.

>>> from  music21 import *
>>> m1 = stream.Measure()
>>> m1.append(key.Key('F', 'major'))
>>> n1 = note.Note("C5")
>>> m1.append(n1)
>>> t1 = expressions.Turn()
>>> t1.realize(n1)
([], <music21.note.Note C>, [<music21.note.Note D>, 
                             <music21.note.Note C>, 
                             <music21.note.Note B->, 
                             <music21.note.Note C>])

>>> m2 = stream.Measure()
>>> m2.append(key.KeySignature(5))
>>> n2 = note.Note("B4")
>>> m2.append(n2)
>>> t2 = expressions.InvertedTurn()
>>> t2.realize(n2)
([], <music21.note.Note B>, [<music21.note.Note A#>, 
                             <music21.note.Note B>, 
                             <music21.note.Note C#>, 
                             <music21.note.Note B>])

>>> n2 = note.Note("C4")
>>> n2.quarterLength = 0.125
>>> t2 = expressions.Turn()
>>> t2.realize(n2)
Traceback (most recent call last):
    ...
ExpressionException: The note is not long enough to realize a turn

Methods inherited from Music21Object:

Turn instance variables

Instance variables inherited from Music21Object: