music.StimulusPhase

class music.StimulusPhase(stimulus, duration=0.0, ramp=0.0, gain=1.0, label='', parameters=<factory>)[source]

Bases: object

One phase of a session: a stimulus, for a while, ramped into.

Attributes:
stimuluscallable() or array_like

What to render. A callable is called with number_of_samples and sample_rate alongside parameters, which is what every generator in music.stimulation accepts, so the session can render it at exactly the length the arrangement needs. An array is taken as it stands.

durationscalar

How long the phase lasts, in seconds, not counting its share of the ramps at either end. Ignored when stimulus is an array, which brings its own length.

rampscalar

The length in seconds of the transition into this phase: a crossfade with the phase before it, or a fade in from silence for the first phase.

gainscalar

A factor applied to the phase before it is mixed, for balancing stimuli of different loudness against each other.

labelstr

A name for the phase, carried for the reader’s sake and shown in the session’s repr.

parametersdict

Keyword arguments passed to stimulus when it is a callable.

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. Only StimulationSession.add() checked, so a phase made by hand was refused nowhere.

Parameters:

Examples

>>> phase = StimulusPhase(stimulus=binaural_beats, duration=0.2,
...                       ramp=0.05, gain=0.5)
>>> phase.duration, phase.ramp, phase.gain
(0.2, 0.05, 0.5)

A session builds these for you, so one is rarely written by hand:

>>> session = StimulationSession()
>>> session.add(binaural_beats, duration=0.2, ramp=0.05, beat_freq=10)
>>> session.phases[0].duration
0.2
__init__(stimulus, duration=0.0, ramp=0.0, gain=1.0, label='', parameters=<factory>)
Parameters:
Return type:

None

Methods

__init__(stimulus[, duration, ramp, gain, ...])

Attributes

duration

gain

label

ramp

stimulus

parameters

stimulus: Callable[[...], ArrayLike] | ArrayLike
duration: float = 0.0
ramp: float = 0.0
gain: float = 1.0
label: str = ''
parameters: Dict[str, Any]