music.loud

music.loud(duration=2, trans_dev=10, alpha=1, to=True, method='exp', number_of_samples=None, sonic_vector=0, sample_rate=None)

An envelope for a linear or exponential transition of amplitude.

An exponential transition of amplitude is a linear transition of its level in decibels, which is heard as a steady change of loudness.

Parameters:

durationscalar

The duration of the envelope in seconds.

trans_devscalar

The deviation of the transition. If method=”exp”, the deviation is in decibels. If method=”linear”, the deviation is an amplitude proportion.

alphascalar

An index to make the transition slower or faster [1]. Ignored if method=”linear”.

tobool

If True, the transition ends at the deviation. If False, the transition starts at the deviation.

methodstr

“lin” or “linear” for a linear transition of amplitude; “exp” or “exponential” for an exponential transition of amplitude (linear loudness).

number_of_samplesinteger or None

The number of samples of the envelope. If given, duration is ignored, and zero is an envelope of no samples.

sonic_vectorarray_like

Samples for the envelope to be applied to. If supplied, duration and number_of_samples are ignored. Mono, or of shape (nchannels, nsamples), every channel shaped alike.

sample_rateinteger or None

The sample rate. Only used if number_of_samples and sonic_vector are not supplied. None, the default, is the rate music.get_sample_rate() returns.

Returns:

endarray

A numpy array where each value is a value of the envelope for the PCM samples. If sonic_vector is supplied, e is the sonic vector with the envelope applied to it.

Raises:

ValueError

If method is not 'lin', 'linear', 'exp' or 'exponential'.

If alpha is negative and the transition exponential: it bends a transition from zero, where a negative power has no finite value, and the envelope came back holding infinity.

See also

louds

An envelope with an arbitrary number of transitions.

fade

Fade in and out.

adsr

An ADSR envelope.

tremolo

An oscillation of loudness.

Notes

The exponential transition is the article’s, in decibels [1]: from 0 dB to \(V_{dB}\), trans_dev, bent by alpha,

\[a_i = 10^{\frac{V_{dB}}{20} \left(\frac{i}{\Lambda - 1}\right)^{\alpha}}, \qquad i = 0, 1, \ldots, \Lambda - 1,\]

or from \(V_{dB}\) back to 0 dB with to false, \(i\) then counted from the end. The linear one moves the amplitude itself, from \(a_0 = 1\) to \(a_{\Lambda-1}\), trans_dev, or back:

\[a_i = a_0 + (a_{\Lambda-1} - a_0) \frac{i}{\Lambda - 1}.\]

Cite the following article whenever you use this function.

References

[1]

Fabbri, Renato, et al. “Musical elements in the discrete-time representation of sound.” arXiv preprint arXiv:abs/1412.6853 (2017)

Examples

>>> write_wav_mono(note_with_vibrato() * loud())
>>> s = horizontal_stack(*[note_with_vibrato() *
...                       loud(trans_dev=i, method=j)
...                       for i, j in zip([6, -50, 2.3],
...                                       ["exp", "exp", "linear"])])
>>> s = horizontal_stack(*[
...     loud(trans_dev=i, method=j, sonic_vector=note_with_vibrato())
...     for i, j in zip([6, -50, 2.3], ["exp", "exp", "linear"])])
>>> envelope = loud(duration=10, trans_dev=-80, to=False, alpha=2)