Skip to content

DurationValue

duration_value

Note duration values (whole, half, quarter, ... + dotted variations).

The DurationValue namespace converts between named durations ("quarter", "q", "q.") and their fractional values relative to a whole note. Useful for music notation tooling.

Each duration entry has a denominator (whole = 1, quarter = 4, ...), a shorthand string (q, e, s, ...), and a list of full names. Dotted variations (q., q..) are computed on the fly.

Example

from tonal_py import DurationValue DurationValue.value("q") # quarter note 0.25 DurationValue.value("q.") # dotted quarter 0.375 DurationValue.fraction("q.") (3, 8)

Source parity: @tonaljs/duration-value

names 

names() -> list[str]

Return every full duration name across all entries.

Each entry contributes multiple names (e.g. quarter has ["quarter", "crotchet"]).

Example

from tonal_py import DurationValue "quarter" in DurationValue.names() True "whole" in DurationValue.names() True

Source code in src/tonal_py/duration_value.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def names() -> list[str]:
    """Return every full duration name across all entries.

    Each entry contributes multiple names (e.g. quarter has `["quarter",
    "crotchet"]`).

    Example:
        >>> from tonal_py import DurationValue
        >>> "quarter" in DurationValue.names()
        True
        >>> "whole" in DurationValue.names()
        True
    """
    return [n for d in _VALUES for n in d.names]

shorthands 

shorthands() -> list[str]

Return the shorthand strings (w, h, q, e, ...).

Example

from tonal_py import DurationValue DurationValue.shorthands()[:5]['dl', 'l', 'd', 'w', 'h']

Source code in src/tonal_py/duration_value.py 
86
87
88
89
90
91
92
93
94
def shorthands() -> list[str]:
    """Return the shorthand strings (`w`, `h`, `q`, `e`, ...).

    Example:
        >>> from tonal_py import DurationValue
        >>> DurationValue.shorthands()[:5]
        ['dl', 'l', 'd', 'w', 'h']
    """
    return [d.shorthand for d in _VALUES]

get 

get(name: str) -> DurationValue

Get a duration by name or shorthand, including dotted variations.

Parameters:

Name Type Description Default
name str

A duration name or shorthand. Trailing dots add half the previous value each (e.g. "q." = 1.5x quarter).

 required

Returns:

Type Description
DurationValue

A DurationValue dataclass. Returns NO_DURATION for unknown input.
Example

from tonal_py import DurationValue DurationValue.get("quarter").value 0.25 DurationValue.get("q").value 0.25 DurationValue.get("q.").fraction (3, 8)

Source code in src/tonal_py/duration_value.py 
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
def get(name: str) -> DurationValue:
    """Get a duration by name or shorthand, including dotted variations.

    Args:
        name: A duration name or shorthand. Trailing dots add half the
            previous value each (e.g. `"q."` = 1.5x quarter).

    Returns:
        A `DurationValue` dataclass. Returns `NO_DURATION` for unknown input.

    Example:
        >>> from tonal_py import DurationValue
        >>> DurationValue.get("quarter").value
        0.25
        >>> DurationValue.get("q").value
        0.25
        >>> DurationValue.get("q.").fraction
        (3, 8)
    """
    m = _REGEX.match(name)
    if not m:
        return NO_DURATION
    simple = m.group(1)
    dots = m.group(2)
    base = next(
        (d for d in _VALUES if d.shorthand == simple or simple in d.names),
        None,
    )
    if base is None:
        return NO_DURATION
    fraction = _calc_dots(base.fraction, len(dots))
    value_ = fraction[0] / fraction[1]
    return DurationValue(
        empty=False,
        name=name,
        value=value_,
        fraction=fraction,
        shorthand=base.shorthand,
        dots=dots,
        names=base.names,
    )

value 

value(name: str) -> float

Get a duration as a float (1.0 = whole note).

Example

from tonal_py import DurationValue DurationValue.value("q") 0.25 DurationValue.value("h.") # dotted half 0.75

Source code in src/tonal_py/duration_value.py 
157
158
159
160
161
162
163
164
165
166
167
def value(name: str) -> float:
    """Get a duration as a float (1.0 = whole note).

    Example:
        >>> from tonal_py import DurationValue
        >>> DurationValue.value("q")
        0.25
        >>> DurationValue.value("h.")        # dotted half
        0.75
    """
    return get(name).value

fraction 

fraction(name: str) -> tuple[int, int]

Get a duration as a (numerator, denominator) reduced fraction.

Example

from tonal_py import DurationValue DurationValue.fraction("q") (1, 4) DurationValue.fraction("q.") (3, 8)

Source code in src/tonal_py/duration_value.py 
170
171
172
173
174
175
176
177
178
179
180
def fraction(name: str) -> tuple[int, int]:
    """Get a duration as a `(numerator, denominator)` reduced fraction.

    Example:
        >>> from tonal_py import DurationValue
        >>> DurationValue.fraction("q")
        (1, 4)
        >>> DurationValue.fraction("q.")
        (3, 8)
    """
    return get(name).fraction