music.fade

music.fade(duration=2, fade_out=True, method='exp', db=-80, alpha=1, perc=1, number_of_samples=None, sonic_vector=0, sample_rate=None)

A fade in or out.

Implements the loudness transition and asserts that it reaches zero amplitude.

Parameters:

durationscalar

The duration in seconds of the fade.

fade_outbool

If True, the fade is a fade out, else it is a fade in.

methodstr

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

dbscalar

The decibels from which to reach before using the linear transition to reach zero. Not used if method=”linear”.

alphascalar

An index to make the exponential fade slower or faster [1]. Ignored if transitions=”linear”.

percscalar

The percentage of the fade that is linear to ensure it reaches zero. It has no effect if method=”linear”.

number_of_samplesinteger or None

The number of samples of the fade. If given, duration is ignored, and zero is a fade of no samples.

sonic_vectorarray_like

Samples for the fade to be applied to. If supplied, duration and number_of_samples are ignored.

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:

aindarray

Each value is a value of the envelope for the PCM samples. If sonic_vector is input, ai is the sonic vector with the fade applied to it.

Raises:

ValueError

If perc is outside [0, 100], or if method is not one of the four names above. A percentage over 100 used to reach an IndexError from inside the routine, and an unknown method an UnboundLocalError, neither of which says what the caller did. Names were once matched by substring, so "explicit" was exponential; they are now the ones loud() takes.

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

adsr

An ADSR envelope.

loud

A transition of loudness.

louds

An envelope with an arbitrary number or loudness transitions.

tremolo

An oscillation of loudness.

Notes

An exponential fade is loud()’s transition between 0 dB and db, -80 dB by default, which never reaches silence: so the last perc percent of a fade out, or the first of a fade in, is a straight line between zero and wherever the exponential has got to [1]. A linear fade is a straight line all the way, from 1 to 0 or from 0 to 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() * fade())
>>> s = horizontal_stack(*[note_with_vibrato() * fade(fade_out=i, method=j)
...                       for i, j in zip([1, 0, 1],
...                                       ["exp", "exp", "linear"])])
>>> s = horizontal_stack(
...     *[fade(fade_out=i, method=j, sonic_vector=note_with_vibrato())
...                       for i, j in zip([1, 0, 1],
...                                       ["exp", "exp", "linear"])])
>>> envelope = fade(duration=10, fade_out=0, perc=0.1)