The duration module

Functions to deal with LilyPond’s musical durations.

A duration is a Fraction or an integer, where a whole note is 1. A duration can be split in two values, log and dot-count, where the log value is 0 for a whole note, 1 for a half note, 2 for a crotchet, -1 for a \breve, etc. This is the same way LilyPond handles durations.

Durations can be scaled using multiplying, e.g. with a Fraction.

class Transform(log=0, dotcount=0, scale=1)

Bases: object

Combine modifications of a duration (shift and/or scale).

Use it to calculate the real length of musical items. Transforms can be added. A Transform that doesn’t modify anything evaluates to False.

log

the log to shift

dotcount

the dots to shift

scale

the scaling

length(duration, scaling=1)

Return the actual musical length of the duration and scaling values.

transform(duration, scaling=1)

Return a transformed two-tuple (duration, scaling).

log_dotcount(value)

Return the integer two-tuple (log, dotcount) for the duration value.

The value may be a Fraction, integer or floating point value.

The returned log is 0 for a whole note, 1 for a half note, 2 for a crotchet, -1 for a \\breve, etc. This is the same way LilyPond handles durations. For example:

>>> from quickly.duration import log_dotcount
>>> log_dotcount(1)
(0, 0)
>>> log_dotcount(1/2)
(1, 0)
>>> log_dotcount(4)
(-2, 0)
>>> log_dotcount(1/4)
(2, 0)
>>> log_dotcount(3/4)
(1, 1)
>>> log_dotcount(7/16)
(2, 2)
>>> to_string(duration(*log_dotcount(Fraction(3, 4))))
'2.'

The value is truncated to a duration that can be expressed by a note length and a number of dots. For example:

>>> to_string(duration(*log_dotcount(1)))
'1'
>>> to_string(duration(*log_dotcount(1.4)))
'1'
>>> to_string(duration(*log_dotcount(1.5)))
'1.'
>>> to_string(duration(*log_dotcount(0.9999)))
'2............'

duration(log, dotcount=0)

Return the duration as a Fraction.

See for an explanation of the log and dotcount values log_dotcount().

shift_duration(value, log, dotcount=0)

Shift the duration.

This function is analogous to LilyPond’s \shiftDurations command. It modifies a duration by shifting the log and the number of dots. Adding 1 to the log halves the note length, and adding a dot mutiplies the note length with (1 + 1/2**<dots>). Subtracting 1 from the log doubles the note length.

The value should be a duration that is expressable by a note length and a number of dots. A Fraction is returned. log is the scaling as a power of 2; and dotcount the number of dots to be added (or removed, by specifying a negative value).

For example:

>>> shift_duration(Fraction(1, 8), -1)
Fraction(1, 4)
>>> shift_duration(Fraction(1, 8), -2)
Fraction(1, 2)
>>> shift_duration(Fraction(1, 4), 1, 1)
Fraction(3, 16)
>>> to_string(shift_duration(Fraction(1,4), 1, 1))
'8.'
>>> to_string(shift_duration(from_string('2'), 1, 1))
'4.'
>>> shift_duration(Fraction(7, 8), 0, -2)
Fraction(1, 2)
>>> shift_duration(Fraction(7, 8), 0, -1)
Fraction(3, 4)

The number of dots in a duration will never drop below zero:

>>> shift_duration(1/4, 0, -1)
Fraction(1, 4)

to_string(value)

Convert the value (most times a Fraction) to a LilyPond string notation.

The value is truncated to a duration that can be expressed by a note length and a number of dots. For example:

>>> from fractions import Fraction
>>> from quickly.duration import to_string
>>> to_string(Fraction(3, 2))
'1.'
>>> to_string(4)
'\\longa'
>>> to_string(7.75)
'\\longa....'

Raises an IndexError if the base duration is too long (longer than \maxima).

from_string(text, dotcount=None)

Convert a LilyPond duration string (e.g. '4.') to a Fraction.

The durations \breve, \longa and \maxima may be used with or without backslash. If dotcount is None, the dots are expected to be in the text.

For example:

>>> from quickly.duration import from_string
>>> from_string('8')
Fraction(1, 8)
>>> from_string('8..')
Fraction(7, 32)
>>> from_string('8', dotcount=2)
Fraction(7, 32)

Raises a ValueError if an invalid duration is specified.

is_writable(value)

Return True if the value can be exactly expressed in a log and dotcount value, without loss.

The value should be >= 1/1024 and < 16, because LilyPond can’t display more than 8 flags and \maxima is the longest available duration name.