Skip to content

duration

Tempo

A musical tempo.

Parameters:

Name Type Description Default
bpm int

Beats per minute

 required
beat Duration

Reference beat duration

 Duration(4)
Source code in staff/duration.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
@dataclass(frozen=True)
class Tempo:
    """A musical tempo.

    Args:
        bpm: Beats per minute
        beat: Reference beat duration
    """

    bpm: int
    beat: Duration = Duration(4)

    def __post_init__(self):
        if not isinstance(self.bpm, int):
            raise TypeError("bpm must be expressed as an 'int'")

        if self.bpm < MIN_TEMPO_BPM:
            raise ValueError(f"bpm must be at least {MIN_TEMPO_BPM}")

        if self.bpm > MAX_TEMPO_BPM:
            raise ValueError(f"bpm must be at most {MAX_TEMPO_BPM}")

        if not isinstance(self.beat, Duration):
            raise TypeError("beat must be an instance of 'Duration'")

    @property
    def beat_milliseconds(self) -> float:
        """Get the length of each beat in milliseconds.

        Returns:
            Reference beat duration in milliseconds
        """
        return 60 / self.bpm * 1000

beat_milliseconds: float property

Get the length of each beat in milliseconds.

Returns:

Type Description
float

Reference beat duration in milliseconds

Duration

Musical duration.

Parameters:

Name Type Description Default
denominator int

The 4 in 1/4 for example

 required
dots int

The modifying dots

 0
is_rest bool

Is or isn't a silent duration

 False

Implements total_ordering against Duration.

Implements the following operations:

- `__add__` against `Duration`
- `__radd__` against `Duration`
- `__sub__` against `Duration`
- `__mul__` against `int` and `float`
- `__rmul__` against `int` and `float`
- `__truediv__` against `int` and `float`

Implements total ordering.

Examples:

Given a Tempo, a Duration length in milliseconds is:

>>> Duration(8, dots=1).milliseconds(Tempo(120))
375.0

>>> Duration(8, dots=1).milliseconds(Tempo(60))
750.0

Duration arithmetic is simple:

>>> Duration(4) + Duration(8)
Duration(denominator=4, dots=1, is_rest=False)

>>> sum((Duration(4), Duration(8), Duration(8)))
Duration(denominator=2, dots=0, is_rest=False)

>>> Duration(4) - Duration(8)
Duration(denominator=8, dots=0, is_rest=False)

>>> Duration(4) * 2
Duration(denominator=2, dots=0, is_rest=False)

>>> Duration(2) / 2
Duration(denominator=4, dots=0, is_rest=False)

Notice that adding or substracting two rests returns a rest:

>>> Duration(4, is_rest=True) + Duration(8, is_rest=True)
Duration(denominator=4, dots=1, is_rest=True)

>>> Duration(4, is_rest=True) - Duration(8, is_rest=True)
Duration(denominator=8, dots=0, is_rest=True)

but that if one of the two Duration instances is not a rest:

>>> Duration(4, is_rest=True) + Duration(8, is_rest=False)
Duration(denominator=4, dots=1, is_rest=False)

>>> Duration(4, is_rest=True) - Duration(8, is_rest=False)
Duration(denominator=8, dots=0, is_rest=False)

The same goes for the other operations:

>>> Duration(4, is_rest=True) * 2
Duration(denominator=2, dots=0, is_rest=True)

>>> Duration(2, is_rest=True) / 2
Duration(denominator=4, dots=0, is_rest=True)

Duration instances are comparable:

>>> Duration(2) > Duration(4)
True
Source code in staff/duration.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
@total_ordering
@dataclass(frozen=True)
class Duration:
    """Musical duration.

    Args:
        denominator: The 4 in 1/4 for example
        dots: The modifying dots
        is_rest: Is or isn't a silent duration

    Implements `total_ordering` against `Duration`.

    Implements the following operations:

        - `__add__` against `Duration`
        - `__radd__` against `Duration`
        - `__sub__` against `Duration`
        - `__mul__` against `int` and `float`
        - `__rmul__` against `int` and `float`
        - `__truediv__` against `int` and `float`

    Implements total ordering.

    Examples:
        Given a `Tempo`, a `Duration` length in milliseconds is:

        >>> Duration(8, dots=1).milliseconds(Tempo(120))
        375.0

        >>> Duration(8, dots=1).milliseconds(Tempo(60))
        750.0

        `Duration` arithmetic is simple:

        >>> Duration(4) + Duration(8)
        Duration(denominator=4, dots=1, is_rest=False)

        >>> sum((Duration(4), Duration(8), Duration(8)))
        Duration(denominator=2, dots=0, is_rest=False)

        >>> Duration(4) - Duration(8)
        Duration(denominator=8, dots=0, is_rest=False)

        >>> Duration(4) * 2
        Duration(denominator=2, dots=0, is_rest=False)

        >>> Duration(2) / 2
        Duration(denominator=4, dots=0, is_rest=False)

        Notice that adding or substracting two rests returns a rest:

        >>> Duration(4, is_rest=True) + Duration(8, is_rest=True)
        Duration(denominator=4, dots=1, is_rest=True)

        >>> Duration(4, is_rest=True) - Duration(8, is_rest=True)
        Duration(denominator=8, dots=0, is_rest=True)

        but that if one of the two `Duration` instances is not a rest:

        >>> Duration(4, is_rest=True) + Duration(8, is_rest=False)
        Duration(denominator=4, dots=1, is_rest=False)

        >>> Duration(4, is_rest=True) - Duration(8, is_rest=False)
        Duration(denominator=8, dots=0, is_rest=False)

        The same goes for the other operations:

        >>> Duration(4, is_rest=True) * 2
        Duration(denominator=2, dots=0, is_rest=True)

        >>> Duration(2, is_rest=True) / 2
        Duration(denominator=4, dots=0, is_rest=True)

        `Duration` instances are comparable:

        >>> Duration(2) > Duration(4)
        True
    """

    denominator: int
    dots: int = 0
    is_rest: bool = False

    def __post_init__(self):
        if not isinstance(self.denominator, int):
            raise TypeError("denominator must be expressed as an 'int'")

        if self.denominator > MAX_DURATION_DENOMINATOR:
            raise ValueError(f"max denominator is {MAX_DURATION_DENOMINATOR}")

        if self.denominator <= 0:
            raise ValueError("denominator must be greater than 0")

        if not isinstance(self.dots, int):
            raise TypeError("dots must be expressed as an 'int'")

        if self.dots > MAX_DURATION_DOTS:
            raise ValueError(f"max dots is {MAX_DURATION_DOTS}")

        if not is_power_of_two(self.denominator):
            raise ValueError("denominator must be a power of two")

    @property
    def decimal(self) -> float:
        """Get the duration as a decimal value.

        Returns:
            The duration as a decimal
        """
        dec = 1 / self.denominator
        for _dot in range(self.dots):
            dec *= 1.5
        return dec

    @property
    def fraction(self) -> Fraction:
        """Get the duration as a Fraction.

        Returns:
            The duration as a fraction
        """
        return Fraction(self.decimal)

    def milliseconds(self, tempo: Tempo) -> float:
        """Get the duration in milliseconds, given a tempo.

        Args:
            tempo: The tempo used to calculate the duration.

        Returns:
            The duration in milliseconds
        """
        if not isinstance(tempo, Tempo):
            raise TypeError("tempo must be an instance of 'Tempo'")
        return (self.decimal / tempo.beat.decimal) * tempo.beat_milliseconds

    def __gt__(self, other: Duration) -> bool:
        if not isinstance(other, Duration):
            raise TypeError(f"cannot compare Duration with type '{type(other)}'")
        return self.decimal > other.decimal

    def __add__(self, other: Duration) -> Duration:
        if not isinstance(other, Duration):
            raise TypeError(
                f"unsupported operand type(s) for +: 'Duration' and '{type(other)}'"
            )
        try:
            frac = self.fraction + other.fraction
            dots = 0
            while frac.numerator != 1:
                frac = Fraction(frac / 1.5)
                dots += 1
                if dots >= MAX_DURATION_DOTS:
                    raise ValueError
            return Duration(
                frac.denominator,
                dots=dots,
                is_rest=self.is_rest and other.is_rest,
            )
        except ValueError as err:
            frac = self.fraction + other.fraction
            msg = "the + operation would result in the invalid Duration: "
            msg += f"{frac.numerator}/{frac.denominator}"
            raise ValueError(msg) from err

    def __radd__(self, other: Union[int, Duration]) -> Duration:
        if other == 0:
            return self
        if not isinstance(other, Duration):
            raise TypeError(
                f"unsupported operand type(s) for +: 'Duration' and '{type(other)}'"
            )
        return self.__add__(other)

    def __sub__(self, other: Duration) -> Duration:
        if not isinstance(other, Duration):
            raise TypeError(
                f"unsupported operand type(s) for -: 'Duration' and '{type(other)}'"
            )
        try:
            frac = self.fraction - other.fraction
            return Duration(
                frac.denominator,
                is_rest=self.is_rest and other.is_rest,
            )
        except ValueError as err:
            msg = "the - operation would result in an invalid Duration."
            raise ValueError(msg) from err

    def _operate(
        self,
        other: Union[int, float],
        oper: Callable,
    ) -> Duration:
        frac = Fraction(oper(self.fraction, other))
        return Duration(frac.denominator, is_rest=self.is_rest)

    def __mul__(self, other: Union[int, float]) -> Duration:
        return self._operate(other, operator.mul)

    def __rmul__(self, other: Union[int, float]) -> Duration:
        return self._operate(other, operator.mul)

    def __truediv__(self, other: Union[int, float]) -> Duration:
        return self._operate(other, operator.truediv)

decimal: float property

Get the duration as a decimal value.

Returns:

Type Description
float

The duration as a decimal

fraction: Fraction property

Get the duration as a Fraction.

Returns:

Type Description
Fraction

The duration as a fraction

milliseconds(tempo)

Get the duration in milliseconds, given a tempo.

Parameters:

Name Type Description Default
tempo Tempo

The tempo used to calculate the duration.

 required

Returns:

Type Description
float

The duration in milliseconds
Source code in staff/duration.py 
142
143
144
145
146
147
148
149
150
151
152
153
def milliseconds(self, tempo: Tempo) -> float:
    """Get the duration in milliseconds, given a tempo.

    Args:
        tempo: The tempo used to calculate the duration.

    Returns:
        The duration in milliseconds
    """
    if not isinstance(tempo, Tempo):
        raise TypeError("tempo must be an instance of 'Tempo'")
    return (self.decimal / tempo.beat.decimal) * tempo.beat_milliseconds

Tuplet

A duration tuplet (triplet, quintuplet, etc)

Parameters:

Name Type Description Default
divisions int

Number of divisions of the total duration

 required
duration Duration

The tuplet's total duration

 required
Source code in staff/duration.py 
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
@dataclass(frozen=True)
class Tuplet:
    """A duration tuplet (triplet, quintuplet, etc)

    Args:
        divisions: Number of divisions of the total duration
        duration: The tuplet's total duration
    """

    divisions: int
    duration: Duration

    def __post_init__(self):
        if not isinstance(self.divisions, int):
            raise TypeError("divisions must be expressed as an 'int'")

        if not isinstance(self.duration, Duration):
            raise TypeError("duration must be an instance of 'Duration'")

    def to_milliseconds(self, tempo: Tempo):
        """The millisecond duration of each subdivision of the tuplet.

        Args:
            tempo: The tempo used to calculate the duration.
        """
        if not isinstance(tempo, Tempo):
            raise TypeError("tempo must be an instance of 'Tempo'")
        return [
            self.duration.milliseconds(tempo=tempo) / self.divisions
            for _ in range(self.divisions)
        ]

to_milliseconds(tempo)

The millisecond duration of each subdivision of the tuplet.

Parameters:

Name Type Description Default
tempo Tempo

The tempo used to calculate the duration.

 required
Source code in staff/duration.py 
245
246
247
248
249
250
251
252
253
254
255
256
def to_milliseconds(self, tempo: Tempo):
    """The millisecond duration of each subdivision of the tuplet.

    Args:
        tempo: The tempo used to calculate the duration.
    """
    if not isinstance(tempo, Tempo):
        raise TypeError("tempo must be an instance of 'Tempo'")
    return [
        self.duration.milliseconds(tempo=tempo) / self.divisions
        for _ in range(self.divisions)
    ]