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.

A sub-category of Expressions are Ornaments.

Unlike articulations, expressions can be attached to the Stream itself. For instance, TextExpressions.

TextExpression

class music21.expressions.TextExpression(content=None, **keywords)

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('Con fuoco')
>>> te.content
'Con fuoco'

Most configuration of style is done on the .style TextStyle object itself.

>>> te.style.fontSize = 24.0
>>> te.style.fontSize
24
>>> te.style.fontStyle = 'italic'
>>> te.style.fontWeight = 'bold'
>>> te.style.letterSpacing = 0.5

TextExpression bases

TextExpression read-only properties

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

TextExpression read/write properties

TextExpression.content

Get or set the content.

>>> te = expressions.TextExpression('dolce')
>>> te.content
'dolce'
>>> te.content = 'sweeter'
>>> te
<music21.expressions.TextExpression 'sweeter'>
TextExpression.enclosure

Returns or sets the enclosure on the Style object stored on .style.

Exposed directly on the expression for backwards compatibility. Does not create a .style object if one does not exist and the value is None.

>>> te = expressions.TextExpression('Bridge')
>>> te.enclosure is None
True
>>> te.enclosure = style.Enclosure.RECTANGLE
>>> te.enclosure
<Enclosure.RECTANGLE>

Note that this is also set on .style.

>>> te.style.enclosure
<Enclosure.RECTANGLE>

Read/write properties inherited from Music21Object:

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:

Methods inherited from ProtoM21Object:

TextExpression instance variables

TextExpression.placement

Staff placement: ‘above’, ‘below’, or None.

A setting of None implies that the placement will be determined by notation software and no particular placement is demanded.

This is not placed in the .style property, since for some expressions, the placement above or below an object has semantic meaning and is not purely presentational.

Instance variables inherited from Music21Object:

Appoggiatura

class music21.expressions.Appoggiatura(**keywords)

Appoggiatura bases

Appoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Appoggiatura read/write properties

Read/write properties inherited from Music21Object:

Appoggiatura methods

Methods inherited from GeneralAppoggiatura:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Appoggiatura instance variables

Instance variables inherited from Music21Object:

ArpeggioMark

class music21.expressions.ArpeggioMark(arpeggioType: str | None = None, **keywords)

ArpeggioMark must be applied to a Chord (not to a single Note).

The parameter arpeggioType can be ‘normal’ (a squiggly line), ‘up’ (a squiggly line with an up arrow), ‘down’ (a squiggly line with a down arrow), or ‘non-arpeggio’ (a bracket instead of a squiggly line, used to indicate a non-arpeggiated chord intervening in a sequence of arpeggiated ones).

>>> am = expressions.ArpeggioMark('normal')
>>> am.type
'normal'

>>> am = expressions.ArpeggioMark('down')
>>> am.type
'down'

ArpeggioMark bases

ArpeggioMark read-only properties

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

ArpeggioMark read/write properties

Read/write properties inherited from Music21Object:

ArpeggioMark methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

ArpeggioMark instance variables

Instance variables inherited from Music21Object:

ArpeggioMarkSpanner

class music21.expressions.ArpeggioMarkSpanner(*spannedElements, arpeggioType: str = 'normal', **keywords)

ArpeggioMarkSpanner is a multi-staff or multi-voice (i.e. multi-chord) arpeggio. The spanner should contain all the simultaneous Chords that are to be arpeggiated together. If there is only one arpeggiated note in a particular staff or voice (i.e. the rest are in other staves/voices), then in that case only the spanner can contain a Note. Do not ever put a Note that is within a Chord into a spanner; put the Chord in instead. And do not ever put an ArpeggioMark in a note or chord’s .expressions.

The parameter arpeggioType can be ‘normal’ (a squiggly line), ‘up’ (a squiggly line with an up arrow), ‘down’ (a squiggly line with a down arrow), or ‘non-arpeggio’ (a bracket instead of a squiggly line, used to indicate a non-arpeggiated multi-chord intervening in a sequence of arpeggiated ones).

>>> ams = expressions.ArpeggioMarkSpanner(arpeggioType='non-arpeggio')
>>> c1 = chord.Chord('C3 E3 G3')
>>> c2 = chord.Chord('C4 E4 G4')
>>> ams.addSpannedElements([c1, c2])
>>> ams.type
'non-arpeggio'
>>> ams
<music21.expressions.ArpeggioMarkSpanner
 <music21.chord.Chord C3 E3 G3><music21.chord.Chord C4 E4 G4>>

ArpeggioMarkSpanner bases

ArpeggioMarkSpanner read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

ArpeggioMarkSpanner read/write properties

Read/write properties inherited from Music21Object:

ArpeggioMarkSpanner methods

ArpeggioMarkSpanner.noteExtremes() → tuple[note.Note | None, note.Note | None]

Return the lowest and highest note spanned by the element, extracting them from Chords if need be.

>>> ch = chord.Chord(['C4', 'E4', 'G4'])
>>> n = note.Note('C#3')
>>> nonArp = expressions.ArpeggioMarkSpanner([ch, n])
>>> nonArp.noteExtremes()
(<music21.note.Note C#>, <music21.note.Note G>)

Methods inherited from Spanner:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

ArpeggioMarkSpanner instance variables

Instance variables inherited from Music21Object:

Expression

class music21.expressions.Expression(**keywords)

This base class is inherited by many diverse expressions.

Expression bases

Expression read-only properties

Expression.name

returns the name of the expression, which is generally the class name lowercased and spaces where a new capital occurs.

Subclasses can override this as necessary.

>>> sc = expressions.Schleifer()
>>> sc.name
'schleifer'

>>> iTurn = expressions.InvertedTurn()
>>> iTurn.name
'inverted turn'

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Expression read/write properties

Read/write properties inherited from Music21Object:

Expression methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Expression instance variables

Instance variables inherited from Music21Object:

Fermata

class music21.expressions.Fermata(**keywords)

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 Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Fermata read/write properties

Read/write properties inherited from Music21Object:

Fermata methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Fermata instance variables

Instance variables inherited from Music21Object:

GeneralAppoggiatura

class music21.expressions.GeneralAppoggiatura(**keywords)

GeneralAppoggiatura bases

GeneralAppoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

GeneralAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

GeneralAppoggiatura methods

GeneralAppoggiatura.realize(srcObj: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None, inPlace: bool = False) → tuple[list[note.Note | note.Unpitched], note.Note | note.Unpitched | None, list[note.Note | note.Unpitched]]

realize an appoggiatura

returns a three-element tuple. The first is the list of 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 Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

GeneralAppoggiatura instance variables

Instance variables inherited from Music21Object:

GeneralMordent

class music21.expressions.GeneralMordent(*, accidental: Accidental | None = None, **keywords)

Base class for all Mordent types.

GeneralMordent bases

GeneralMordent read-only properties

GeneralMordent.direction

The direction of the mordent’s ornamental pitch from the main note. Can be ‘up’ or ‘down’.

GeneralMordent.name

returns the name of the Mordent/InvertedMordent, which is generally the class name lowercased, with spaces where a new capital occurs. The name also will include any accidental, if it exists.

Subclasses can override this as necessary.

>>> mordent = expressions.Mordent()
>>> mordent.name
'mordent'

>>> sharp = pitch.Accidental('sharp')
>>> invertedMordent = expressions.InvertedMordent(accidental=sharp)
>>> invertedMordent.name
'inverted mordent (sharp)'
GeneralMordent.ornamentalPitch

Returns the mordent’s ornamentalPitch. If resolveOrnamentalPitches has not yet been called, None is returned.

GeneralMordent.ornamentalPitches

Returns any ornamental pitch that has been resolved (see resolveOrnamentalPitches, which must be called first, or an empty tuple will be returned).

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

GeneralMordent read/write properties

GeneralMordent.accidental

This is the GeneralMordent’s accidental.

Read/write properties inherited from Music21Object:

GeneralMordent methods

GeneralMordent.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the mordent’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the mordent will also be taken into account. If no accidental has been set, the appropriate accidental from the key signature will be used.

If keySig is specified, this can be considered to be a theoretical question: “If this particular mordent were to be attached to this note, in this key, what would the size of the mordent interval be?”

GeneralMordent.realize(srcObj: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None, inPlace: bool = False) → tuple[list[note.Note | note.Unpitched], note.Note | note.Unpitched | None, list[note.Note | note.Unpitched]]

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):
music21.expressions.ExpressionException: Cannot realize a mordent if I do not
    know its direction
GeneralMordent.resolveOrnamentalPitches(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None)

Computes and stores the ornamental pitch for a GeneralMordent, given the srcObj (can be any kind of ornamented GeneralNote) and an optional keySig.

If keySig is None, srcNote’s context will be searched for a key signature. If no key signature is found, a key signature with no sharps and no flats will be used.

A mordent on a G in a key with no sharps or flats (ornamental pitch will be F).

>>> noSharpsOrFlats = key.KeySignature(sharps=0)
>>> n1 = note.Note('G4')
>>> mordent = expressions.Mordent()
>>> mordent.resolveOrnamentalPitches(n1, keySig=noSharpsOrFlats)
>>> mordent.ornamentalPitches
(<music21.pitch.Pitch F4>,)
>>> mordent.ornamentalPitch
<music21.pitch.Pitch F4>

e.g. A mordent on a G in a key with one sharp (ornamental pitch will be F#).

>>> oneSharp = key.KeySignature(sharps=1)
>>> mordent.resolveOrnamentalPitches(n1, keySig=oneSharp)
>>> mordent.ornamentalPitches
(<music21.pitch.Pitch F#4>,)
>>> mordent.ornamentalPitch
<music21.pitch.Pitch F#4>

e.g. A mordent with a natural, on a G, in a key with one sharp (ornamental pitch will be F).

>>> mordent.accidental = pitch.Accidental('natural')
>>> mordent.resolveOrnamentalPitches(n1, keySig=oneSharp)
>>> mordent.ornamentalPitches
(<music21.pitch.Pitch F4>,)
>>> mordent.ornamentalPitch
<music21.pitch.Pitch F4>
GeneralMordent.updateAccidentalDisplay(*, pitchPast: list[Pitch] | None = None, pitchPastMeasure: list[Pitch] | None = None, otherSimultaneousPitches: list[Pitch] | None = None, alteredPitches: list[Pitch] | None = None, cautionaryPitchClass: bool = True, cautionaryAll: bool = False, overrideStatus: bool = False, cautionaryNotImmediateRepeat: bool = True)

Updates accidental display for a GeneralMordent’s ornamental pitch. Defined exactly like Pitch.updateAccidentalDisplay, with two changes: Instead of self being the pitch to update, self is a GeneralMordent whose ornamentalPitch is to be updated; and we pay no attention to ties, since ornamental notes cannot be tied.

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

GeneralMordent instance variables

Instance variables inherited from Music21Object:

HalfStepAppoggiatura

class music21.expressions.HalfStepAppoggiatura(**keywords)

HalfStepAppoggiatura bases

HalfStepAppoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

HalfStepAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

HalfStepAppoggiatura methods

Methods inherited from GeneralAppoggiatura:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

HalfStepAppoggiatura instance variables

Instance variables inherited from Music21Object:

HalfStepInvertedAppoggiatura

class music21.expressions.HalfStepInvertedAppoggiatura(**keywords)

HalfStepInvertedAppoggiatura bases

HalfStepInvertedAppoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

HalfStepInvertedAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

HalfStepInvertedAppoggiatura methods

Methods inherited from GeneralAppoggiatura:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

HalfStepInvertedAppoggiatura instance variables

Instance variables inherited from Music21Object:

HalfStepInvertedMordent

class music21.expressions.HalfStepInvertedMordent(**keywords)

A half-step inverted Mordent.

>>> m = expressions.HalfStepInvertedMordent()
>>> m.direction
'up'
>>> m.getSize(note.Note('C4'))
<music21.interval.Interval m2>

HalfStepInvertedMordent bases

HalfStepInvertedMordent read-only properties

Read-only properties inherited from GeneralMordent:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

HalfStepInvertedMordent read/write properties

HalfStepInvertedMordent.accidental

Read/write properties inherited from Music21Object:

HalfStepInvertedMordent methods

HalfStepInvertedMordent.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the mordent’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the mordent will also be taken into account. If no accidental has been set, the appropriate accidental from the key signature will be used.

If keySig is specified, this can be considered to be a theoretical question: “If this particular mordent were to be attached to this note, in this key, what would the size of the mordent interval be?”

Methods inherited from GeneralMordent:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

HalfStepInvertedMordent instance variables

Instance variables inherited from Music21Object:

HalfStepMordent

class music21.expressions.HalfStepMordent(**keywords)

A half step normal Mordent.

>>> m = expressions.HalfStepMordent()
>>> m.direction
'down'
>>> m.getSize(note.Note('C4'))
<music21.interval.Interval m-2>

HalfStepMordent bases

HalfStepMordent read-only properties

Read-only properties inherited from GeneralMordent:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

HalfStepMordent read/write properties

HalfStepMordent.accidental

Read/write properties inherited from Music21Object:

HalfStepMordent methods

HalfStepMordent.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the mordent’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the mordent will also be taken into account. If no accidental has been set, the appropriate accidental from the key signature will be used.

If keySig is specified, this can be considered to be a theoretical question: “If this particular mordent were to be attached to this note, in this key, what would the size of the mordent interval be?”

Methods inherited from GeneralMordent:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

HalfStepMordent instance variables

Instance variables inherited from Music21Object:

HalfStepTrill

class music21.expressions.HalfStepTrill(**keywords)

A trill confined to half steps.

>>> halfTrill = expressions.HalfStepTrill()
>>> halfTrill.placement
'above'
>>> halfTrill.getSize(note.Note('C4'))
<music21.interval.Interval m2>

Here the key signature of 2 sharps will not affect the trill:

>>> n = note.Note('B4', type='eighth')
>>> m = stream.Measure()
>>> m.insert(0, key.KeySignature(2))
>>> m.append(n)
>>> halfTrill.realize(n)
([<music21.note.Note B>,
  <music21.note.Note C>,
  <music21.note.Note B>,
  <music21.note.Note C>], None, [])

HalfStepTrill bases

HalfStepTrill read-only properties

Read-only properties inherited from Trill:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

HalfStepTrill read/write properties

HalfStepTrill.accidental

Read/write properties inherited from Music21Object:

HalfStepTrill methods

HalfStepTrill.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the trill’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the trill will also be taken into account.

If keySig is specified, this can be considered to be a theoretical question: “If this particular trill were to be attached to this note, in this key, what would the size of the trill interval be?”

Methods inherited from Trill:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

HalfStepTrill instance variables

Instance variables inherited from Music21Object:

InvertedAppoggiatura

class music21.expressions.InvertedAppoggiatura(**keywords)

InvertedAppoggiatura bases

InvertedAppoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

InvertedAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

InvertedAppoggiatura methods

Methods inherited from GeneralAppoggiatura:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

InvertedAppoggiatura instance variables

Instance variables inherited from Music21Object:

InvertedMordent

class music21.expressions.InvertedMordent(*, accidental: Accidental | None = None, **keywords)

An inverted Mordent – goes upwards and has no line through it.

Note that some computer terminology calls this one a (normal) mordent, but this is a modern term. See Apel, Harvard Dictionary of Music, “Inverted Mordent”:

An 18th-century ornament involving alternation of the
written note with the note immediately above it.

An inverted mordent has the size of a second, of some form, depending on the note that will have the mordent, the current key signature in that note’s context, as well as any accidental on the mordent itself.

>>> m = expressions.InvertedMordent()
>>> m.direction
'up'
>>> m.getSize(note.Note('C4'))
<music21.interval.Interval M2>
>>> m.getSize(note.Note('B3'))
<music21.interval.Interval m2>

>>> mSharp = expressions.InvertedMordent(accidental=pitch.Accidental('sharp'))
>>> mSharp.direction
'up'
>>> mSharp.getSize(note.Note('C4'))
<music21.interval.Interval A2>
>>> mSharp.getSize(note.Note('B3'))
<music21.interval.Interval M2>

  • Changed in v7: InvertedMordent sizes are GenericIntervals – as was originally intended but programmed incorrectly.

  • Changed in v9: Support an accidental on InvertedMordent. This also adds the concept of an ornamental pitch that is processed by makeAccidentals. The size property has been removed and replaced with .getSize() (which requires a srcObj and optional keySig param). Added optional keySig param to .realize() as well.

InvertedMordent bases

InvertedMordent read-only properties

Read-only properties inherited from GeneralMordent:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

InvertedMordent read/write properties

Read/write properties inherited from GeneralMordent:

Read/write properties inherited from Music21Object:

InvertedMordent methods

Methods inherited from GeneralMordent:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

InvertedMordent instance variables

Instance variables inherited from Music21Object:

InvertedTrill

class music21.expressions.InvertedTrill(*, accidental: Accidental | None = None, **keywords)

InvertedTrill bases

InvertedTrill read-only properties

Read-only properties inherited from Trill:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

InvertedTrill read/write properties

Read/write properties inherited from Trill:

Read/write properties inherited from Music21Object:

InvertedTrill methods

Methods inherited from Trill:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

InvertedTrill instance variables

Instance variables inherited from Music21Object:

InvertedTurn

class music21.expressions.InvertedTurn(*, delay: ~music21.common.enums.OrnamentDelay | float | ~fractions.Fraction = <OrnamentDelay.NO_DELAY>, upperAccidental: ~music21.pitch.Accidental | None = None, lowerAccidental: ~music21.pitch.Accidental | None = None, **keywords)

InvertedTurn bases

InvertedTurn read-only properties

Read-only properties inherited from Turn:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

InvertedTurn read/write properties

Read/write properties inherited from Turn:

Read/write properties inherited from Music21Object:

InvertedTurn methods

Methods inherited from Turn:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

InvertedTurn instance variables

Instance variables inherited from Music21Object:

Mordent

class music21.expressions.Mordent(*, accidental: Accidental | None = None, **keywords)

A normal Mordent – goes downwards and has a line through it.

Note that some computer terminology calls this one an inverted mordent, but this is a modern term. See Apel, Harvard Dictionary of Music, “Mordent”:

A musical ornament consisting of the alternation of the written note
with the note immediately below it.

A mordent has the size of a second, of some form, depending on the note that will have the mordent, the current key signature in that note’s context, as well as any accidental on the mordent itself.

e.g. Mordent without accidentals in default key (no flats or sharps)

>>> m = expressions.Mordent()
>>> m.direction
'down'
>>> m.getSize(note.Note('C4'))
<music21.interval.Interval m-2>
>>> m.getSize(note.Note('B3'))
<music21.interval.Interval M-2>

e.g. Mordent with flat, in default key (no flats or sharps)

>>> mFlat = expressions.Mordent(accidental=pitch.Accidental('flat'))
>>> mFlat.direction
'down'
>>> mFlat.getSize(note.Note('C4'))
<music21.interval.Interval M-2>
>>> mFlat.getSize(note.Note('B3'))
<music21.interval.Interval A-2>

e.g. Mordent without accidentals, in key with one flat

>>> oneFlat = key.KeySignature(-1)
>>> mNotFlat = expressions.Mordent()
>>> mNotFlat.direction
'down'
>>> mNotFlat.getSize(note.Note('C4'), keySig=oneFlat)
<music21.interval.Interval M-2>
>>> mNotFlat.getSize(note.Note('B3'), keySig=oneFlat)
<music21.interval.Interval M-2>

e.g. Mordent without accidentals, with a key from context with one flat (same results)

>>> noteC4 = note.Note('C4')
>>> noteB3 = note.Note('B3')
>>> measure = stream.Measure([oneFlat, noteC4, noteB3])
>>> mNotFlatWithKeyFromContext = expressions.Mordent()
>>> mNotFlatWithKeyFromContext.direction
'down'
>>> mNotFlatWithKeyFromContext.getSize(noteC4)
<music21.interval.Interval M-2>
>>> mNotFlatWithKeyFromContext.getSize(noteB3)
<music21.interval.Interval M-2>

  • Changed in v7: Mordent sizes are GenericIntervals – as was originally intended but programmed incorrectly.

  • Changed in v9: Support an accidental on Mordent. This also adds the concept of an ornamental pitch that is processed by makeAccidentals. The size property has been removed and replaced with .getSize() (which requires a srcObj and optional keySig param). Added optional keySig param to .realize() as well.

Mordent bases

Mordent read-only properties

Read-only properties inherited from GeneralMordent:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Mordent read/write properties

Read/write properties inherited from GeneralMordent:

Read/write properties inherited from Music21Object:

Mordent methods

Methods inherited from GeneralMordent:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Mordent instance variables

Instance variables inherited from Music21Object:

Ornament

class music21.expressions.Ornament(**keywords)

An Ornament is a type of Expression that, when attached to a Note (in the future: Notes) can transform into the main note.

All ornaments have an .autoScale boolean which determines whether to shrink (not currently to expand) the ornament if the note it is attached to is too short to realize.

Ornament bases

Ornament read-only properties

Ornament.ornamentalPitches

Only implemented in Turn, GeneralMordent, and Trill.

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Ornament read/write properties

Read/write properties inherited from Music21Object:

Ornament methods

Ornament.fillListOfRealizedNotes(srcObj: note.Note | note.Unpitched, fillObjects: list[note.Note | note.Unpitched], transposeInterval: interval.IntervalBase, *, useQL: OffsetQL | None = None) → None

Used by trills and mordents to fill out their realization.

Ornament.realize(srcObj: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None, inPlace: bool = False) → tuple[list[note.Note | note.Unpitched], note.Note | note.Unpitched | None, list[note.Note | note.Unpitched]]

subclassable method call that takes a sourceObject and optional keySig 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”.

  • New in v8: inPlace boolean; note that some ornaments might not return a Note in the second position at all (such as trills) so inPlace does nothing.

  • Changed in v9: Optional keySig can be passed in (useful in cases where there is no keySig in srcObj’s context, or where a different keySig is desired).

Ornament.resolveOrnamentalPitches(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None)

Only implemented in Turn, GeneralMordent, and Trill.

Ornament.updateAccidentalDisplay(*, pitchPast: list[Pitch] | None = None, pitchPastMeasure: list[Pitch] | None = None, otherSimultaneousPitches: list[Pitch] | None = None, alteredPitches: list[Pitch] | None = None, cautionaryPitchClass: bool = True, cautionaryAll: bool = False, overrideStatus: bool = False, cautionaryNotImmediateRepeat: bool = True) → None

Only implemented in Turn, GeneralMordent, and Trill.

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Ornament instance variables

Instance variables inherited from Music21Object:

PedalBounce

class music21.expressions.PedalBounce(**keywords)

This object, when seen in a PedalMark spanner, represents an up/down bounce of the pedal.

PedalBounce bases

PedalBounce read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

PedalBounce read/write properties

Read/write properties inherited from Music21Object:

PedalBounce methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

PedalBounce instance variables

Instance variables inherited from Music21Object:

PedalForm

class music21.expressions.PedalForm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

PedalForm bases

PedalGapEnd

class music21.expressions.PedalGapEnd(**keywords)

This object, when seen in a PedalMark spanner, represents the reappearance of the pedal line.

PedalGapEnd bases

PedalGapEnd read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

PedalGapEnd read/write properties

Read/write properties inherited from Music21Object:

PedalGapEnd methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

PedalGapEnd instance variables

Instance variables inherited from Music21Object:

PedalGapStart

class music21.expressions.PedalGapStart(**keywords)

This object, when seen in a PedalMark spanner, represents a disappearance of the pedal line, usually with a TextExpression(‘simile’). The pedaling should continue (similarly to before), but the line is invisible during this gap.

PedalGapStart bases

PedalGapStart read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

PedalGapStart read/write properties

Read/write properties inherited from Music21Object:

PedalGapStart methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

PedalGapStart instance variables

Instance variables inherited from Music21Object:

PedalMark

class music21.expressions.PedalMark(*spannedElements, **keywords)

A pedal mark spanner contains a pedaled set of notes. The spanner starts at the moment of down-pedal, and ends at the moment of up-pedal. There can be any number of pedal “bounces” in the middle of the spanner.

The visual form of the pedal mark can vary. The following examples use a pedal mark with one “bounce” in the middle:

Pedal marks can be lines:            |_______^________|
Pedal marks can be normal symbolic:  Ped.    * Ped.   *
Pedal marks can be altered symbolic: Ped.    Ped.     *
Pedal marks can be symbol and line:  Ped.____^________|

Pedal marks, whether lines, symbols, or a combination, can represent the sustain pedal (Ped.), the sostenuto pedal (Sost.), the soft (una corda) pedal, or (more rarely) the silent (muting) pedal.

Pedal marks that are symbolic can be abbreviated: e.g. P. instead of Ped., S. instead of Sost.

Pedal marks that are lines can have non-printed portions (gaps) in them; these are usually started with “simile”, but not necessarily.

PedalMark bases

PedalMark read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

PedalMark read/write properties

Read/write properties inherited from Music21Object:

PedalMark methods

Methods inherited from Spanner:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

PedalMark instance variables

Instance variables inherited from Music21Object:

PedalObject

class music21.expressions.PedalObject(**keywords)

Base class of individual objects that mark various transitions in a PedalMark spanner.

PedalObject bases

PedalObject read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

PedalObject read/write properties

Read/write properties inherited from Music21Object:

PedalObject methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

PedalObject instance variables

Instance variables inherited from Music21Object:

PedalType

class music21.expressions.PedalType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

PedalType bases

RehearsalMark

class music21.expressions.RehearsalMark(content=None, *, numbering=None, **keywords)

A rehearsal mark is a type of Expression that designates a rehearsal marking, such as A., B., etc.

Takes two inputs, content (‘B’, 5, ‘III’) and an optional numbering system which is helpful for getting the next rehearsal mark.

>>> rm = expressions.RehearsalMark('B')
>>> rm
<music21.expressions.RehearsalMark 'B'>

RehearsalMark bases

RehearsalMark read-only properties

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

RehearsalMark read/write properties

Read/write properties inherited from Music21Object:

RehearsalMark methods

RehearsalMark.nextContent()

Return the next content based on the numbering

>>> expressions.RehearsalMark('A').nextContent()
'B'

>>> expressions.RehearsalMark('II').nextContent()
'III'

>>> expressions.RehearsalMark('IV').nextContent()
'V'

>>> expressions.RehearsalMark(7).nextContent()
8

>>> expressions.RehearsalMark('Z').nextContent()
'AA'

With rehearsal mark ‘I’ default is to consider it as a roman numeral:

>>> expressions.RehearsalMark('I').nextContent()
'II'

Specify numbering directly to avoid problems:

>>> expressions.RehearsalMark('I', numbering='alphabetical').nextContent()
'J'
RehearsalMark.nextMark()

Return the next rehearsal mark.

>>> rm = expressions.RehearsalMark('C')
>>> rm.nextMark()
<music21.expressions.RehearsalMark 'D'>

>>> rm = expressions.RehearsalMark('IV', numbering='roman')
>>> nm = rm.nextMark()
>>> nm.content
'V'
>>> nm.numbering
'roman'

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

RehearsalMark instance variables

Instance variables inherited from Music21Object:

Schleifer

class music21.expressions.Schleifer(**keywords)

A slide or culee

  • Changed in v7: size is a Generic second. removed unused nachschlag component.

Schleifer bases

Schleifer read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Schleifer read/write properties

Read/write properties inherited from Music21Object:

Schleifer methods

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Schleifer instance variables

Instance variables inherited from Music21Object:

Shake

class music21.expressions.Shake(**keywords)

A slower trill.

>>> shake = expressions.Shake()
>>> shake.quarterLength
0.25

Shake bases

Shake read-only properties

Read-only properties inherited from Trill:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Shake read/write properties

Read/write properties inherited from Trill:

Read/write properties inherited from Music21Object:

Shake methods

Methods inherited from Trill:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Shake instance variables

Instance variables inherited from Music21Object:

Tremolo

class music21.expressions.Tremolo(**keywords)

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

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

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

>>> trem.numberOfMarks = -1
Traceback (most recent call last):
music21.expressions.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 Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

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: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None, inPlace: bool = False) → tuple[list[note.Note | note.Unpitched], note.Note | note.Unpitched | None, list[note.Note | note.Unpitched]]

Realize the ornament

>>> n = note.Note(type='quarter')
>>> trem = expressions.Tremolo()
>>> trem.measured = True  # default
>>> trem.numberOfMarks = 3  # default
>>> trem.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 = trem.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')
>>> trem = expressions.Tremolo()
>>> n.expressions.append(trem)
>>> 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>

>>> trem.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 Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Tremolo instance variables

Instance variables inherited from Music21Object:

TremoloSpanner

class music21.expressions.TremoloSpanner(*spannedElements, **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.TremoloSpanner <music21.note.Note C><music21.note.Note D>>

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

TremoloSpanner bases

TremoloSpanner read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

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:

Methods inherited from ProtoM21Object:

TremoloSpanner instance variables

Instance variables inherited from Music21Object:

Trill

class music21.expressions.Trill(*, accidental: Accidental | None = None, **keywords)

A basic trill marker without the trill extension

>>> tr = expressions.Trill()
>>> tr.placement
'above'
>>> tr.getSize(note.Note('C4'))
<music21.interval.Interval M2>
>>> tr.getSize(note.Note('B4'))
<music21.interval.Interval m2>

Trills have a .nachschlag attribute which determines whether there should be extra gracenotes at the end of the trill.

>>> tr.nachschlag
False
>>> tr.nachschlag = True

The Trill also has a “quarterLength” attribute that sets how long each trill note should be. Defaults to 32nd note:

>>> tr.quarterLength
0.125
>>> tr.quarterLength == duration.Duration('32nd').quarterLength
True

  • Changed in v7: the size should be a generic second.

  • Changed in v9: Support an accidental on trills. This also adds the concept of an ornamental pitch that is processed by makeAccidentals. The size property has been removed and replaced with .getSize() (which requires a srcObj and optional keySig param). Added optional keySig param to .realize() as well.

Trill bases

Trill read-only properties

Trill.direction

The direction of the trill’s ornamental pitch from the main note. Can be ‘up’ or ‘down’.

Trill.name

returns the name of the Trill, which is generally the class name lowercased, with spaces where a new capital occurs. The name also will include the accidental, if it exists.

Subclasses can override this as necessary.

>>> trill = expressions.Trill()
>>> trill.name
'trill'

>>> doubleSharpedTrill = expressions.Trill(accidental=pitch.Accidental('double-sharp'))
>>> doubleSharpedTrill.name
'trill (double-sharp)'
Trill.ornamentalPitch

Returns the trill’s ornamentalPitch. If resolveOrnamentalPitches has not yet been called, None is returned.

Trill.ornamentalPitches

Returns any ornamental pitch that has been resolved (see resolveOrnamentalPitches, which must be called first, or an empty tuple will be returned).

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Trill read/write properties

Trill.accidental

This is the Trill’s accidental. Whether or not it is visible is dictated by the accidental’s displayStatus.

Read/write properties inherited from Music21Object:

Trill methods

Trill.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the trill’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the trill will also be taken into account.

If keySig is specified, this can be considered to be a theoretical question: “If this particular trill were to be attached to this note, in this key, what would the size of the trill interval be?”

Trill.realize(srcObj: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None, inPlace: bool = False) → tuple[list[note.Note | note.Unpitched], note.Note | note.Unpitched | None, list[note.Note | note.Unpitched]]

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.duration.type = 'eighth'
>>> t1 = expressions.Trill()
>>> n1.expressions.append(t1)
>>> realization = t1.realize(n1)
>>> realization
([<music21.note.Note C>,
  <music21.note.Note D>,
  <music21.note.Note C>,
  <music21.note.Note D>], None, [])
>>> realization[0][0].quarterLength
0.125
>>> realization[0][0].pitch.octave
4

When inside a stream, the realizations will consult the current key to see if it should be a whole-step or half-step trill:

>>> m = stream.Measure()
>>> k1 = key.Key('D-')
>>> m.insert(0, k1)
>>> m.append(n1)
>>> t1.realize(n1)
([<music21.note.Note C>,
  <music21.note.Note D->,
  <music21.note.Note C>,
  <music21.note.Note D->], None, [])

Note that if the key contradicts the note of the trill, for instance, here having a C-natural rather than a C-sharp, we do not correct the C to C#.

>>> k2 = key.Key('A')
>>> m.replace(k1, k2)
>>> t1.realize(n1)
([<music21.note.Note C>,
  <music21.note.Note D>,
  <music21.note.Note C>,
  <music21.note.Note D>], None, [])

This can lead to certain unusual circumstances such as augmented second trills which are technically correct, but probably not what a performer exprects.

>>> k3 = key.Key('E')
>>> m.replace(k2, k3)
>>> t1.realize(n1)
([<music21.note.Note C>,
  <music21.note.Note D#>,
  <music21.note.Note C>,
  <music21.note.Note D#>], None, [])

To avoid this case, create a HalfStepTrill or WholeStepTrill.

If there is a nachschlag, it will appear in the third element of the list.

>>> n1.duration.type = 'quarter'
>>> m.replace(k3, k1)  # back to D-flat major
>>> t1.nachschlag = True
>>> t1.realize(n1)
([<music21.note.Note C>,
  <music21.note.Note D->,
  <music21.note.Note C>,
  <music21.note.Note D->,
  <music21.note.Note C>,
  <music21.note.Note D->], None, [<music21.note.Note C>, <music21.note.Note B->])

Some notes can be too short to realize if autoscale is off.

>>> n2 = note.Note('D4')
>>> n2.duration.type = '32nd'
>>> t2 = expressions.Trill()
>>> t2.autoScale = False
>>> t2.realize(n2)
Traceback (most recent call last):
music21.expressions.ExpressionException: The note is not long enough to realize a trill

A quicker trill makes it possible:

>>> t2.quarterLength = duration.Duration('64th').quarterLength
>>> t2.realize(n2)
([<music21.note.Note D>,
  <music21.note.Note E>], None, [])

inPlace is not used for Trills.

Trill.resolveOrnamentalPitches(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None)

Computes and stores the ornamental pitch for a Trill, given the srcObj (can be any kind of ornamented GeneralNote) and an optional keySig.

If keySig is None, srcNote’s context will be searched for a key signature. If no key signature is found, a key signature with no sharps and no flats will be used.

e.g. A trill on a D in a key with no sharps or flats (ornamental pitch will be E).

>>> noSharpsOrFlats = key.KeySignature(0)
>>> n2 = note.Note('D4')
>>> trill = expressions.Trill()
>>> trill.resolveOrnamentalPitches(n2, keySig=noSharpsOrFlats)
>>> trill.ornamentalPitches
(<music21.pitch.Pitch E4>,)
>>> trill.ornamentalPitch
<music21.pitch.Pitch E4>
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>>]
Trill.updateAccidentalDisplay(*, pitchPast: list[Pitch] | None = None, pitchPastMeasure: list[Pitch] | None = None, otherSimultaneousPitches: list[Pitch] | None = None, alteredPitches: list[Pitch] | None = None, cautionaryPitchClass: bool = True, cautionaryAll: bool = False, overrideStatus: bool = False, cautionaryNotImmediateRepeat: bool = True)

Updates accidental display for a Trill’s ornamental pitch. Defined exactly like Pitch.updateAccidentalDisplay, with two changes: Instead of self being the pitch to update, self is an Trill whose ornamentalPitch is to be updated; and we pay no attention to ties, since ornamental notes cannot be tied.

These examples show a Trill whose main note is a G in a key with no sharps or flats, so the trill’s ornamental pitch is an A. We show various situations where the A might or might not end up with a natural accidental.

If updateAccidentalDisplay is called with cautionaryAll, the A gets a (cautionary) natural accidental.

>>> noSharpsOrFlats = key.KeySignature(0)
>>> trill1 = expressions.Trill()
>>> trill1.resolveOrnamentalPitches(note.Note('g4'), keySig=noSharpsOrFlats)
>>> trill1.ornamentalPitch
<music21.pitch.Pitch A4>
>>> trill1.ornamentalPitch.accidental is None
True
>>> past = [pitch.Pitch('a#4'), pitch.Pitch('c#4'), pitch.Pitch('c4')]
>>> trill1.updateAccidentalDisplay(pitchPast=past, cautionaryAll=True)
>>> trill1.ornamentalPitch.accidental, trill1.ornamentalPitch.accidental.displayStatus
(<music21.pitch.Accidental natural>, True)

If updateAccidentalDisplay is called without cautionaryAll, the A gets a natural accidental, because a previous A had a sharp accidental.

>>> trill2 = expressions.Trill()
>>> trill2.resolveOrnamentalPitches(note.Note('g4'), keySig=noSharpsOrFlats)
>>> trill2.ornamentalPitch
<music21.pitch.Pitch A4>
>>> trill2.ornamentalPitch.accidental is None
True
>>> past = [pitch.Pitch('a#4'), pitch.Pitch('c#4'), pitch.Pitch('c4')]
>>> trill2.updateAccidentalDisplay(pitchPast=past)  # should add a natural
>>> trill2.ornamentalPitch.accidental, trill2.ornamentalPitch.accidental.displayStatus
(<music21.pitch.Accidental natural>, True)

If updateAccidentalDisplay is called with cautionaryPitchClass=False, the A does not get a natural accidental because the previous A# was in a different octave.

>>> trill3 = expressions.Trill()
>>> trill3.resolveOrnamentalPitches(note.Note('g4'), keySig=noSharpsOrFlats)
>>> trill3.ornamentalPitch
<music21.pitch.Pitch A4>
>>> trill3.ornamentalPitch.accidental is None
True
>>> past = [pitch.Pitch('a#3'), pitch.Pitch('c#'), pitch.Pitch('c')]
>>> trill3.updateAccidentalDisplay(pitchPast=past, cautionaryPitchClass=False)
>>> trill3.ornamentalPitch.accidental is None
True

If we add a natural accidental to the trill (with displayStatus True), and then updateAccidentalDisplay is called with cautionaryPitchClass=False, the A gets a visible natural accidental because of that added natural accidental.

>>> trill4 = expressions.Trill()
>>> natural = pitch.Accidental('natural')
>>> natural.displayStatus = True
>>> trill4.accidental = natural
>>> trill4.resolveOrnamentalPitches(note.Note('g4'), keySig=noSharpsOrFlats)
>>> trill4.ornamentalPitch
<music21.pitch.Pitch A4>
>>> trill4.ornamentalPitch.accidental
<music21.pitch.Accidental natural>
>>> trill4.ornamentalPitch.accidental.displayStatus
True
>>> past = [pitch.Pitch('a#3'), pitch.Pitch('c#'), pitch.Pitch('c')]
>>> trill4.updateAccidentalDisplay(pitchPast=past, cautionaryPitchClass=False)
>>> trill4.ornamentalPitch.accidental
<music21.pitch.Accidental natural>
>>> trill4.ornamentalPitch.accidental.displayStatus
True

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Trill instance variables

Instance variables inherited from Music21Object:

TrillExtension

class music21.expressions.TrillExtension(*spannedElements, **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 TrillExtension between notes 2 and 3

>>> te = expressions.TrillExtension(s.notes[1], s.notes[2])
>>> s.append(te)  # spanner can go anywhere in the Stream
>>> 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:

Read-only properties inherited from ProtoM21Object:

TrillExtension read/write properties

TrillExtension.placement

Get or set the placement as either above, below, or None.

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

A setting of None implies that the placement will be determined by notation software and no particular placement is demanded.

Read/write properties inherited from Music21Object:

TrillExtension methods

Methods inherited from Spanner:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

TrillExtension instance variables

Instance variables inherited from Music21Object:

Turn

class music21.expressions.Turn(*, delay: ~music21.common.enums.OrnamentDelay | float | ~fractions.Fraction = <OrnamentDelay.NO_DELAY>, upperAccidental: ~music21.pitch.Accidental | None = None, lowerAccidental: ~music21.pitch.Accidental | None = None, **keywords)

A turn or Gruppetto.

  • Changed in v7: size is a Generic second. removed unused nachschlag component.

  • Changed in v9: Added support for delayed vs non-delayed Turn.

  • Changed in v9: Support upper and lower accidentals on turns. This also adds the concept of ornamental pitches that are processed by makeAccidentals. The size property has been removed and replaced with .getSize() (which requires a srcObj and optional keySig param, as well as which=’upper’ or which=’lower’). Added optional keySig param to .realize() as well.

Turn bases

Turn read-only properties

Turn.isDelayed

Whether the Turn is delayed (i.e. between a specific note and the following note) or not (i.e. exactly on a specific note).

Turn.lowerOrnamentalPitch

Returns the turn’s lower ornamental pitch. If resolveOrnamentalPitches has not yet been called, None is returned.

Turn.name

returns the name of the Turn/InvertedTurn, which is generally the class name lowercased, with spaces where a new capital occurs, but also with a ‘delayed’ prefix, if the Turn/InvertedTurn is delayed. If the delay is of a specific duration, the prefix will include that duration. The name also will include upper and lower accidentals, if they exist.

Subclasses can override this as necessary.

>>> nonDelayedTurn = expressions.Turn()
>>> nonDelayedTurn.name
'turn'

>>> from music21.common.enums import OrnamentDelay
>>> delayedInvertedTurn = expressions.InvertedTurn(
...     delay=OrnamentDelay.DEFAULT_DELAY,
...     upperAccidental=pitch.Accidental('sharp'),
...     lowerAccidental=pitch.Accidental('natural')
... )
>>> delayedInvertedTurn.name
'delayed inverted turn (upper=sharp, lower=natural)'

>>> delayedBy1Turn = expressions.Turn(
...     delay=1.0, lowerAccidental=pitch.Accidental('double-flat'))
>>> delayedBy1Turn.name
'delayed(delayQL=1.0) turn (lower=double-flat)'
Turn.ornamentalPitches

Returns any ornamental pitches that have been resolved (see resolveOrnamentalPitches, which must be called first, or an empty tuple will be returned).

Turn.upperOrnamentalPitch

Returns the turn’s upper ornamental pitch. If resolveOrnamentalPitches has not yet been called, None is returned.

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

Turn read/write properties

Turn.delay

If delay is NO_DELAY, the turn is not delayed.

If delay is anything else (an OffsetQL or DEFAULT_DELAY), the turn is delayed.

Note that if you set delay to OffsetQL(0), and then get the delay, you will get NO_DELAY, not 0.

Turn.lowerAccidental

This is the Turn’s lowerAccidental. Whether or not it is visible is dictated by the upperAccidental’s displayStatus.

Turn.upperAccidental

This is the Turn’s upperAccidental. Whether or not it is visible is dictated by the upperAccidental’s displayStatus.

Read/write properties inherited from Music21Object:

Turn methods

Turn.getSize(srcObj: note.GeneralNote, which: str, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of one of the turn’s two intervals (which=’upper’ or which=’lower’), given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any upperAccidental or lowerAccidental that has been set on the turn will also be taken into account. If either has not been set, the appropriate accidental from the key signature will be used.

If keySig is specified, this can be considered to be a theoretical question: “If this particular turn were to be attached to this note, in this key, what would the (‘upper’ or ‘lower’) size of the turn interval be?”

Turn.realize(srcObj: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None, inPlace: bool = False) → tuple[list[note.Note | note.Unpitched], note.Note | note.Unpitched | None, list[note.Note | note.Unpitched]]

realize a turn.

returns a three-element tuple. The first element is an empty list because there are no notes at the start of a turn. The second element is the original note with a duration equal to the delay (but if there is no delay, the second element is None, because the turn “eats up” the entire note). The third element is a list of the four turn notes, adding up to the duration of the original note (less the delay, if there is one). The four turn notes will either be of equal duration, or the fourth note will be longer, to “eat up” the entire note.

>>> from  music21 import *
>>> from music21.common.enums import OrnamentDelay
>>> m1 = stream.Measure()
>>> m1.append(key.Key('F', 'major'))
>>> n1 = note.Note('C5')
>>> m1.append(n1)
>>> t1 = expressions.Turn()
>>> t1.realize(n1)
([], None, [<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', type='quarter')
>>> m2.append(n2)
>>> t2 = expressions.InvertedTurn(delay=OrnamentDelay.DEFAULT_DELAY)
>>> n2.expressions.append(t2)
>>> t2.realize(n2)
([], <music21.note.Note B>, [<music21.note.Note A#>,
                             <music21.note.Note B>,
                             <music21.note.Note C#>,
                             <music21.note.Note B>])

Realizing an expression leaves the original note and expression alone

>>> n2.duration.type
'quarter'
>>> n2.expressions
[<music21.expressions.InvertedTurn>]

If inPlace is True then the note is affected and the turn is removed from .expressions:

>>> n2 = note.Note('C4')
>>> n2.duration.type = '32nd'
>>> t2 = expressions.Turn(delay=OrnamentDelay.DEFAULT_DELAY)
>>> _empty, newOrigNote, turnNotes = t2.realize(n2, inPlace=True)
>>> for turnNote in turnNotes:
...     print(turnNote, turnNote.duration.type)
<music21.note.Note D> 256th
<music21.note.Note C> 256th
<music21.note.Note B> 256th
<music21.note.Note C> 256th
>>> n2.duration.type
'64th'
>>> n2.expressions
[]
>>> newOrigNote is n2
True

If the four turn notes (self.quarterLength each) don’t add up to the original note duration, the fourth turn note should be held to the length of any remaining unused duration. Here, for example, we have a dotted eighth note total duration, a delay of a 16th note, and a turn note duration of a triplet 32nd note, leaving the fourth turn note with a duration of a 16th note. This sort of turn is seen all over the music of Weber.

>>> from fractions import Fraction
>>> n3 = note.Note('C4')
>>> n3.quarterLength = 0.75
>>> t3 = expressions.Turn(delay=0.25)
>>> t3.quarterLength = 0.125 * Fraction(2, 3)
>>> _empty, newOrigNote, turnNotes = t3.realize(n3, inPlace=True)
>>> print(newOrigNote, newOrigNote.quarterLength)
<music21.note.Note C> 0.25
>>> for turnNote in turnNotes:
...     print(turnNote, turnNote.quarterLength)
<music21.note.Note D> 1/12
<music21.note.Note C> 1/12
<music21.note.Note B> 1/12
<music21.note.Note C> 0.25

If .autoScale is off and the note is not long enough to realize 4 32nd notes, then an exception is raised.

>>> n2 = note.Note('C4')
>>> n2.duration.type = '32nd'
>>> t2 = expressions.Turn()
>>> t2.autoScale = False
>>> t2.realize(n2)
Traceback (most recent call last):
music21.expressions.ExpressionException: The note is not long enough to realize a turn
Turn.resolveOrnamentalPitches(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None)

Computes and stores the ornamental pitches for a Turn, given the srcObj (can be any kind of ornamented GeneralNote) and an optional keySig.

If keySig is None, srcNote’s context will be searched for a key signature. If no key signature is found, a key signature with no sharps and no flats will be used.

e.g. A turn on a D in a key with two flats (upper ornamental pitch will be E flat, lower ornamental pitch will be C).

>>> twoFlats = key.KeySignature(sharps=-2)
>>> n1 = note.Note('D4')
>>> turn = expressions.Turn()
>>> turn.resolveOrnamentalPitches(n1, keySig=twoFlats)
>>> turn.ornamentalPitches
(<music21.pitch.Pitch E-4>, <music21.pitch.Pitch C4>)
>>> turn.upperOrnamentalPitch
<music21.pitch.Pitch E-4>
>>> turn.lowerOrnamentalPitch
<music21.pitch.Pitch C4>

e.g. A turn with a sharp over it and a flat under it, on a C, in a key with no sharps or flats (upper ornamental pitch will be D#, lower ornamental pitch will be B flat).

>>> noSharpsOrFlats = key.KeySignature(0)
>>> n2 = note.Note('C4')
>>> turn = expressions.Turn(
...     upperAccidental=pitch.Accidental('sharp'),
...     lowerAccidental=pitch.Accidental('flat'))
>>> turn.resolveOrnamentalPitches(n2, keySig=noSharpsOrFlats)
>>> turn.ornamentalPitches
(<music21.pitch.Pitch D#4>, <music21.pitch.Pitch B-3>)
>>> turn.upperOrnamentalPitch
<music21.pitch.Pitch D#4>
>>> turn.lowerOrnamentalPitch
<music21.pitch.Pitch B-3>
Turn.updateAccidentalDisplay(*, pitchPast: list[Pitch] | None = None, pitchPastMeasure: list[Pitch] | None = None, otherSimultaneousPitches: list[Pitch] | None = None, alteredPitches: list[Pitch] | None = None, cautionaryPitchClass: bool = True, cautionaryAll: bool = False, overrideStatus: bool = False, cautionaryNotImmediateRepeat: bool = True)

Updates accidental display for a Turn’s ornamental pitches (upper and lower). Defined exactly like Pitch.updateAccidentalDisplay, with two changes: Instead of self being the pitch to update, self is a Turn whose ornamentalPitches are to be updated; and we pay no attention to ties, since ornamental notes cannot be tied.

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

Turn instance variables

Instance variables inherited from Music21Object:

WholeStepAppoggiatura

class music21.expressions.WholeStepAppoggiatura(**keywords)

WholeStepAppoggiatura bases

WholeStepAppoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

WholeStepAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

WholeStepAppoggiatura methods

Methods inherited from GeneralAppoggiatura:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

WholeStepAppoggiatura instance variables

Instance variables inherited from Music21Object:

WholeStepInvertedAppoggiatura

class music21.expressions.WholeStepInvertedAppoggiatura(**keywords)

WholeStepInvertedAppoggiatura bases

WholeStepInvertedAppoggiatura read-only properties

Read-only properties inherited from Ornament:

Read-only properties inherited from Expression:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

WholeStepInvertedAppoggiatura read/write properties

Read/write properties inherited from Music21Object:

WholeStepInvertedAppoggiatura methods

Methods inherited from GeneralAppoggiatura:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

WholeStepInvertedAppoggiatura instance variables

Instance variables inherited from Music21Object:

WholeStepInvertedMordent

class music21.expressions.WholeStepInvertedMordent(**keywords)

A whole-step inverted Mordent.

>>> m = expressions.WholeStepInvertedMordent()
>>> m.direction
'up'
>>> m.getSize(note.Note('C4'))
<music21.interval.Interval M2>

WholeStepInvertedMordent bases

WholeStepInvertedMordent read-only properties

Read-only properties inherited from GeneralMordent:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

WholeStepInvertedMordent read/write properties

WholeStepInvertedMordent.accidental

Read/write properties inherited from Music21Object:

WholeStepInvertedMordent methods

WholeStepInvertedMordent.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the mordent’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the mordent will also be taken into account. If no accidental has been set, the appropriate accidental from the key signature will be used.

If keySig is specified, this can be considered to be a theoretical question: “If this particular mordent were to be attached to this note, in this key, what would the size of the mordent interval be?”

Methods inherited from GeneralMordent:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

WholeStepInvertedMordent instance variables

Instance variables inherited from Music21Object:

WholeStepMordent

class music21.expressions.WholeStepMordent(**keywords)

A whole step normal Mordent.

>>> m = expressions.WholeStepMordent()
>>> m.direction
'down'
>>> m.getSize(note.Note('C4'))
<music21.interval.Interval M-2>

WholeStepMordent bases

WholeStepMordent read-only properties

Read-only properties inherited from GeneralMordent:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

WholeStepMordent read/write properties

WholeStepMordent.accidental

Read/write properties inherited from Music21Object:

WholeStepMordent methods

WholeStepMordent.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the mordent’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the mordent will also be taken into account. If no accidental has been set, the appropriate accidental from the key signature will be used.

If keySig is specified, this can be considered to be a theoretical question: “If this particular mordent were to be attached to this note, in this key, what would the size of the mordent interval be?”

Methods inherited from GeneralMordent:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

WholeStepMordent instance variables

Instance variables inherited from Music21Object:

WholeStepTrill

class music21.expressions.WholeStepTrill(**keywords)

A trill that yields whole steps no matter what.

>>> wholeTrill = expressions.WholeStepTrill()
>>> wholeTrill.placement
'above'
>>> wholeTrill.getSize(note.Note('C4'))
<music21.interval.Interval M2>

Here the key signature of one sharp will not affect the trill:

>>> n = note.Note('B4', type='eighth')
>>> m = stream.Measure()
>>> m.insert(0, key.KeySignature(1))
>>> m.append(n)
>>> wholeTrill.realize(n)
([<music21.note.Note B>,
  <music21.note.Note C#>,
  <music21.note.Note B>,
  <music21.note.Note C#>], None, [])

WholeStepTrill bases

WholeStepTrill read-only properties

Read-only properties inherited from Trill:

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

WholeStepTrill read/write properties

WholeStepTrill.accidental

Read/write properties inherited from Music21Object:

WholeStepTrill methods

WholeStepTrill.getSize(srcObj: note.GeneralNote, *, keySig: key.KeySignature | None = None) → interval.IntervalBase

Returns the size of the trill’s interval, given a source note and an optional key signature. If the key signature is not specified, the source note’s context is searched for the current key signature, and if there is no such key signature, a key signature with no sharps and no flats will be used. Any accidental that has been set on the trill will also be taken into account.

If keySig is specified, this can be considered to be a theoretical question: “If this particular trill were to be attached to this note, in this key, what would the size of the trill interval be?”

Methods inherited from Trill:

Methods inherited from Ornament:

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

WholeStepTrill instance variables

Instance variables inherited from Music21Object:

Functions

music21.expressions.isUnison(intv: IntervalBase) → bool
music21.expressions.realizeOrnaments(srcObj: note.Note | note.Unpitched, *, keySig: key.KeySignature | None = None)

given a Note or Unpitched 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