music.StimulationSession

class music.StimulationSession(sample_rate=44100, end_ramp=0.0, ramp_shape='equal_power', phases=<factory>)

Bases: object

A sequence of stimuli rendered as one sound.

Phases are added in order and rendered end to end. Each transition is a crossfade centred on the boundary between the phases it joins, so the session lasts exactly the sum of its phase durations: a ramp is taken half from the phase before it and half from the phase after, rather than being inserted between them and stretching the protocol past the length its author wrote down. A protocol that says ten minutes lasts ten minutes.

Ramps that cannot fit are shortened before rendering. Phases are considered from first to last; each divides its available samples between its requested incoming and outgoing ramps in proportion to the space they need. Both neighbors use the same shortened transition. This prevents overlapping crossfades around a short middle phase and preserves both outer fades. Arrays keep their original samples and give up only their share of the effective overlaps.

A callable phase whose duration rounds to zero samples contributes nothing and is not called. At sample resolution, a one-sample closing fade is silence; a one- or two-sample phase with both outer fades therefore renders silence.

Attributes:

sample_rateinteger

The sampling frequency in Hertz, passed to every callable stimulus so the whole session is rendered at one rate.

end_rampscalar

The fade to silence at the end of the session, in seconds. Like the fade in at the start – the first phase’s ramp – it is taken from within the session rather than added to it, because there is no neighbouring phase for it to overlap.

ramp_shapestr

'equal_power', the default, or 'linear'. See _ramp_shape() for which to want when.

phaseslist of StimulusPhase

The phases, in order. Normally built with add().

Parameters:

• sample_rate (int)

• end_ramp (float)

• ramp_shape (str)

• phases (List[StimulusPhase])

See also

music.Sequencer

notes scheduled at arbitrary offsets, which is the musical version of the same idea.

Examples

>>> import music
>>> session = music.StimulationSession(end_ramp=0.05)
>>> session.add(music.binaural_beats, duration=0.2, beat_freq=10)
>>> session.add(music.isochronic_tones, duration=0.2, ramp=0.05,
...             pulse_rate=6)
>>> session.duration
0.4
>>> session.render().shape
(2, 17640)

__init__(sample_rate=44100, end_ramp=0.0, ramp_shape='equal_power', phases=<factory>)

Parameters:

• sample_rate (int)

• end_ramp (float)

• ramp_shape (str)

• phases (List[StimulusPhase])

Return type:

None

Methods

__init__([sample_rate, end_ramp, ...])
add(stimulus[, duration, ramp, gain, label])	Append a phase.
render()	Render every phase and mix them into one sound.
write(filename[, bit_depth])	Render the session and write it to a WAV file.

Attributes

duration	How long the session lasts, in seconds.
end_ramp
ramp_shape
sample_rate
phases

sample_rate: int = 44100

end_ramp: float = 0.0

ramp_shape: str = 'equal_power'

phases: List[StimulusPhase]

add(stimulus, duration=0.0, ramp=0.0, gain=1.0, label='', **parameters)

Append a phase.

Parameters:

stimuluscallable() or array_like

The generator to render, or an already rendered sound.

durationscalar

How long the phase lasts, in seconds. Required for a callable; ignored for an array, which brings its own length.

rampscalar

The transition into this phase, in seconds.

gainscalar

A factor applied to the phase before mixing.

labelstr

A name for the phase.

**parameters

Passed to stimulus when it is a callable, so a phase is written as the generator plus the arguments it would have been called with.

Raises:

ValueError

If ramp or duration is negative, or if a callable stimulus is given no duration – it would render nothing, and silently dropping a phase from a protocol is worse than refusing it.

Parameters:

• stimulus (Callable[[...], ArrayLike] | ArrayLike)

• duration (float)

• ramp (float)

• gain (float)

• label (str)

• parameters (Any)

Return type:

None

property duration: float

How long the session lasts, in seconds.

Measured from the layout rather than from the durations that were asked for, so it reports what will actually be rendered.

render()

Render every phase and mix them into one sound.

Returns:

ndarray

A one-dimensional array, or a (2, nsamples) one if any phase is stereo – a session that mixes binaural beats with isochronic tones is stereo throughout, because the two cannot share a channel layout and the binaural phase is the one that would be destroyed by flattening.

Raises:

ValueError

If a callable stimulus returns a length other than the one it was asked for. Every generator in this package honours number_of_samples; one that does not would silently shift every phase after it.

Return type:

NDArray[float64]

write(filename, bit_depth=16)

Render the session and write it to a WAV file.

Parameters:

filenamestr

The path to write to.

bit_depthinteger

The bit depth of the samples written.

Parameters:

• filename (str)

• bit_depth (int)

Return type:

None