music21.note¶
Classes and functions for creating Notes, Rests, and Lyrics.
The Pitch
object is stored within,
and used to configure, Note
objects.
Note¶
-
class
music21.note.
Note
(pitchName=None, **keywords)¶ One of the most important music21 classes, a Note stores a single note (that is, not a rest or an unpitched element) that can be represented by one or more notational units – so for instance a C quarter-note and a D# eighth-tied-to-32nd are both a single Note object.
A Note knows both its total duration and how to express itself as a set of tied notes of different lengths. For instance, a note of 2.5 quarters in length could be half tied to eighth or dotted quarter tied to quarter.
The first argument to the Note is the pitch name (with or without octave, see the introduction to
music21.pitch.Pitch
). Further arguments can be specified as keywords (such as type, dots, etc.) and are passed to the underlyingmusic21.duration.Duration
element.>>> n = note.Note() >>> n <music21.note.Note C> >>> n.pitch <music21.pitch.Pitch C4>
>>> n = note.Note('B-') >>> n.name 'B-' >>> n.octave is None True >>> n.pitch.implicitOctave 4
>>> n = note.Note(name='D#') >>> n.name 'D#' >>> n = note.Note(nameWithOctave='D#5') >>> n.nameWithOctave 'D#5'
Other ways of instantiating a Pitch object, such as by MIDI number or pitch class are also possible:
>>> note.Note(64).nameWithOctave 'E4'
Two notes are considered equal if their most important attributes (such as pitch, duration, articulations, and ornaments) are equal. Attributes that might change based on the wider context of a note (such as offset) are not compared. This test does not look at lyrics in establishing equality. (It may in the future.)
>>> note.Note('C4') == note.Note('C4') True
Note
bases
Note
read-only properties
-
Note.
fullName
¶ Return the most complete representation of this Note, providing duration and pitch information.
>>> n = note.Note('A-', quarterLength=1.5) >>> n.fullName 'A-flat Dotted Quarter Note'
>>> n = note.Note('E~3', quarterLength=2) >>> n.fullName 'E-half-sharp in octave 3 Half Note'
>>> n = note.Note('D', quarterLength=0.25) >>> n.pitch.microtone = 25 >>> n.fullName 'D (+25c) 16th Note'
Read-only properties inherited from Music21Object
:
Read-only properties inherited from ProtoM21Object
:
Note
read/write properties
-
Note.
nameWithOctave
¶ Return or set the pitch name with octave from the
Pitch
object. See Pitch’s attributenameWithOctave
.
-
Note.
pitches
¶ Return the
Pitch
object in a tuple. This property is designed to provide an interface analogous to that found onChord
so that [c.pitches for c in s.notes] provides a consistent interface for all objects.>>> n = note.Note('g#') >>> n.nameWithOctave 'G#' >>> n.pitches (<music21.pitch.Pitch G#>,)
Since this is a Note, not a chord, from the list or tuple, only the first one will be used:
>>> n.pitches = [pitch.Pitch('c2'), pitch.Pitch('g2')] >>> n.nameWithOctave 'C2' >>> n.pitches (<music21.pitch.Pitch C2>,)
The value for setting must be a list or tuple:
>>> n.pitches = pitch.Pitch('C4') Traceback (most recent call last): music21.note.NoteException: cannot set pitches with provided object: C4
For setting a single one, use n.pitch instead.
Don’t use strings, or you will get a string back!
>>> n.pitches = ('C4', 'D4') >>> n.pitch 'C4' >>> n.pitch.diatonicNoteNum Traceback (most recent call last): AttributeError: 'str' object has no attribute 'diatonicNoteNum'
Read/write properties inherited from NotRest
:
Read/write properties inherited from GeneralNote
:
Read/write properties inherited from Music21Object
:
Note
methods
-
Note.
pitchChanged
()¶ Called by the underlying pitch if something changed there.
-
Note.
transpose
(value, *, inPlace=False)¶ Transpose the Note by the user-provided value. If the value is an integer, the transposition is treated in half steps.
If the value is a string, any Interval string specification can be provided.
>>> a = note.Note('g4') >>> b = a.transpose('m3') >>> b <music21.note.Note B-> >>> aInterval = interval.Interval(-6) >>> b = a.transpose(aInterval) >>> b <music21.note.Note C#>
>>> c = b.transpose(interval.GenericInterval(2)) >>> c <music21.note.Note D#>
>>> a.transpose(aInterval, inPlace=True) >>> a <music21.note.Note C#>
If the transposition value is an integer, take the KeySignature or Key context into account…
>>> s = stream.Stream() >>> s.append(key.Key('D')) >>> s.append(note.Note('F')) >>> s.append(key.Key('b-', 'minor')) >>> s.append(note.Note('F')) >>> s.show('text') {0.0} <music21.key.Key of D major> {0.0} <music21.note.Note F> {1.0} <music21.key.Key of b- minor> {1.0} <music21.note.Note F> >>> for n in s.notes: ... n.transpose(1, inPlace=True) >>> s.show('text') {0.0} <music21.key.Key of D major> {0.0} <music21.note.Note F#> {1.0} <music21.key.Key of b- minor> {1.0} <music21.note.Note G->
Methods inherited from NotRest
:
Methods inherited from GeneralNote
:
Methods inherited from Music21Object
:
Methods inherited from ProtoM21Object
:
Note
instance variables
-
Note.
isNote
¶ Boolean read-only value describing if this Note is a Note (True).
-
Note.
isRest
¶ Boolean read-only value describing if this Note is a Rest (False).
-
Note.
pitch
¶ A
Pitch
object containing all the information about the note’s pitch. Many .pitch properties and methods are also made Note properties also
Instance variables inherited from NotRest
:
Instance variables inherited from GeneralNote
:
Instance variables inherited from Music21Object
:
Rest¶
-
class
music21.note.
Rest
(*arguments, **keywords)¶ Rests are represented in music21 as GeneralNote objects that do not have a pitch object attached to them. By default they have length 1.0 (Quarter Rest)
Calling
notes
on a Stream does not get rests. However, the propertynotesAndRests
of Streams gets rests as well.>>> r = note.Rest() >>> r.isRest True >>> r.isNote False >>> r.duration.quarterLength = 2.0 >>> r.duration.type 'half'
All Rests have the name property ‘rest’:
>>> r.name 'rest'
Rest
bases
Rest
read-only properties
-
Rest.
fullName
¶ Return the most complete representation of this Rest, providing duration information.
>>> r = note.Rest(quarterLength=1.5) >>> r.fullName 'Dotted Quarter Rest'
>>> note.Rest(type='whole').fullName 'Whole Rest'
Read-only properties inherited from Music21Object
:
Read-only properties inherited from ProtoM21Object
:
Rest
read/write properties
Read/write properties inherited from GeneralNote
:
Read/write properties inherited from Music21Object
:
Rest
methods
Methods inherited from GeneralNote
:
Methods inherited from Music21Object
:
Methods inherited from ProtoM21Object
:
Rest
instance variables
-
Rest.
fullMeasure
¶ does this rest last a full measure (thus display as whole, center, etc.) Options are False, True, “always”, “auto” (default)
False means do not set as full measure, no matter what.
True keeps the set duration, but will always display as a full measure rest.
“always” means the duration will (EVENTUALLY, not yet!) update automatically to match the time signature context; and is True. Does not work yet – functions as True.
# TODO: get it to work.
“auto” is the default, where if the rest value happens to match the current time signature context, then display it as a whole note, centered, etc. otherwise will display normally.
See examples in
music21.musicxml.m21ToXml.MeasureExporter.restToXml()
-
Rest.
isNote
¶ Boolean read-only value describing if this Rest is a Note (False).
-
Rest.
isRest
¶ Boolean read-only value describing if this Rest is a Rest (True, obviously).
-
Rest.
name
¶ returns “rest” always. It is here so that you can get x.name on all .notesAndRests objects
-
Rest.
stepShift
¶ number of lines/spaces to shift the note upwards or downwards for display.
Instance variables inherited from GeneralNote
:
Instance variables inherited from Music21Object
:
SpacerRest¶
-
class
music21.note.
SpacerRest
(*arguments, **keywords)¶ This is exactly the same as a rest, but it is a SpacerRest. This object should only be used for making hidden space in a score in lilypond.
This may become deprecated at some point…
>>> sr = note.SpacerRest(type='whole') >>> sr <music21.note.SpacerRest rest duration=4.0>
SpacerRest
bases
SpacerRest
read-only properties
Read-only properties inherited from Rest
:
Read-only properties inherited from Music21Object
:
Read-only properties inherited from ProtoM21Object
:
SpacerRest
read/write properties
Read/write properties inherited from GeneralNote
:
Read/write properties inherited from Music21Object
:
SpacerRest
methods
Methods inherited from GeneralNote
:
Methods inherited from Music21Object
:
Methods inherited from ProtoM21Object
:
SpacerRest
instance variables
Instance variables inherited from Rest
:
Instance variables inherited from GeneralNote
:
Instance variables inherited from Music21Object
:
Unpitched¶
-
class
music21.note.
Unpitched
¶ A General class of unpitched objects which appear at different places on the staff. Examples: percussion notation.
The Unpitched object does not currently do anything and should not be used.
>>> unp = note.Unpitched()
Unpitched elements have displayStep and displayOctave which shows where they should be displayed, but they do not have pitch objects:
>>> unp.displayStep 'C' >>> unp.displayOctave 4 >>> unp.displayStep = 'G' >>> unp.pitch Traceback (most recent call last): AttributeError: 'Unpitched' object has no attribute 'pitch'
Unpitched
bases
Unpitched
read-only properties
Read-only properties inherited from Music21Object
:
Read-only properties inherited from ProtoM21Object
:
Unpitched
read/write properties
-
Unpitched.
storedInstrument
¶
Read/write properties inherited from NotRest
:
Read/write properties inherited from GeneralNote
:
Read/write properties inherited from Music21Object
:
Unpitched
methods
-
Unpitched.
displayPitch
() → music21.pitch.Pitch¶ returns a pitch object that is the same as the displayStep and displayOctave. it will never have an accidental.
>>> unp = note.Unpitched() >>> unp.displayStep = 'E' >>> unp.displayOctave = 4 >>> unp.displayPitch() <music21.pitch.Pitch E4>
Methods inherited from NotRest
:
Methods inherited from GeneralNote
:
Methods inherited from Music21Object
:
Methods inherited from ProtoM21Object
:
Unpitched
instance variables
Instance variables inherited from NotRest
:
Instance variables inherited from GeneralNote
:
Instance variables inherited from Music21Object
:
NotRest¶
-
class
music21.note.
NotRest
(*arguments, **keywords)¶ Parent class for Note-like objects that are not rests; that is to say they have a stem, can be tied, and volume is important. Basically, that’s a Note or Unpitched object for now.
NotRest
bases
NotRest
read-only properties
Read-only properties inherited from Music21Object
:
Read-only properties inherited from ProtoM21Object
:
NotRest
read/write properties
-
NotRest.
notehead
¶ Get or set the notehead type of this NotRest object. Valid notehead type names are found in note.noteheadTypeNames (see below):
>>> note.noteheadTypeNames ('arrow down', 'arrow up', 'back slashed', 'circle dot', 'circle-x', 'circled', 'cluster', 'cross', 'diamond', 'do', 'fa', 'inverted triangle', 'la', 'left triangle', 'mi', 'none', 'normal', 'other', 're', 'rectangle', 'slash', 'slashed', 'so', 'square', 'ti', 'triangle', 'x') >>> n = note.Note() >>> n.notehead = 'diamond' >>> n.notehead 'diamond'
>>> n.notehead = 'junk' Traceback (most recent call last): music21.note.NotRestException: not a valid notehead type name: 'junk'
-
NotRest.
noteheadFill
¶ Get or set the note head fill status of this NotRest. Valid note head fill values are True, False, or None (meaning default). “yes” and “no” are converted to True and False.
>>> n = note.Note() >>> n.noteheadFill = 'no' >>> n.noteheadFill False >>> n.noteheadFill = 'filled' >>> n.noteheadFill True
>>> n.noteheadFill = 'jelly' Traceback (most recent call last): music21.note.NotRestException: not a valid notehead fill value: jelly
-
NotRest.
noteheadParenthesis
¶ Get or set the note head parentheses for this Note/Unpitched/Chord object.
>>> n = note.Note() >>> n.noteheadParenthesis False >>> n.noteheadParenthesis = True >>> n.noteheadParenthesis True
‘yes’ or 1 equate to True; ‘no’ or 0 to False
>>> n.noteheadParenthesis = 'no' >>> n.noteheadParenthesis False
Anything else raises an exception:
>>> n.noteheadParenthesis = 'blah' Traceback (most recent call last): music21.note.NotRestException: notehead parentheses must be True or False, not 'blah'
-
NotRest.
stemDirection
¶ Get or set the stem direction of this NotRest object. Valid stem direction names are found in note.stemDirectionNames (see below).
>>> note.stemDirectionNames ('double', 'down', 'noStem', 'none', 'unspecified', 'up') >>> n = note.Note()
By default a Note’s stemDirection is ‘unspecified’ meaning that it is unknown:
>>> n.stemDirection 'unspecified'
>>> n.stemDirection = 'noStem' >>> n.stemDirection 'noStem'
The alias ‘none’ (the string) is the same as ‘noStem’
>>> n.stemDirection = 'none' >>> n.stemDirection 'noStem'
>>> n.stemDirection = 'junk' Traceback (most recent call last): music21.note.NotRestException: not a valid stem direction name: junk
Stem direction can be set explicitly to None to remove any prior stem information, same as ‘unspecified’:
>>> n.stemDirection = None >>> n.stemDirection 'unspecified'
-
NotRest.
volume
¶ Get and set the
Volume
object of this object. Volume objects are created on demand.>>> n1 = note.Note() >>> n1.volume.velocity = 120 >>> n2 = note.Note() >>> n2.volume = 80 # can directly set a velocity value >>> s = stream.Stream() >>> s.append([n1, n2]) >>> [n.volume.velocity for n in s.notes] [120, 80]
Read/write properties inherited from GeneralNote
:
Read/write properties inherited from Music21Object
:
NotRest
methods
-
NotRest.
hasVolumeInformation
() → bool¶ Returns bool whether volume was set – saving some time for advanced users (such as MusicXML exporters) that only want to look at the volume if it is already there.
>>> n = note.Note() >>> n.hasVolumeInformation() False >>> n.volume <music21.volume.Volume realized=0.71> >>> n.hasVolumeInformation() True
Methods inherited from GeneralNote
:
Methods inherited from Music21Object
:
Methods inherited from ProtoM21Object
:
NotRest
instance variables
Instance variables inherited from GeneralNote
:
Instance variables inherited from Music21Object
:
GeneralNote¶
-
class
music21.note.
GeneralNote
(*arguments, **keywords)¶ A GeneralNote object is the base class object for the
Note
,Rest
,Chord
, and related objects.Keywords can be passed to a GeneralNote which are then passed to the underlying
Duration
. These keywords might be listed like type=’16th’, dots=2 etc. to create a double-dotted sixteenth note.In almost every circumstance, you should create note.Note() or note.Rest() or note.Chord() objects directly, and not use this underlying structure.
>>> gn = note.GeneralNote(type='16th', dots=2) >>> gn.quarterLength 0.4375
GeneralNote
bases
GeneralNote
read-only properties
Read-only properties inherited from Music21Object
:
Read-only properties inherited from ProtoM21Object
:
GeneralNote
read/write properties
-
GeneralNote.
lyric
¶ The lyric property can be used to get and set a lyric for this Note, Chord, or Rest. This is a simplified version of the more general
addLyric()
method.>>> a = note.Note('A4') >>> a.lyrics [] >>> a.lyric = 'hel-' >>> a.lyric 'hel' >>> a.lyrics [<music21.note.Lyric number=1 syllabic=begin text='hel'>]
Eliminate Lyrics by setting a.lyric to None
>>> a.lyric = None >>> a.lyric >>> a.lyrics []
Set multiple lyrics with n separated text:
>>> a.lyric = '1. Hi\n2. Bye' >>> a.lyric '1. Hi\n2. Bye' >>> a.lyrics [<music21.note.Lyric number=1 syllabic=single text='1. Hi'>, <music21.note.Lyric number=2 syllabic=single text='2. Bye'>]
Read/write properties inherited from Music21Object
:
GeneralNote
methods
-
GeneralNote.
addLyric
(text, lyricNumber=None, *, applyRaw=False, lyricIdentifier=None) → None¶ Adds a lyric, or an additional lyric, to a Note, Chord, or Rest’s lyric list. If lyricNumber is not None, a specific line of lyric text can be set. The lyricIdentifier can also be set.
>>> n1 = note.Note() >>> n1.addLyric('hello') >>> n1.lyrics[0].text 'hello' >>> n1.lyrics[0].number 1
An added option gives the lyric number, not the list position
>>> n1.addLyric('bye', 3) >>> n1.lyrics[1].text 'bye' >>> n1.lyrics[1].number 3 >>> for lyr in n1.lyrics: ... print(lyr.text) hello bye
Replace an existing lyric by specifying the same number:
>>> n1.addLyric('ciao', 3) >>> n1.lyrics[1].text 'ciao' >>> n1.lyrics[1].number 3
Giving a lyric with a hyphen at either end will set whether it is part of a multisyllable word:
>>> n1.addLyric('good-') >>> n1.lyrics[2].text 'good' >>> n1.lyrics[2].syllabic 'begin'
This feature can be overridden by specifying the keyword only argument “applyRaw=True”:
>>> n1.addLyric('-5', applyRaw=True) >>> n1.lyrics[3].text '-5' >>> n1.lyrics[3].syllabic 'single'
-
GeneralNote.
augmentOrDiminish
(scalar, *, inPlace=False)¶ Given a scalar greater than zero, return a Note with a scaled Duration. If inPlace is True, this is done in-place and the method returns None. If inPlace is False [default], this returns a modified deepcopy.
Changed – inPlace is now False as of version 5.
>>> n = note.Note('g#') >>> n.quarterLength = 3 >>> n.augmentOrDiminish(2, inPlace=True) >>> n.quarterLength 6.0
>>> c = chord.Chord(['g#', 'a#', 'd']) >>> c.quarterLength = 2 >>> c.augmentOrDiminish(0.25, inPlace=True) >>> c.quarterLength 0.5
>>> n = note.Note('g#') >>> n.augmentOrDiminish(-1) Traceback (most recent call last): music21.note.NoteException: scalar must be greater than zero
>>> n = note.Note() >>> n.quarterLength = 3 >>> n2 = n.augmentOrDiminish(1/3, inPlace=False) >>> n2.quarterLength 1.0 >>> n.quarterLength 3.0
-
GeneralNote.
getGrace
(*, appoggiatura=False, inPlace=False)¶ Return a grace version of this GeneralNote
>>> n = note.Note('G4', quarterLength=2) >>> n.duration.quarterLength 2.0 >>> n.duration.isGrace False >>> n.duration <music21.duration.Duration 2.0> >>> n.duration.type 'half' >>> n.duration.components (DurationTuple(type='half', dots=0, quarterLength=2.0),)
>>> ng = n.getGrace() >>> ng.duration.quarterLength 0.0 >>> ng.duration.isGrace True >>> ng.duration <music21.duration.GraceDuration unlinked type:zero quarterLength:0.0> >>> ng.duration.type 'zero' >>> ng.duration.components (DurationTuple(type='half', dots=0, quarterLength=0.0),)
Appoggiaturas are still a work in progress… Changed in v.6 – corrected spelling of appoggiatura keyword.
>>> ng2 = n.getGrace(appoggiatura=True) >>> ng2.duration <music21.duration.AppoggiaturaDuration unlinked type:zero quarterLength:0.0> >>> ng2.duration.slash False
Set inPlace to True to change the duration element on the Note. This can have negative consequences if the Note is in a stream.
>>> r = note.Rest(quarterLength=0.5) >>> r.getGrace(inPlace=True) >>> r.duration <music21.duration.GraceDuration unlinked type:zero quarterLength:0.0>
-
GeneralNote.
insertLyric
(text, index=0, *, applyRaw=False, identifier=None)¶ Inserts a lyric into the Note, Chord, or Rest’s lyric list in front of the index specified (0 by default), using index + 1 as the inserted lyric’s line number. shifts line numbers of all following lyrics in list
>>> n1 = note.Note() >>> n1.addLyric('second') >>> n1.lyrics [<music21.note.Lyric number=1 syllabic=single text='second'>] >>> n1.insertLyric('first', 0) >>> n1.lyrics [<music21.note.Lyric number=1 syllabic=single text='first'>, <music21.note.Lyric number=2 syllabic=single text='second'>]
Methods inherited from Music21Object
:
Methods inherited from ProtoM21Object
:
GeneralNote
instance variables
-
GeneralNote.
articulations
¶ a list of articulations such as
Staccato
, etc.) that are stored on this Note.
-
GeneralNote.
expressions
¶ a list of expressions (such as
Fermata
, etc.) that are stored on this Note.
-
GeneralNote.
isChord
¶ Boolean read-only value describing if this object is a Chord.
-
GeneralNote.
tie
¶ either None or a
Tie
object.
Instance variables inherited from Music21Object
:
Lyric¶
-
class
music21.note.
Lyric
(text=None, number=1, **kwargs)¶ An object representing a single Lyric as part of a note’s .lyrics property.
The note.lyric property is a simple way of specifying a single lyric, but Lyric objects are needed for working with multiple lyrics.
>>> l = note.Lyric(text='hello') >>> l <music21.note.Lyric number=1 syllabic=single text='hello'>
Music21 processes leading and following hyphens intelligently…
>>> l2 = note.Lyric(text='hel-') >>> l2 <music21.note.Lyric number=1 syllabic=begin text='hel'>
…unless applyRaw is set to True
>>> l3 = note.Lyric(number=3, text='hel-', applyRaw=True) >>> l3 <music21.note.Lyric number=3 syllabic=single text='hel-'>
Lyrics have four properties: text, number, identifier, syllabic (single, begin, middle, end)
>>> l3.text 'hel-'
>>> l3.number 3
>>> l3.syllabic 'single'
Note musicXML only supports one ‘identifier’ attribute which is called ‘number’ but which can be a number or a descriptive identifier like ‘part2verse1.’ To preserve lyric ordering, music21 stores a number and a descriptive identifier separately. The descriptive identifier is by default the same as the number, but in cases where a string identifier is present, it will be different.
Both music21 and musicxml support multiple lyric objects in the same stanza, for instance, if there is an elision on a note then multiple lyrics with different syllabics can appear on a single note.
Lyric
bases
Lyric
read-only properties
Read-only properties inherited from ProtoM21Object
:
Read-only properties inherited from StyleMixin
:
Lyric
read/write properties
-
Lyric.
identifier
¶ By default, this is the same as self.number. However, if there is a descriptive identifier like ‘part2verse1’, it is stored here and will be different from self.number. When converting to musicXML, this property will be stored in the lyric ‘number’ attribute which can store a number or a descriptive identifier but not both.
>>> l = note.Lyric() >>> l.number = 12 >>> l.identifier 12
>>> l.identifier = 'Rainbow' >>> l.identifier 'Rainbow'
-
Lyric.
number
¶ This stores the number of the lyric (which determines the order lyrics appear in the score if there are multiple lyrics). Unlike the musicXML lyric number attribute, this value must always be a number; lyric order is always stored in this form. Descriptive identifiers like ‘part2verse1’ which can be found in the musicXML lyric number attribute should be stored in self.identifier.
>>> l = note.Lyric('Hi') >>> l.number = 5 >>> l.number 5 >>> l.number = None Traceback (most recent call last): music21.note.LyricException: Number best be number
-
Lyric.
rawText
¶ returns the text of the syllable with ‘-‘ etc.
>>> l = note.Lyric('hel-') >>> l.text 'hel' >>> l.rawText 'hel-'
>>> l = note.Lyric('-lo') >>> l.rawText '-lo'
>>> l = note.Lyric('-ti-') >>> l.rawText '-ti-'
>>> l = note.Lyric('bye') >>> l.rawText 'bye'
Read/write properties inherited from StyleMixin
:
Lyric
methods
-
Lyric.
setTextAndSyllabic
(rawText: str, applyRaw: bool = False) → None¶ Given a setting for rawText and applyRaw, sets the syllabic type for a lyric based on the rawText:
>>> l = note.Lyric() >>> l.setTextAndSyllabic('hel-') >>> l.text 'hel' >>> l.syllabic 'begin'
Methods inherited from ProtoM21Object
: