MetronomeMark

digraph InheritanceGraph { graph [bgcolor=transparent, color=lightsteelblue2, fontname=Arial, fontsize=10, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, splines=spline, style="dashed, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=10, height=0, penwidth=2, shape=box, style="filled, rounded", width=0]; edge [color=lightslategrey, penwidth=1]; subgraph "cluster_abjad.indicators" { graph [label="abjad.indicators"]; node [color=1]; "abjad.indicators.MetronomeMark.MetronomeMark" [URL="../api/abjad/indicators/MetronomeMark.html#abjad.indicators.MetronomeMark.MetronomeMark", color=black, fontcolor=white, label="Metronome\nMark", target=_top]; } subgraph "cluster_abjad.system" { graph [label="abjad.system"]; node [color=2]; "abjad.system.AbjadObject.AbjadObject" [URL="../api/abjad/indicators/../system/AbjadObject.html#abjad.system.AbjadObject.AbjadObject", label="Abjad\nObject", target=_top]; "abjad.system.AbjadValueObject.AbjadValueObject" [URL="../api/abjad/indicators/../system/AbjadValueObject.html#abjad.system.AbjadValueObject.AbjadValueObject", label="Abjad\nValue\nObject", target=_top]; "abjad.system.AbjadObject.AbjadObject" -> "abjad.system.AbjadValueObject.AbjadValueObject"; } subgraph cluster_builtins { graph [label=builtins]; node [color=3]; "builtins.object" [URL="https://docs.python.org/3.6/library/functions.html#object", label=object, target=_top]; } "abjad.system.AbjadValueObject.AbjadValueObject" -> "abjad.indicators.MetronomeMark.MetronomeMark"; "builtins.object" -> "abjad.system.AbjadObject.AbjadObject"; }

class abjad.indicators.MetronomeMark.MetronomeMark(reference_duration=None, units_per_minute=None, textual_indication=None, *, custom_markup=None, hide=None)

MetronomeMark.

Initializes integer-valued metronome mark:

>>> score = abjad.Score([])
>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> score.append(staff)
>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> abjad.attach(mark, staff[0])
>>> abjad.show(score) 

Initializes rational-valued metronome mark:

>>> score = abjad.Score([])
>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> score.append(staff)
>>> mark = abjad.MetronomeMark((1, 4), abjad.Fraction(181, 2))
>>> abjad.attach(mark, staff[0])
>>> abjad.show(score) 

Initializes from text, duration and range:

>>> score = abjad.Score([])
>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> score.append(staff)
>>> mark = abjad.MetronomeMark((1, 4), (120, 133), 'Quick')
>>> abjad.attach(mark, staff[0])
>>> abjad.show(score) 

Use rational-value units-per-minute together with custom markup for float-valued metornome marks:

>>> score = abjad.Score([])
>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> score.append(staff)
>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(
...     abjad.Duration(1, 4),
...     90.1,
...     )
>>> mark = abjad.MetronomeMark(
...     (1, 4),
...     Fraction(900, 10),
...     custom_markup=markup,
...     )
>>> abjad.attach(mark, staff[0])
>>> abjad.show(score) 

(Abjad models all timekeeping with rationals.)


Attributes Summary

__add__ Adds metronome mark to argument.
__div__ Divides metronome mark by argument.
__eq__ Is true when metronome mark equals argument.
__format__ Formats metronome mark.
__ge__ Return a >= b.
__gt__ Return a > b.
__hash__ Hashes metronome mark.
__le__ Return a <= b.
__lt__ Is true when argument is a metronome mark with quarters per minute greater than that of this metronome mark.
__mul__ Multiplies metronome mark by multiplier.
__radd__ Adds argument to metronome mark.
__rmul__ Multiplies multiplier by metronome mark.
__str__ Gets string representation of metronome mark.
__sub__ Subtracts argument from metronome mark.
__truediv__ Divides metronome mark by argument.
context Gets (historically conventional) context.
custom_markup Gets custom markup of metronome mark.
duration_to_milliseconds Gets millisecond value of duration under a given metronome mark.
hide Is true when metronome mark should not appear in output (but should still determine effective metronome mark).
is_imprecise Is true if metronome mark is entirely textual or if metronome mark’s units_per_minute is a range.
list_related_tempos Lists related tempos.
make_tempo_equation_markup Makes tempo equation markup.
parameter Is 'METRONOME_MARK'.
quarters_per_minute Gets metronome mark quarters per minute.
reference_duration Gets reference duration of metronome mark.
rewrite_duration Rewrites duration under metronome_mark.
textual_indication Gets optional textual indication of metronome mark.
tweaks Are not implemented on metronome mark.
units_per_minute Gets units per minute of metronome mark.

Special methods

__add__(argument)

Adds metronome mark to argument.

Adds one metronome mark to another:

>>> mark_1 = abjad.MetronomeMark((1, 4), 60)
>>> mark_2 = abjad.MetronomeMark((1, 4), 90)
>>> mark_1 + mark_2
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=150)
>>> mark_2 + mark_1
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=150)

Raises imprecise metronome mark error with textual indication:

>>> mark_1 = abjad.MetronomeMark(textual_indication='Langsam')
>>> mark_2 = abjad.MetronomeMark((1, 4), 90)
>>> mark_1 + mark_2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 359, in __add__
    raise exceptions.ImpreciseMetronomeMarkError
abjad.exceptions.ImpreciseMetronomeMarkError

Raises imprecise metronome mark error with range:

>>> mark_1 = abjad.MetronomeMark((1, 8), (90, 92))
>>> mark_2 = abjad.MetronomeMark((1, 4), 90)
>>> mark_1 + mark_2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 359, in __add__
    raise exceptions.ImpreciseMetronomeMarkError
abjad.exceptions.ImpreciseMetronomeMarkError

Raises type error when argument is not a metronome mark:

>>> abjad.MetronomeMark((1, 4), 60) + 90
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 357, in __add__
    raise TypeError(argument)
TypeError: 90
Return type:Optional[MetronomeMark]
(AbjadValueObject).__copy__(*arguments)

Copies Abjad value object.

Returns new Abjad value object.

__div__(argument)

Divides metronome mark by argument.

Divides metronome mark by number:

>>> abjad.MetronomeMark((1, 4), 60) / 2
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=30)

Divides metronome mark by other metronome mark:

>>> abjad.MetronomeMark((1, 4), 60) / abjad.MetronomeMark((1, 4), 40)
Multiplier(3, 2)
Return type:MetronomeMark
__eq__(argument)

Is true when metronome mark equals argument.

>>> mark_1 = abjad.MetronomeMark((3, 32), 52)
>>> mark_2 = abjad.MetronomeMark((3, 32), 52)
>>> mark_1 == mark_2
True
>>> mark_2 == mark_1
True
>>> mark_1 = abjad.MetronomeMark((3, 32), 52)
>>> mark_2 = abjad.MetronomeMark((6, 32), 104)
>>> mark_1 == mark_2
False
>>> mark_2 == mark_1
False
>>> mark_1 = abjad.MetronomeMark((3, 32), 52, 'Langsam')
>>> mark_2 = abjad.MetronomeMark((3, 32), 52, 'Langsam')
>>> mark_3 = abjad.MetronomeMark((3, 32), 52, 'Slow')
>>> mark_1 == mark_2
True
>>> mark_1 == mark_3
False
Return type:bool
__format__(format_specification='')

Formats metronome mark.

Without custom markup:

>>> mark = abjad.MetronomeMark((1, 4), 84, 'Allegro')
>>> print(format(mark))
abjad.MetronomeMark(
    reference_duration=abjad.Duration(1, 4),
    units_per_minute=84,
    textual_indication='Allegro',
    )

With custom markup:

>>> markup = abjad.Markup(r'\italic { Allegro }')
>>> mark = abjad.MetronomeMark((1, 4), 84, custom_markup=markup)
>>> print(format(mark))
abjad.MetronomeMark(
    reference_duration=abjad.Duration(1, 4),
    units_per_minute=84,
    custom_markup=abjad.Markup(
        contents=[
            abjad.MarkupCommand(
                'italic',
                ['Allegro']
                ),
            ],
        ),
    )
Return type:str
__ge__(other, NotImplemented=NotImplemented)

Return a >= b. Computed by @total_ordering from (not a < b).

__gt__(other, NotImplemented=NotImplemented)

Return a > b. Computed by @total_ordering from (not a < b) and (a != b).

__hash__()

Hashes metronome mark.

Redefined in tandem with __eq__.

Return type:int
__le__(other, NotImplemented=NotImplemented)

Return a <= b. Computed by @total_ordering from (a < b) or (a == b).

__lt__(argument)

Is true when argument is a metronome mark with quarters per minute greater than that of this metronome mark.

Return type:bool
__mul__(multiplier)

Multiplies metronome mark by multiplier.

Doubles metronome mark:

>>> mark = abjad.MetronomeMark((1, 4), 84)
>>> 2 * mark
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=168)

Triples metronome mark:

>>> mark = abjad.MetronomeMark((1, 4), 84)
>>> 3 * mark
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=252)
Return type:Optional[MetronomeMark]
__radd__(argument)

Adds argument to metronome mark.

Adds one metronome mark to another:

>>> mark_1 = abjad.MetronomeMark((1, 4), 60)
>>> mark_2 = abjad.MetronomeMark((1, 4), 90)
>>> mark_1 + mark_2
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=150)
>>> mark_2 + mark_1
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=150)

Raises imprecise metronome mark error with textual indication:

>>> mark_1 = abjad.MetronomeMark(textual_indication='Langsam')
>>> mark_2 = abjad.MetronomeMark((1, 4), 90)
>>> mark_1 + mark_2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 359, in __add__
    raise exceptions.ImpreciseMetronomeMarkError
abjad.exceptions.ImpreciseMetronomeMarkError

Raises imprecise metronome mark error with range:

>>> mark_1 = abjad.MetronomeMark((1, 8), (90, 92))
>>> mark_2 = abjad.MetronomeMark((1, 4), 90)
>>> mark_1 + mark_2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 359, in __add__
    raise exceptions.ImpreciseMetronomeMarkError
abjad.exceptions.ImpreciseMetronomeMarkError

Raises type error when argument is not a metronome mark:

>>> 90 + abjad.MetronomeMark((1, 4), 60)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 619, in __radd__
    raise TypeError(argument)
TypeError: 90
Return type:Optional[MetronomeMark]
(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.

__rmul__(multiplier)

Multiplies multiplier by metronome mark.

Return type:Optional[MetronomeMark]
__str__()

Gets string representation of metronome mark.

Integer-valued metronome mark:

>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> str(mark)
'4=90'

Rational-valued metronome mark:

>>> mark = abjad.MetronomeMark((1, 4), (90, 96))
>>> str(mark)
'4=90-96'
Return type:str
__sub__(argument)

Subtracts argument from metronome mark.

Same reference reference durations:

>>> mark_1 = abjad.MetronomeMark((1, 4), 90)
>>> mark_2 = abjad.MetronomeMark((1, 4), 60)
>>> mark_1 - mark_2
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=30)

Different reference durations:

>>> mark_1 = abjad.MetronomeMark((1, 4), 90)
>>> mark_2 = abjad.MetronomeMark((1, 2), 90)
>>> mark_1 - mark_2
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=45)

Raises imprecise metronome mark error with textual indication:

>>> mark_1 = abjad.MetronomeMark(textual_indication='Langsam')
>>> mark_2 = abjad.MetronomeMark((1, 2), 90)
>>> mark_1 - mark_2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/josiah/Source/github.com/Abjad/abjad/abjad/indicators/MetronomeMark.py", line 740, in __sub__
    raise exceptions.ImpreciseMetronomeMarkError
abjad.exceptions.ImpreciseMetronomeMarkError
Return type:MetronomeMark
__truediv__(argument)

Divides metronome mark by argument.

Operator required by Python 3.

Divides metronome mark by number:

>>> abjad.MetronomeMark((1, 4), 60).__truediv__(2)
MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=30)

Divides metronome mark by other metronome mark:

>>> abjad.MetronomeMark((1, 4), 60).__truediv__(
...     abjad.MetronomeMark((1, 4), 40)
...     )
Multiplier(3, 2)
Return type:MetronomeMark

Methods

duration_to_milliseconds(duration)

Gets millisecond value of duration under a given metronome mark.

One quarter lasts 1000 msec at quarter equals 60:

>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> mark.duration_to_milliseconds((1, 4))
Duration(1000, 1)

Dotted sixteenth lasts 1500 msec at quarter equals 60:

>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> mark.duration_to_milliseconds((3, 8))
Duration(1500, 1)
Return type:Duration

Lists related tempos.

Rewrites tempo 4=58 by ratios n:d such that 1 <= n <= 8 and 1 <= d <= 8.

>>> mark = abjad.MetronomeMark((1, 4), 58)
>>> pairs = mark.list_related_tempos(
...     maximum_numerator=8,
...     maximum_denominator=8,
...     )
>>> for tempo, ratio in pairs:
...     string = f'{tempo!s}\t{ratio!s}'
...     print(string)
... 
4=29	1:2
4=33+1/7	4:7
4=34+4/5	3:5
4=36+1/4	5:8
4=38+2/3	2:3
4=41+3/7	5:7
4=43+1/2	3:4
4=46+2/5	4:5
4=48+1/3	5:6
4=49+5/7	6:7
4=50+3/4	7:8
4=58	1:1
4=66+2/7	8:7
4=67+2/3	7:6
4=69+3/5	6:5
4=72+1/2	5:4
4=77+1/3	4:3
4=81+1/5	7:5
4=87	3:2
4=92+4/5	8:5
4=96+2/3	5:3
4=101+1/2	7:4
4=116	2:1

Integer-valued tempos only:

>>> mark = abjad.MetronomeMark((1, 4), 58)
>>> pairs = mark.list_related_tempos(
...     maximum_numerator=16,
...     maximum_denominator=16,
...     integer_tempos_only=True,
...     )
>>> for tempo, ratio in pairs:
...     string = f'{tempo!s}\t{ratio!s}'
...     print(string)
... 
4=29	1:2
4=58	1:1
4=87	3:2
4=116	2:1

Constrains ratios such that 1:2 <= n:d <= 2:1.

Returns list of tempo / ratio pairs.

rewrite_duration(duration, metronome_mark)

Rewrites duration under metronome_mark.

Consider the two metronome marks below.

>>> tempo = abjad.MetronomeMark((1, 4), 60)
>>> metronome_mark = abjad.MetronomeMark((1, 4), 90)

tempo specifies quarter equal to 60.

metronome_mark indication specifies quarter equal to 90.

metronome_mark is 3/2 times as fast as tempo:

>>> metronome_mark / tempo
Multiplier(3, 2)

Note that a triplet eighth note under tempo equals a regular eighth note under metronome_mark:

>>> tempo.rewrite_duration((1, 12), metronome_mark)
Duration(1, 8)

And note that a regular eighth note under tempo equals a dotted sixteenth under metronome_mark:

>>> tempo.rewrite_duration((1, 8), metronome_mark)
Duration(3, 16)

Given duration governed by this tempo returns new duration governed by metronome_mark.

Ensures that duration and new duration consume the same amount of time in seconds.

Returns duration.


Class & static methods

static make_tempo_equation_markup(reference_duration, units_per_minute)

Makes tempo equation markup.

Integer-valued metronome mark:

>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(
...     (1, 4),
...     90,
...     )
>>> abjad.show(markup) 

Float-valued metronome mark:

>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(
...     (1, 4),
...     90.1,
...     )
>>> abjad.show(markup) 

Rational-valued metronome mark:

>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(
...     abjad.Duration(1, 4),
...     abjad.Fraction(181, 2),
...     )
>>> abjad.show(markup) 

Reference duration expressed with ties:

>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(
...     (5, 16),
...     90,
...     )
>>> abjad.show(markup) 

Reference duration expressed as a tuplet:

>>> markup = abjad.MetronomeMark.make_tempo_equation_markup((1, 6), 90)
>>> abjad.show(markup) 

Reference duration passed in as explicit rhythm:

>>> maker = abjad.NoteMaker()
>>> durations = [(1, 16), (3, 16), (1, 16)]
>>> selection = maker([0], durations)
>>> abjad.attach(abjad.Tie(), selection)
>>> abjad.attach(abjad.Beam(), selection)
>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(selection, 90)
>>> abjad.show(markup) 

Pass rhythms like this as Abjad selections.

Returns markup.


Read-only properties

context

Gets (historically conventional) context.

Fifty-two eighth notes per minute:

>>> mark = abjad.MetronomeMark((1, 8), 52)
>>> mark.context
'Score'

Ninety quarter notes per minute:

>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> mark.context
'Score'

Override with abjad.attach(..., context='...').

Return type:str
custom_markup

Gets custom markup of metronome mark.

With custom markup:

>>> markup = abjad.MetronomeMark.make_tempo_equation_markup(
...     abjad.Duration(1, 4),
...     67.5,
...     )
>>> markup = markup.with_color('red')
>>> mark = abjad.MetronomeMark(
...     reference_duration=(1, 4),
...     units_per_minute=Fraction(135, 2),
...     custom_markup=markup,
...     )
>>> staff = abjad.Staff("c'4 d'4 e'4 f'4")
>>> score = abjad.Score([staff])
>>> abjad.attach(mark, staff[0])
>>> abjad.show(score) 
Return type:Optional[Markup]
hide

Is true when metronome mark should not appear in output (but should still determine effective metronome mark).

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> metronome_mark_1 = abjad.MetronomeMark((1, 4), 72)
>>> abjad.attach(metronome_mark_1, staff[0])
>>> metronome_mark_2 = abjad.MetronomeMark(
...     textual_indication='Allegro',
...     hide=True,
...     )
>>> abjad.attach(metronome_mark_2, staff[2])
>>> score = abjad.Score([staff])
>>> abjad.show(score) 
>>> abjad.f(score)
\new Score
<<
    \new Staff
    {
        \tempo 4=72
        c'4
        d'4
        e'4
        f'4
    }
>>
>>> for leaf in abjad.iterate(staff).leaves():
...     prototype = abjad.MetronomeMark
...     leaf, abjad.inspect(leaf).effective(prototype)
... 
(Note("c'4"), MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=72))
(Note("d'4"), MetronomeMark(reference_duration=Duration(1, 4), units_per_minute=72))
(Note("e'4"), MetronomeMark(textual_indication='Allegro', hide=True))
(Note("f'4"), MetronomeMark(textual_indication='Allegro', hide=True))
Return type:Optional[bool]
is_imprecise

Is true if metronome mark is entirely textual or if metronome mark’s units_per_minute is a range.

Imprecise metronome marks:

>>> abjad.MetronomeMark((1, 4), 60).is_imprecise
False
>>> abjad.MetronomeMark(4, 60, 'Langsam').is_imprecise
False
>>> abjad.MetronomeMark(textual_indication='Langsam').is_imprecise
True
>>> abjad.MetronomeMark(4, (35, 50), 'Langsam').is_imprecise
True
>>> abjad.MetronomeMark((1, 4), (35, 50)).is_imprecise
True

Precise metronome marks:

>>> abjad.MetronomeMark((1, 4), 60).is_imprecise
False
Return type:bool
parameter

Is 'METRONOME_MARK'.

>>> abjad.MetronomeMark((1, 8), 52).parameter
'METRONOME_MARK'
Return type:str
quarters_per_minute

Gets metronome mark quarters per minute.

Fifty-two eighth notes per minute:

>>> mark = abjad.MetronomeMark((1, 8), 52)
>>> mark.quarters_per_minute
Fraction(104, 1)

Ninety quarter notes per minute:

>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> mark.quarters_per_minute
Fraction(90, 1)

140 quarters per minute:

>>> mark = abjad.MetronomeMark((3, 32), Fraction(105, 2))
>>> mark.quarters_per_minute
Fraction(140, 1)

Returns tuple when metronome mark units_per_minute is a range.

Returns none when metronome mark is imprecise.

Returns fraction otherwise.

Return type:Union[tuple, None, Fraction]
reference_duration

Gets reference duration of metronome mark.

Fifty-two eighth notes per minute:

>>> mark = abjad.MetronomeMark((1, 8), 52)
>>> mark.reference_duration
Duration(1, 8)

Ninety quarter notes per minute:

>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> mark.reference_duration
Duration(1, 4)
Return type:Optional[Duration]
textual_indication

Gets optional textual indication of metronome mark.

Fifty-two eighth notes per minute:

>>> mark = abjad.MetronomeMark((1, 8), 52)
>>> mark.textual_indication is None
True

Ninety quarter notes per minute:

>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> mark.textual_indication is None
True
Return type:Optional[str]
tweaks

Are not implemented on metronome mark.

The LilyPond \tempo command refuses tweaks.

Override the LilyPond MetronomeMark grob instead.

Return type:None
units_per_minute

Gets units per minute of metronome mark.

Integer-valued metronome mark:

>>> mark = abjad.MetronomeMark((1, 4), 90)
>>> mark.units_per_minute
90

Rational-valued metronome mark:

>>> mark = abjad.MetronomeMark((1, 4), abjad.Fraction(181, 2))
>>> mark.units_per_minute
Fraction(181, 2)
Return type:Union[int, Fraction, None]