sc3.synth.envelope module¶

Env.sc

class Env(levels=None, times=None, curves='lin', release_node=None, loop_node=None, offset=0)¶

Bases: sc3.synth._graphparam.UGenParameter, sc3.synth._graphparam.NodeParameter

Specification for a segmented envelope.

Envelope specifications are used for server-side parameters’ generation for EnvGen or IEnvGen. They can be used client-side through the Pseq mostly equivalent time pattern.

Envelopes can be of fixed duration or sustained, if a release node is defined. There is a number specialized constructor methods with the most common envelopes.

This class supports multichannel expansion and ugens as inputs for the levels parameters (as supported by EnvGen).

Parameters

levels (list) – Amplitude levels of the envelope. The first value is the initial level of the envelope. When the envelope is used with an EnvGen, levels can be any ugen (new level values are updated only when the envelope has reached that point). When the array of levels contains itself an array, the envelope returns a multichannel output (see multichannel expansion).
times (list | float | int) – Transition times to the next level values. There should be one fewer duration than there are levels, but if shorter, the array is extended by wrapping around the given values. If a scalar value is supplied all durations will be equal.
curves (list | str | float | int) – Determine the shape of the transition segments. Possible values are: ‘linear’ or ‘lin’, linear segments (default), ‘step’, flat segments (immediately jumps to final value), ‘hold’, flat segments (holds initial value, jump to final value at the end of the segment), ‘exponential’ or ‘exp’, natural exponential growth and decay (in this case, the levels must all be nonzero and have the same sign), ‘sine’ or ‘sin’, sinusoidal S shaped segments, ‘welch’ or ‘wel’, sinusoidal segments shaped like the sides of a Welch window, ‘squared’ or ‘sqr’, squared segment, ‘cubed’ or ‘cub’, cubed segment, a float value, that determines the curvature value for all segments (0 means linear, positive and negative numbers curve the segment up and down) or a list of the above values determining the curvature for each segment.
release_node (int) – If set, the envelope will sustain at the release node level until released.
loop_node (int) – Define a node as the time point at which a loop is created between the next node and the release node levels. The level of the loop node is ignored, only the transition time to the next node is used in the loop as the time from the release node level to the next node level.
offset (float | int) – An offset to all time values (only applies in IEnvGen).

Notes

Internally, an envelope specification consist of an initial level value followed by time segments specified as target level value, duration to reach the target level, the shape of the segment and a cuve value (used only if the shape type if 5). These time segments are called evelope nodes.

Constructors of this class group these parameters as separated lists of levels, times and curves. This representation is consistent with event patterns rather than server command.

For example, a fixed time envelope is defined as follows.:

# Fixed time triangular envelope of duration 2.
levels = [0, 1, 0]  # An initial level, followed by 2 target levels.
times = [1, 1]  # The duration to the target levels.
curves = 'lin'  # The curve of the segments to reach next levels.
env = Env(levels, times, curves)

Fixed duration envelopes are triggered from the EnvGen gate parameter. The initial value of the envelope only acts as the start value and is never repeated. Thus, at the moment envelopes are re-triggered the first node becomes the target node and the transition starts from whatever the current level value of the envelope is at that moment.

Sustained envelopes define a release node. The EnvGen gate parameter acts as a normal gate in this case. While the gate is open and the envelope reach the release node, it holds its level value until the gate is closed and then starts the transition to the next node through the end of the envelope.:

# Sustained trapezoidal envelope
levels = [0, 1, 0]  # An initial level, followed by 2 target levels.
times = [0.1, 0.1]  # The duration to the target levels.
curves = 'lin'  # The curve of the segments to reach next levels.
release_node = 1  # Hold node at level 1 before the last target.
env = Env(levels, times, curves, release_node)

Sustained envelopes define can define a loop between nodes for the sustain part by defining both the release and loop nodes.:

# Sustained ADSR envelope with loop node.
levels = [0, 1, 0.25, 0.75, 0.5, 0]
times = [0.02, 0.18, 0.2, 0.8, 0.02]
release_node = 4
loop_node = 2
env = Env(levels, times, curves, release_node)

Something that is sometimes confusing is that both the release node and the loop node are the nodes prior to the actual destination nodes (targets) for the loop and release phases of the envelope. This is just because the transition duration belongs to the target node and the loop/release node whould be the time point before that transition. In the example above, the release node (four) starts the loop between the node after the loop node and itself oscilating linearly between levels 0.5 and 0.75 at 1 Hertz, taking 0.2 seconds to reach the target level 0.75 and 0.8 to reach target level 0.5. As soon as the gate is closed by the EnvGen ugen, the envelope starts the transition from whatever the current value of the envelope is, in this case it will be between 0.5 and 0.75, taking 0.02 seconds to reach level 0. Sigh.

classmethod xyc(xyc)¶

Fixed duration envelope from control points with curvature.

Parameters: xyc (list) – A list of lists of three elements [time, level, curve]. if possible, pairs are sorted regarding their point in time. Default curve value is ‘lin’.

classmethod pairs(pairs, curves=None)¶

Fixed duration envelope from control points.

Parameters

pairs (list) – A list of lists of two elements [time, level]. if possible, pairs are sorted regarding their point in time.
curve (list | str | float | int) – Curvature of the segments. Default value is ‘lin’.

classmethod triangle(dur=1.0, level=1.0)¶

Fixed duration envelope specification with triangular shape.

Parameters

dur (list | float | int) – Duration of the envelope.
level (list | float | int) – Peak level of the envelope.

classmethod sine(dur=1.0, level=1.0)¶

Fixed duration envelope specification with hanning shape.

Parameters

dur (list | float | int) – Duration of the envelope.
level (list | float | int) – Peak level of the envelope.

classmethod perc(attack_time=0.01, release_time=1.0, level=1.0, curve=- 4.0)¶

Fixed duration evenlope which (usually) has a percussive shape.

Parameters

attack_time (float | int | list) – Duration of the attack portion.
release_time (float | int | list) – Duration of the release portion.
level (float | int | list) – Peak level of the envelope.
curve (str | float | int | list) – Curvature of the envelope.

classmethod linen(attack_time=0.01, sustain_time=1.0, release_time=1.0, level=1.0, curve='lin')¶

Fixed duration envelope specification with trapezoidal shape.

Parameters

attack_time (list | float | int) – Duration of the attack portion.
sustain_time (list | float | int) – Duration of the sustain portion.
release_time (list | float | int) – Duration of the release portion.
level (list | float | int) – Level of the sustain portion.
curve (list | str | float | int) – Curvatuve of the envelope.

classmethod step(levels=None, times=None, release_level=None, loop_level=None, offset=0)¶

Sustained envelope where all the segments are horizontal lines.

Given n values of times only n levels need to be provided, corresponding to the fixed value of each segment.

Parameters

levels (list) – Levels can be any ugen (new level values are updated only when the envelope has reached that point).
times (list) – Durations of segments in seconds. It should be the same size as the levels array.
release_level (int) – The index of the release level. The envelope will sustain at this level until released.
loop_level (int) – Index of the loop level. If not None the envelop sustain will loop between this level and the release level.
offset (float | int) – Offset to all time values (only applies in IEnvGen).

classmethod cutoff(release_time=0.1, level=1.0, curve='lin')¶

Sustained envelope specification which has no attack segment.

It simply sustains at the peak level until released. Useful if you only need a fadeout, and more versatile than Line.

Parameters

release_time (list | float | int) – Duration of the release portion.
level (list | float | int) – Peak level of the envelope.
curve (str) – Curvature of the envelope.

classmethod dadsr(delay_time=0.1, attack_time=0.01, decay_time=0.3, sustain_level=0.5, release_time=1.0, peak_level=1.0, curve=- 4.0, bias=0.0)¶

Sustained adsr envelope with onset delay.

Parameters

delay_time (list | float | int) – Onset delay time.
attack_time (list | float | int) – Duration of the attack portion.
decay_time (list | float | int) – Duration of the decay portion.
sustain_level (list | float | int) – Level of the sustain portion as a ratio of the peak level.
release_time (list | float | int) – Duration of the release portion.
peak_level (list | float | int) – Peak level of the envelope.
curve (ist | str | float | int) – Curvature of the envelope.
bias (list | float | int) – DC offset.

classmethod adsr(attack_time=0.01, decay_time=0.3, sustain_level=0.5, release_time=1.0, peak_level=1.0, curve=- 4.0, bias=0.0)¶

Sustained envelope as traditional analog attack-decay-sustain-release.

Parameters

attack_time (list | float | int) – Duration of the attack portion.
decay_time (list | float | int) – Duration of the decay portion.
sustain_level (list | float | int) – Level of the sustain portion as a ratio of the peak level.
release_time (list | float | int) – Duration of the release portion.
peak_level (list | float | int) – Peak level of the envelope.
curve (ist | str | float | int) – Curvature of the envelope.
bias (list | float | int) – DC offset.

classmethod asr(attack_time=0.01, sustain_level=1.0, release_time=1.0, curve=- 4.0)¶

Sustained envelope as traditional analog attack-sustain-release.

Parameters

attack_time (list | float | int) – Duration of the attack portion.
sustain_level (list | float | int) – Level of the sustain portion as a ratio of the peak level.
release_time (list | float | int) – Duration of the release portion.
curve (ist | str | float | int) – Curvature of the envelope.

classmethod cyclic(levels, times, curves='lin')¶

Sustained envelope which cycles through its values.

For making a given envelope cyclic, you can use the instance method circle.

Parameters

levels (list) – Values through which the envelope passes.
times (list | float | int) – Durations between subsequent levels in the envelope. If a list shorter than the levels list is passed it will be expanded. In difference to the default constructor method, the size of the times array is the same as that of the levels, because it includes the loop time.
curves (list | str | float | int) – Curvature of the envelope. If a list shorter than the levels list is passed it will be expanded. In difference to the default constructor method, the size of the times array is the same as that of the levels, because it includes the loop time.

Notes

Cyclic envelopes use ugens internally thus they can only be used within a synthdef function.

circle(last_time=0.0, last_curve='lin')¶

Make the envelope cyclical.

Parameters

last_time (float | int) – Transition time from the end to the beginning of the evenlope.
last_curve (str) – Curvature of the transition from the end to the beginning of the evenlope.

property duration¶: Duration of the envelope as the sum of times.

total_duration()¶: Duration of the longest envelop (multichannel case).

property release_time¶: Duration of the release portion of the envelope.

property is_sustained¶: Return True if the envelope is sustained.

range(lo=0.0, hi=1.0)¶

Return a copy of the envelope with the levels mapped linearly.

Parameters

lo (float | int) – Lower value of the new range.
hi (float | int) – Maximum value of the new range.

exprange(lo=0.01, hi=1.0)¶

Return a copy of the envelope with the levels mapped exponentially.

Parameters

lo (float | int) – Lower value of the new range. Must be greater than 0.
hi (float | int) – Maximum value of the new range.

curverange(lo=0.0, hi=1.0, curve=- 4)¶

Return a copy of the envelope with the levels mapped to a curvature.

Parameters

lo (float | int) – Lower value of the new range.
hi (float | int) – Maximum value of the new range.
curve (float | int) – Curvature of the mapping.