music.tremolo

music.tremolo(duration=2, tremolo_freq=2, max_db_dev=10, alpha=1, waveform_table=array([0., 0.0003835, 0.00076699, ..., -0.00115049, -0.00076699, -0.0003835], shape=(16384,)), number_of_samples=None, sonic_vector=0, sample_rate=None)

Synthesize a tremolo envelope or apply it to a sound.

Set fa=0 or dB=0 for a constant envelope with value 1. A tremolo is an oscillatory pattern of loudness [1].

Parameters:

durationscalar

The duration of the envelope in seconds.

tremolo_freqscalar

The frequency of the tremolo oscillations in Hertz.

max_db_devscalar

The maximum deviation of loudness in the tremolo in decibels.

alphascalar

An index to distort the tremolo pattern [1].

waveform_tablearray_like

The table with the waveform for the tremolo oscillatory pattern.

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 tremolo 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. None, the default, is the rate music.get_sample_rate() returns.

Returns:

tndarray

A numpy array where each value is a PCM sample of the envelope. If sonic_vector is input, t is the sonic vector with the tremolo applied to it.

Raises:

ValueError

If alpha is negative: it bends a tremolo through zero, where a negative power has no finite value, and the render came back holding infinity behind a warning.

See also

note_with_vibrato

A musical note with an oscillation of pitch.

note_with_fm

A linear oscillation of fundamental frequency.

am

A linear oscillation of amplitude.

Notes

The tremolo’s pattern is read from its table as a vibrato’s is, and it takes the level up to \(V_{dB}\) decibels either way, as the article writes a tremolo [1]:

\[a_i = 10^{t'_i V_{dB} / 20}, \qquad t'_i = \tilde{m}_{\gamma'_i \bmod \tilde{\Lambda}_M}, \qquad \gamma'_i = \left\lfloor i f' \frac{\tilde{\Lambda}_M}{f_s} \right\rfloor,\]

where \(\tilde{m}\) is waveform_table, \(f'\) is tremolo_freq and \(V_{dB}\) is max_db_dev. Given a sonic_vector \(t\), it returns \(t_i a_i\). In decibels the swing is the same either way – 10 dB up and down is a factor of 3.16 one way and of 0.316 the other – which is why a tremolo is written in them, where am() moves the amplitude itself. With alpha other than 1 the exponent is bent as note_with_vibrato() bends its own.

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() * tremolo())  # a note with tremolo
>>> s = horizontal_stack(
...     *[note_with_vibrato() * tremolo(tremolo_freq=i, max_db_dev=j)
...      for i, j in zip([6, 15, 100], [2, 1, 20])])
>>> s = horizontal_stack(
...     *[tremolo(tremolo_freq=i, max_db_dev=j,
...              sonic_vector=note_with_vibrato())
...      for i, j in zip([6, 15, 100], [2, 1, 20])])
>>> envelope2 = tremolo(440, 1.5, 60)  # a lengthy envelope