music.cross_fade

music.cross_fade(sonic_vector_1, sonic_vector_2, duration_ms=500, method='lin', sample_rate=None, **renamed)

Cross fade two sounds over duration_ms milliseconds.

The tail of the first sound is faded out, the head of the second is faded in, and the two are overlapped by that duration, so the result is shorter than the two inputs laid end to end.

Parameters:

sonic_vector_1array_like

The sound that fades out. Mono, or (2, nsamples) stereo.

sonic_vector_2array_like

The sound that fades in, of the same number of dimensions.

duration_msscalar

The length of the crossfade in milliseconds.

methodstr

The fade shape, as fade() takes it: “lin” or “linear”, “exp” or “exponential”.

sample_rateinteger or None

The sample rate in Hertz. None, the default, is the rate music.get_sample_rate() returns.

**renamed

duration, the name duration_ms had before it said its unit beside fade()’s duration, which is in seconds. Still accepted, with a DeprecationWarning.

Returns:

ndarray

The two sounds overlapped, duration_ms milliseconds shorter than their concatenation.

Raises:

ValueError

If the two sounds do not have the same number of dimensions. Crossfading a mono sound with a stereo one has no single sensible answer, so it is refused rather than guessed at.

If duration_ms is not a positive number of samples at sample_rate, or is longer than the shorter of the two sounds. Both used to reach a NumPy broadcast failure naming two sample counts, which does not say which duration caused it.

TypeError

If a keyword is neither a parameter nor the old name.

See also

fade

the fade in or out on its own.

music.StimulationSession

crossfades that preserve total duration.

Notes

The inputs are left as they were. The fades used to be applied to the caller’s arrays, the one routine here that did that, so crossfading the same two sounds twice faded each of them twice.

The overlap makes the result shorter, which is why music.StimulationSession does not use this function: a protocol’s phase durations have to survive its transitions.

Examples

>>> joined = cross_fade(note(220, 1), note(330, 1), duration_ms=200)
>>> len(joined) / 44100    # the overlap is 200 ms of the two seconds
1.8