Shorthand volume notation - davidpanderson/Numula GitHub Wiki

Numula provides two shorthand notations for describing volume changes over time: one for continuous change, and one for accents.

As with Numula's other shorthand notations, you can use iteration, substitution, and comments.

Notating piecewise continuous volume change

from numula.notate_nuance import *
from numula.vol_names import *

sh_vol('pp 2/4 mf 4/4 pp')

denotes a volume change from pp to mf over 2 beats, them back to pp over 4 beats. It's equivalent to

[
    Linear(pp, mf, 2/4),
    Linear(mf, pp, 4/4)
]

Time intervals must be notated as N/M. You can specify volume levels using the following symbols:

pppp    = .01
pppp_   = .08
_ppp    = .16
ppp     = .23
ppp_    = .30
_pp     = .38
pp      = .45
pp_     = .52
_p      = .60
p       = .67
p_      = .74
_mp     = .82
mp      = .89
mp_     = .96
mm      = 1
_mf     = 1.04
mf      = 1.11
mf_     = 1.18
_f      = 1.26
f       = 1.33
f_      = 1.40
_ff     = 1.48
ff      = 1.55
ff_     = 1.62
_fff    = 1.68
fff     = 1.77
fff_    = 1.84
_ffff   = 1.92
ffff    = 1.99

Alternatively, you can specify levels directly; for example,

sh_vol('pp 2/4 mf 4/4 pp')
sh_vol('.45 2/4 1.1 4/4 .45')

are equivalent.

sh_vol() returns a PFT that you can apply to a score using vol_adjust_pft():

ns = Score()
...
pft = sh_vol('pp 2/4 mf 4/4 pp')
ns.vol_adjust_pft(pft, 0)

Discontinuities are notated as

sh_vol('pp 2/4 mf ] mp 4/4 pp')

This means: go from pp to mf over 2 beats, then from mp to pp over 4 beats. The ] means the volume at the boundary is that of the first segment, i.e. mf. [ means use the volume of the second segment. So the above is equivalent to

[
    Linear(pp, mf, 2/4, closed_end=True),
    Linear(mp, pp, 4/4, closed_start=False)
]

By default, sh_vol() generates linear segments. You can also use exponential curves:

sh_vol('exp3.0 pp 2/4 mf linear 4/4 pp')

is equivalent to

[
    ExpCurve(3.0, pp, mf, 2/4),
    Linear(mf, pp, 4/4)
]

Notating accents

You can create a PFT to accent (or attenuate) notes at particular times as follow:

sh_accents('f 3/4 mf 1/4')

This accents the downbeat of a 4/4 measure, and adds a smaller accent to the 4th beat. It's equivalent to

[
    Accent(f),
    Unity(3/4),
    Accent(mf),
    Unity(1/4)
]

sh_accents() returns a PFT that you can apply to a score using vol_adjust_pft().

The default mode is VOL_MULT: a f accent multiplies the volume by 1.33; it doesn't set the volume to 1.33. You can also use VOL_ADD or VOL_SET.