Envelopes

nanosynth.envelopes

Envelope class and EnvGen UGen for nanosynth.

Ported from supriya's ugens/envelopes.py.

Envelope

Bases: UGenSerializable

An envelope specification for use with EnvGen.

Defines an amplitude envelope as a sequence of breakpoints with configurable interpolation curves. Used to shape the amplitude, frequency, or any other parameter of a synth over time.

Args: amplitudes: Breakpoint values. Must have at least 2 elements. The first element is the initial value; subsequent elements are target values for each segment. durations: Duration of each segment in seconds. Length must be len(amplitudes) - 1. curves: Interpolation shape per segment. Can be EnvelopeShape values, numeric curvature floats (positive = slow start, negative = fast start), or shape name strings. Cycled if shorter than the number of segments. release_node: Index of the sustain node. When EnvGen receives a gate-off (gate=0), the envelope jumps from this node to the next, enabling sustain behavior (used by adsr, asr). loop_node: Index of the loop-back node (for looping envelopes). offset: Time offset applied to the envelope start.

Factory methods adsr, asr, linen, percussive, and triangle create common envelope shapes without manual breakpoint specification.

adsr classmethod

adsr(
    attack_time: float = 0.01,
    decay_time: float = 0.3,
    sustain: float = 0.5,
    release_time: float = 1.0,
    peak: float = 1.0,
    curve: float = -4.0,
    bias: float = 0.0,
) -> Envelope

Attack-Decay-Sustain-Release envelope.

Rises from 0 to peak over attack_time, decays to peak * sustain over decay_time, holds at sustain until gate-off, then releases to 0 over release_time. Requires EnvGen with a gate parameter for sustain/release behavior.

asr classmethod

asr(
    attack_time: float = 0.01,
    sustain: float = 1.0,
    release_time: float = 1.0,
    curve: float = -4.0,
) -> Envelope

Attack-Sustain-Release envelope.

Rises from 0 to sustain over attack_time, holds until gate-off, then releases to 0 over release_time.

linen classmethod

linen(
    attack_time: float = 0.01,
    sustain_time: float = 1.0,
    release_time: float = 1.0,
    level: float = 1.0,
    curve: float | int = 1,
) -> Envelope

Linear envelope with fixed sustain duration.

Rises from 0 to level over attack_time, holds at level for sustain_time, then falls to 0 over release_time. Unlike adsr/asr, this is not gate-controlled -- the total duration is fixed.

percussive classmethod

percussive(
    attack_time: UGenOperable | float = 0.01,
    release_time: UGenOperable | float = 1.0,
    amplitude: UGenOperable | float = 1.0,
    curve: EnvelopeShape
    | UGenOperable
    | float
    | str = -4.0,
) -> Envelope

Percussive (attack-release) envelope with no sustain.

Rises from 0 to amplitude over attack_time, then immediately decays to 0 over release_time. Commonly used with DoneAction.FREE_SYNTH to auto-free the synth when done.

triangle classmethod

triangle(
    duration: float = 1.0, amplitude: float = 1.0
) -> Envelope

Symmetric triangular envelope.

Rises linearly from 0 to amplitude over duration / 2, then falls linearly back to 0.

serialize

serialize() -> UGenVector

Serialize envelope for UGen graph wiring.

Returns a UGenVector containing the envelope specification in SuperCollider's wire format: [initial_amplitude, num_segments, release_node, loop_node, (amplitude, duration, shape, curve)...].

Inputs may be OutputProxy references when envelope parameters are driven by other UGens.

compile

compile() -> tuple[float, ...]

Compile envelope to SCgf-compatible float sequence.

Returns the same values as serialize() but as plain floats, without wrapping in UGenVector/ConstantProxy. Only works when all envelope parameters are numeric (not UGen outputs).

Raises: TypeError: If any parameter is a UGen (cannot flatten to float).

EnvGen

Bases: UGen

Envelope generator UGen.

Plays back an Envelope specification as a control or audio signal. Commonly used to shape amplitude, filter cutoff, or any time-varying parameter.

Args: gate: Gate signal. For envelopes with a release_node (e.g. adsr, asr), the envelope sustains while gate > 0 and releases when gate transitions to 0. For fixed envelopes (linen, percussive), gate is typically left at 1. level_scale: Scales the envelope output. level_bias: Offset added to the envelope output. time_scale: Scales all segment durations. done_action: Action to take when the envelope finishes (see DoneAction). DoneAction.FREE_SYNTH is the most common. envelope: An Envelope instance. Serialized automatically.