Notation

class maelzel.scoring.Notation(duration, pitches=None, offset=None, isRest=False, tiedPrev=False, tiedNext=False, dynamic='', durRatios=(), group='', gliss=False, color='', sizeFactor=1, properties=None, fixNotenames=False, _init=True)

Bases: object

This represents a notation (a rest, a note or a chord)

Parameters:

• duration (Union[float, int, Fraction]) – the duration of this Notation, in quarter-notes. 0 indicates a grace note

• pitches (Optional[list[Union[int, float, str]]]) – if given, a list of pitches as midinote or notename.

• offset (Union[float, int, Fraction, None]) – the offset of this Notation, in quarter-notes.

• isRest – is this a rest?

• tiedPrev – is this Notation tied to the previous one?

• tiedNext – is it tied to the next

• dynamic (str) – the dynamic of this notation, one of “p”, “pp”, “f”, etc.

• group – a str identification, can be used to group Notations together

• durRatios (tuple[Fraction, ...]) – a list of tuples (x, y) indicating a tuple relationship. For example, a Notation used to represent one 8th note in a triplet would have the duration 1/3 and durRatios=[(3, 2)]. Multiplying the duration by the durRatios would result in the notated value, in this case 1/2 (1 being a quarter note). A value of None is the same as a value of [(1, 1)] (no modification)

• gliss – if True, a glissando will be rendered between this note and the next

• color – the color of this notations

• stem – if given, one of

• fixNotenames – if True, pitches given as strings are fixed to the given spelling

Attributes Summary

attachments	Attachments are gathered here
color	The color of this entire Notation
durRatios	A set of ratios to apply to .duration to convert it to its notated duration
duration	The duration of this Notation, in quarternotes
dynamic	A dynamic mark
end	The end time of this notation.
fixedNotenames	A dict mapping pitch index to spelling
gliss	Is this Notation part of a glissando?
groupid	The group id this Notation belongs to, if applicable
isGracenote	Is this a gracenote?
isRealnote	A real note is not a rest and not a gracenote
isRest	Is this a Rest?
isStemless	Is this Notation stemless?
mergeable
noteheads	A dict mapping pitch index to notehead definition
offset	The start time in quarternotes
pitches	The pitches of this Notation (without spelling, just midinotes)
properties	A dict of user properties.
qoffset	Quantized offset, ensures that it is never None
quantized	Is this Notation quantized?
sizeFactor	bigger, 2: even bigger, -1: smaller, etc.)
spanners	A list of spanners this Notations is part of
stem
tiedNext	Is this Notation tied to the next one?
tiedPrev	Is this Notation tied to the previous one?

Methods Summary

accidentalDirection([index, minAlteration])	Returns the direction of the alteration in this notation
addArticulation(articulation[, color, placement])	Add an articulation to this Notation.
addAttachment(attachment)	Add an attachment to this Notation
addSpanner(spanner[, end])	Add a Spanner to this Notation
addText(text[, placement, fontsize, italic, ...])	Add a text annotation to this Notation.
asRest()	rtype: Notation
canMergeWith(other)	Can this Notation merge with other?
checkIntegrity([fix])	Checks the integrity of self
clearClefHints()	Remove any clef hints from this Notation :rtype: None
clearFixedNotenames()	rtype: None
clone([copyFixedNotenames])	Clone this Notation, overriding any value.
cloneAsTie(duration, offset[, tiedPrev, ...])	Clone self so that the cloned Notation can be used within a logical tie
copy()	Copy this Notation
copyAttachmentsTo(dest)	Copy any attachments in self to dest Notation
copyAttributesTo(dest[, spelling])	Copy attributes of self to dest
copyFixedSpellingTo(other)	Copy fixed spelling to other
delProperty(key)	Remove the given property
extractPartialNotation(indexes)	Extract part of a chord with any attachments corresponding to the given pitches
findAttachment(cls[, anchor, predicate])	Find an attachment by class or classname
findSpanner(uuid[, kind])	Find a spanner with the given attributes
fixNotename(notename[, idx])	Fix the spelling for the pitch at index inplace
fixedSlots([semitoneDivs])	Calculate the fixed slots within this chord
fusedDurRatio()	rtype: Fraction
getAttachments([cls, predicate, anchor])	Get a list of Attachments matching the given criteria
getClefHint([idx])	Get any clef hint for this notation or a particular pitch thereof
getFixedNotename([idx])	Returns the fixed notename of this notation, if any
getNotehead([index])	Get a Notehead by index
getProperty(key[, default, setdefault])	Get the value of a property.
hasAttributes()	True if this notation has information attached
hasRegularDuration()	rtype: bool
hasSpanner(uuid[, kind])	Returns true if a spanner with the given uuid is found
makeArtificialHarmonic(basepitch, interval, ...)	rtype: Notation
makeRest(duration[, offset, dynamic, annotation])	Shortcut function to create a rest notation.
meanPitch()	The mean pitch of this note/chord
mergeWith(other)	Merge this Notation with other
notatedDuration()	The duration of the notated figure as a NotatedDuration
notename([index, addExplicitMark])	Returns the notename corresponding to the given pitch index
pitchclassIndex([semitoneDivs, index])	The index of the nearest pitch/microtone
quantizedPitches([divs])	Quantize the pitches of this Notation
removeAttachments(predicate)	Remove attachments where predicate is True
removeAttachmentsByClass(cls)	Remove attachments which match the given class
removeSpanner(spanner)	Removes the given spanner from this Notation
removeSpanners()	Remove all spanners from this Notation
resolveHarmonic([removeAttachment])	Realize an artificial harmonic as a chord with the corresponding noteheads
resolveNotenames([addFixedAnnotation])	Resolve the enharmonic spellings for this Notation
setClefHint(clef[, idx])	Sets a hint regarding which clef to use for this notation
setNotehead(notehead[, idx, merge])	Set a notehead in this notation
setPitches(pitches[, fixNotenames])	Set the pitches of this notation, in place
setProperty(key, value)	Set any property of this Notation.
splitAtOffsets(offsets)	Splits a Notation at the given offsets
symbolicDuration()	The symbolic duration of this Notation.
transferSpanner(spanner, other)	Move the given spanner to another Notation
verticalPosition([index])	The vertical position of the notated note at given index

Attributes Documentation

attachments: list[Attachment] | None

Attachments are gathered here

color: str

The color of this entire Notation

durRatios: tuple[Fraction, ...]

A set of ratios to apply to .duration to convert it to its notated duration

see Notation.notatedDuration()

duration: Fraction

The duration of this Notation, in quarternotes

dynamic: str

A dynamic mark

end

The end time of this notation.

Raises an exception if this Notation has no offset

fixedNotenames: dict[int, str] | None

A dict mapping pitch index to spelling

gliss: bool

Is this Notation part of a glissando?

groupid: str

The group id this Notation belongs to, if applicable

isGracenote

Is this a gracenote?

isRealnote

A real note is not a rest and not a gracenote

isRest: bool

Is this a Rest?

isStemless

Is this Notation stemless?

This property can be set by adding a StemTraits attachment

mergeable

noteheads: dict[int, Notehead] | None

A dict mapping pitch index to notehead definition

offset: Fraction | None

The start time in quarternotes

pitches: list[float]

The pitches of this Notation (without spelling, just midinotes)

properties: dict[str, Any] | None

A dict of user properties. To be set via setProperty

qoffset

Quantized offset, ensures that it is never None

quantized

Is this Notation quantized?

sizeFactor: int

bigger, 2: even bigger, -1: smaller, etc.)

Type:

A size factor applied to this Notation (0

Type:

normal, 1

spanners: list[Spanner] | None

A list of spanners this Notations is part of

stem

tiedNext: bool

Is this Notation tied to the next one?

tiedPrev: bool

Is this Notation tied to the previous one?

Methods Documentation

accidentalDirection(index=0, minAlteration=0.5)

Returns the direction of the alteration in this notation

Parameters:

• index – index of the pitch within this Notation

• minAlteration – threshold (with minAlteration 0.5 C+ gets a direction of +1, whereas C+25 still gets a direction of 0)

Return type:

int

Returns:

one of -1, 0 or +1, corresponding to the direction of the alteration (flat, natural or sharp)

addArticulation(articulation, color='', placement='')

Add an articulation to this Notation.

See definitions.articulations for possible values. We understand articulation in a broad sense as any symbol attached to a note/chord

Parameters:

• articulation (str | Articulation) – an Articulation object, or one of accent, staccato, tenuto,

• marcato

• staccatissimo

• espressivo

• portato

• arpeggio

• upbow

:param : :param downbow: :param flageolet: :param open: :param closed: :param stopped: :param snappizz: :type color: :param color: if given, color of the articulation :type placement: :param placement: one of ‘above’, ‘below’. If not given, the default placement

for the given articulation is used

Return type:

Notation

Returns:

self

addAttachment(attachment)

Add an attachment to this Notation

An attachment is any kind of note attached symbol or text expression (a Fermata, a Text, an Articulation, an Ornament, etc.). To add a spanner (a slur, a bracket, etc.) see addSpanner.

Note

Some kinds of attachments are exclusive. Adding an exclusive attachment (like a certain text) will remove any previous such attachment.

Parameters:

attachment (Attachment) – an instance of scoring.attachment.Attachment

Return type:

Notation

Returns:

self

addSpanner(spanner, end=None)

Add a Spanner to this Notation

Spanners always are bound in pairs. A ‘start’ spanner is attached to one Notation, an ‘end’ spanner with the same uuid is attached to the notation where the spanner should end (see Spanner.bind())

Parameters:

• spanner (Spanner) – the spanner to add.

• end (Optional[Notation]) – the end anchor of the spanner

Return type:

Notation

Returns:

self

addText(text, placement='above', fontsize=None, italic=False, weight='normal', fontfamily='', box=False, exclusive=False, role='')

Add a text annotation to this Notation.

Parameters:

• text (str | Text) – the text of the annotation, or a Text object itself If passed a Text objecj, all other parameters will not be considered

• placement – where to place the text annotation, one of ‘above’ or ‘below’

• fontsize (Union[int, float, None]) – the size of the font

• box (str | bool) – if True, the text is enclosed in a box. A string indicates the shape of the box

• italic – if True, use italic style

• weight – one of ‘normal’, ‘bold’

• fontfamily – the font used

• role – either unset or one of ‘measure’, …

• exclusive – if True, only one text annotation with the given text and attributes is allowed. This enables to set a given text for a Notation without needing to check at the callsite that this text is already present

Return type:

None

asRest()

Return type:

Notation

canMergeWith(other)

Can this Notation merge with other?

Return type:

bool

checkIntegrity(fix=False)

Checks the integrity of self

Parameters:

fix – if True, attempts to fix the probelms found, if possible

Return type:

list[str]

Returns:

a list of error messages

clearClefHints()

Remove any clef hints from this Notation :rtype: None

See also

Notation.getClefHint(), Notation.setClefHint()

clearFixedNotenames()

Return type:

None

clone(copyFixedNotenames=True, **kws)

Clone this Notation, overriding any value.

Parameters:

• copyFixedNotenames – transfer any fixed notenames to the cloned notation

• kws – keyword arguments, as passed to the Notation constructor. Any parameter given will override the corresponding value in this Notation

Return type:

Notation

cloneAsTie(duration, offset, tiedPrev=True, tiedNext=None, gliss=None)

Clone self so that the cloned Notation can be used within a logical tie

This is used when a notation is split across a measure or a beam or within a tuplet

Return type:

Notation

Returns:

The cloned Notation

copy()

Copy this Notation

Return type:

Notation

copyAttachmentsTo(dest)

Copy any attachments in self to dest Notation

Return type:

None

copyAttributesTo(dest, spelling=True)

Copy attributes of self to dest

Return type:

None

copyFixedSpellingTo(other)

Copy fixed spelling to other

delProperty(key)

Remove the given property

Parameters:

key (str) – the key to remove

Return type:

None

extractPartialNotation(indexes)

Extract part of a chord with any attachments corresponding to the given pitches

Parameters:

indexes (list[int]) – the indexes of the pitches to extract

Return type:

Notation

Returns:

a new Notation with the given pitches

findAttachment(cls, anchor=UNSET, predicate=None)

Find an attachment by class or classname

Similar to getAttachments, returns only one attachment or None :type cls: str | type :param cls: the class to match (the class itself or its name, case is not relevant) :type predicate: Optional[Callable] :param predicate: a function (attachment) -> bool :type anchor: int | None | Unset :param anchor: if given, the anchor index to match. Some attachments are anchored to

a specific component (pitch) in the notation (for example a notehead or an accidental trait are attached to a specific pitch of the chord)

Return type:

Attachment | None

Returns:

an Attachment matching the given criteria, or None

findSpanner(uuid, kind='')

Find a spanner with the given attributes

Parameters:

• uuid (str) – the uuid of the spanner

• kind – the kind of the spanner, one of ‘start’ / ‘end’

Return type:

Spanner | None

fixNotename(notename, idx=None)

Fix the spelling for the pitch at index inplace

Parameters:

• notename (str) – if given, it will be fixed to the given notename. If nothing is given, it will be fixed to n2m(self.pitches[idx])

• idx (Optional[int]) – the index of the note to modify. If None, a matching pitch in this notation is searched. ValueError is raised if no pitch is found

Return type:

None

See also

Notation.notenames()

fixedSlots(semitoneDivs=2)

Calculate the fixed slots within this chord

Parameters:

semitoneDivs – the number of divisions of the semitone.

Return type:

dict[int, int] | None

Returns:

a dict mapping slot to alteration direction

fusedDurRatio()

Return type:

Fraction

getAttachments(cls='', predicate=None, anchor=UNSET)

Get a list of Attachments matching the given criteria

Parameters:

• cls (str | type) – the class to match (the class itself or its name, case is not relevant)

• predicate (Optional[Callable]) – a function (attachment) -> bool

• anchor (int | None | Unset) – if given, the anchor index to match. Some attachments are anchored to a specific component (pitch) in the notation (for example a notehead or an accidental trait are attached to a specific pitch of the chord)

Return type:

list[Attachment]

Returns:

the list of attachments matching the given criteria

getClefHint(idx=0)

Get any clef hint for this notation or a particular pitch thereof

Warning

This is mostly used internally and is an experimental feature which might be implemented using other means in the future

Parameters:

idx (int) – which pitch index to query

Return type:

str | None

Returns:

the clef hint, if any

getFixedNotename(idx=0)

Returns the fixed notename of this notation, if any

Parameters:

idx (int) – 0 in the case of a note, the index of the note if representing a chord

Return type:

str | None

Returns:

the fixed spelling of the note, if exists (None otherwise)

getNotehead(index=0)

Get a Notehead by index

Parameters:

index – the notehead index. This corresponds to the pitch index in self.pitches

Return type:

Notehead | None

Returns:

the Notehead or None if not defined

getProperty(key, default=None, setdefault=None)

Get the value of a property.

Parameters:

• key (str) – the key to query

• setdefault – if given, sets properties[key] = value if not already set

• default – like setdefault but never modifies the actual properties

Return type:

Any

Returns:

the value of the given property, or a fallback value

hasAttributes()

True if this notation has information attached

Information is any dynanic, attachments, spanners, etc.

Return type:

bool

hasRegularDuration()

Return type:

bool

hasSpanner(uuid, kind='')

Returns true if a spanner with the given uuid is found

Return type:

bool

classmethod makeArtificialHarmonic(basepitch, interval, **kws)

Return type:

Notation

static makeRest(duration, offset=None, dynamic='', annotation='')

Shortcut function to create a rest notation.

A rest is only needed when stacking notations within a container like Chain or Track, to signal a spacing between notations. Just explicitely setting the offset of a notation has the same effect

Parameters:

• duration (Union[float, int, Fraction]) – the duration of the rest

• offset (Union[float, int, Fraction, None]) – the start time of the rest. Normally a rest’s offset is left unspecified (None)

• dynamic (str) – if given, attach this dynamic to the rest

• annotation (str) – if given, attach this text annotation to the rest

Return type:

Notation

Returns:

the created rest (a Notation)

meanPitch()

The mean pitch of this note/chord

This is provided to have a generalized way of quering the pitch of a note/chord for packing

Return type:

float

Returns:

the pitchof this note or the avg. pitch if it is a chord. Rests do not have a mean pitch and calling this on a rest will raise ValueError

mergeWith(other)

Merge this Notation with other

Return type:

Notation

notatedDuration()

The duration of the notated figure as a NotatedDuration

A quarter-note inside a triplet would have a notatedDuration of 1

Return type:

NotatedDuration

notename(index=0, addExplicitMark=False)

Returns the notename corresponding to the given pitch index

If there is a fixed notename for the pitch, that will be returned; otherwise the notename corresponding to the pitch

Parameters:

• index – the index of the pitch (in self.pitches)

• addExplicitMark – if True, the notename is suffixed with a ‘!’ sign if the spelling has been fixed

Return type:

str

Returns:

the notename corresponing to the given pitch

pitchclassIndex(semitoneDivs=2, index=0)

The index of the nearest pitch/microtone

Parameters:

• semitoneDivs – the number of divisions per semitone (1=chromatic, 2=quartertones, …)

• index – the index of the pitch within this Notation

Return type:

int

For example, if divs_per_semitone is 2, then

note	microtone index
4C	0
5C	0
4C+	1
4C#	2
4Db	2
…	…

quantizedPitches(divs=4)

Quantize the pitches of this Notation

Parameters:

divs – the number of divisions per semitone

Return type:

list[float]

Returns:

the quantized pitches as midinotes

removeAttachments(predicate)

Remove attachments where predicate is True

Parameters:

predicate (Callable[[Attachment], bool]) – a function taking an Attachment, returns True if it should be removed

Return type:

None

removeAttachmentsByClass(cls)

Remove attachments which match the given class

Return type:

None

removeSpanner(spanner)

Removes the given spanner from this Notation

Parameters:

spanner (Spanner | str) – the spanner to remove or the uuid of the spanner to remove

Return type:

None

removeSpanners()

Remove all spanners from this Notation

Return type:

None

resolveHarmonic(removeAttachment=False)

Realize an artificial harmonic as a chord with the corresponding noteheads

Return type:

Notation

Returns:

the modified Notation or self if this Notation is not a harmonic

resolveNotenames(addFixedAnnotation=False)

Resolve the enharmonic spellings for this Notation

Parameters:

• addFixedAnnotation – if True, enforce the returned spelling by adding

• suffix. (a '!')

Return type:

list[str]

Returns:

the notenames of each pitch in this Notation

setClefHint(clef, idx=None)

Sets a hint regarding which clef to use for this notation

Warning

This is mostly used internally and is an experimental feature. It is conceived for the case where two notations are bound by a glissando, and they should be placed together, even if the pitch of some of them might indicate otherwise

Parameters:

• clef (str) – the clef to set, one of ‘treble’, ‘bass’ or ‘treble8’, ‘treble15’ or ‘bass8’

• idx (Optional[int]) – the index of the pitch within a chord, or None to apply to the whole notation

Return type:

None

setNotehead(notehead, idx=None, merge=False)

Set a notehead in this notation

Parameters:

• notehead (Notehead | str) – a Notehead or the notehead shape, as string (one of ‘normal’, ‘hidden’, ‘cross’, ‘harmonic’, ‘rhombus’, ‘square’, etc.). See maelzel.scoring.definitions.noteheadShapes for a complete list

• idx (Optional[int]) – the index, corresponding to the pitch at the same index, or None to set all noteheads

• merge – if True and there is already a Notehead set for the given index, the new properties are merged with the properties of the already existing notehead

Return type:

None

setPitches(pitches, fixNotenames=False)

Set the pitches of this notation, in place

Parameters:

• pitches (list[float | str]) – a list of midinotes or notenames, or any combination

• fixNotenames – if True, fix the notenames for those pitches given as strings. Notenames can also be fixed with a ‘!’ suffix

Return type:

None

setProperty(key, value)

Set any property of this Notation.

Properties can be used, for example, for any rendering backend to pass directives which are specific to that rendering backend.

Parameters:

• key (str) – the key to set

• value – the value of the property.

Return type:

None

splitAtOffsets(offsets)

Splits a Notation at the given offsets

Parameters:

• self (Notation) – the Notation to split

• offsets (Sequence[Fraction]) – the offsets at which to split n

Return type:

list[Notation]

Returns:

the parts after splitting

Example:

>>> splitAtOffsets(Notation(F(0.5), duration=F(1)))
[Notation(0.5, duration=0.5), Notation(1, duration=0.5)]

symbolicDuration()

The symbolic duration of this Notation.

This represents the notated figure (1=quarter, 1/2=eighth note, 1/4=16th note, etc)

Return type:

Fraction

transferSpanner(spanner, other)

Move the given spanner to another Notation

Parameters:

• spanner (Spanner) – the spanner to transfer

• other (Notation) – the destination notation

Return type:

bool

Returns:

True if the spanner was actually transferred

This is done when replacing a Notation within a Node but there is a need to keep the spanner

verticalPosition(index=0)

The vertical position of the notated note at given index

The vertical position is the position within the staff in terms of lines/spaces. It is calculated as octave*7 + diatonic_index

Note	Vertical Position
4C	28
4C#	28
4D	29
4Eb	30
…	…

Parameters:

index – the index of the pitch within this notation

Return type:

int

Returns:

the vertical position