undertone

Appearance

@liminal-hq/undertone / Pattern

Class: Pattern<T> ​

Defined in: pattern.ts:97

A pattern is a function from a timespan (in cycles) to the events overlapping it. Patterns are immutable: every combinator returns a new Pattern wrapping the old query, so a partially-built pattern is always safe to branch or reuse.

Type Parameters ​

T ​

T

Constructors ​

Constructor ​

new Pattern<T>(query): Pattern<T>

Defined in: pattern.ts:98

Parameters ​

query ​

(span) => Hap<T>[]

Returns ​

Pattern<T>

Properties ​

query ​

readonly query: (span) => Hap<T>[]

Defined in: pattern.ts:98

Parameters ​

span ​

TimeSpan

Returns ​

Hap<T>[]

Methods ​

attack() ​

attack(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:325

Amplitude envelope attack time, in seconds. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

bank() ​

bank(this, name): Pattern<ControlPatch>

Defined in: pattern.ts:267

Bank prefix for sample lookup — tried as ${name}_${sampleName} before falling back to bare sampleName.

Parameters ​

this ​

Pattern<ControlPatch>

name ​

string

Returns ​

Pattern<ControlPatch>

channels() ​

channels(this, gains): Pattern<ControlPatch>

Defined in: pattern.ts:677

Multichannel (up to 7.1) placement: per-speaker output gains in the order FL, FR, C, LFE, SL, SR, RL, RR (1-8 entries). Takes precedence over pan(). On destinations that can't address that many speakers (or without enableMultichannel()), the voice folds down to stereo automatically.

Parameters ​

this ​

Pattern<ControlPatch>

gains ​

number[]

Returns ​

Pattern<ControlPatch>

cut() ​

cut(this, group): Pattern<ControlPatch>

Defined in: pattern.ts:567

Cut group (Strudel/Tidal cut): a new event in the same group stops the previous one with a very short fade — a closed hi-hat choking an open one, or a monophonic line retriggering. The same number on different patterns shares one group. Not patternable, like orbit().

Parameters ​

this ​

Pattern<ControlPatch>

group ​

number

Returns ​

Pattern<ControlPatch>

decay() ​

decay(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:330

Amplitude envelope decay time, in seconds. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

delay() ​

delay(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:643

Delay send level (0-1) to this voice's orbit bus (see orbit()). No send at all when omitted. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

delayfeedback() ​

delayfeedback(this, amount): Pattern<ControlPatch>

Defined in: pattern.ts:653

Feedback (0-1) for the orbit's shared delay bus. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

amount ​

string | number

Returns ​

Pattern<ControlPatch>

delaytime() ​

delaytime(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:648

Delay time in seconds for the orbit's shared delay bus. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

duration() ​

duration(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:520

Explicit gate length in seconds: the envelopes hold at their sustain level for this long, then release — independent of the event's length in the pattern, and also in a one-shot play(). Needs a sustain above 0 to hold. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

early() ​

early(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:588

Moves every event seconds earlier — the negative of late()/nudge().

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

euclid() ​

euclid(pulses, steps, rotation?): Pattern<T>

Defined in: pattern.ts:177

Distributes the pattern over a euclidean rhythm: pulses onsets spread as evenly as possible across steps slots per cycle (Bjorklund's algorithm), optionally rotated left by rotation slots. The whole pattern is squeezed into each onset slot, which for single-value patterns matches Strudel's "x(3,8)" exactly.

Parameters ​

pulses ​

number

steps ​

number

rotation? ​

number = 0

Returns ​

Pattern<T>

every() ​

every(n, fn): Pattern<T>

Defined in: pattern.ts:156

Applies fn to the pattern on every nth cycle (cycles 0, n, 2n, ...).

Parameters ​

n ​

number

fn ​

(pat) => Pattern<T>

Returns ​

Pattern<T>

fast() ​

fast(factor): Pattern<T>

Defined in: pattern.ts:115

Speeds the pattern up: fast(2) squeezes two cycles into every one.

Parameters ​

factor ​

number

Returns ​

Pattern<T>

fm() ​

fm(this, index): Pattern<ControlPatch>

Defined in: pattern.ts:402

FM modulation index (Strudel's fm): the modulator swings the carrier's frequency by index × the modulator's frequency, so the sound is equally bright at every pitch. 0 turns it off. Synth voices only. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

index ​

string | number

Returns ​

Pattern<ControlPatch>

fmap() ​

fmap<U>(fn): Pattern<U>

Defined in: pattern.ts:101

Transforms every event value, keeping the pattern's structure.

Type Parameters ​

U ​

U

Parameters ​

fn ​

(value) => U

Returns ​

Pattern<U>

fmattack() ​

fmattack(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:433

Seconds for the FM depth to reach the full index. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

fmdecay() ​

fmdecay(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:438

Seconds for the FM depth to fall to fmsustain() × the index (toward silence when fmsustain() is unset). Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

fmenv() ​

fmenv(this, curve): Pattern<ControlPatch>

Defined in: pattern.ts:453

Ramp shape of the FM depth envelope: 'exp' (default, as in Strudel) or 'lin'. Not patternable.

Parameters ​

this ​

Pattern<ControlPatch>

curve ​

"lin" | "exp"

Returns ​

Pattern<ControlPatch>

fmh() ​

fmh(this, ratio): Pattern<ControlPatch>

Defined in: pattern.ts:422

FM harmonicity (Strudel's fmh): the modulator's frequency as a multiple of the carrier's. Whole numbers give harmonic tones; fractions such as 3.5 or 2.76 give bells and metal. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

ratio ​

string | number

Returns ​

Pattern<ControlPatch>

fmi() ​

fmi(this, index): Pattern<ControlPatch>

Defined in: pattern.ts:413

Alias of fm() under Strudel's fmi name.

Parameters ​

this ​

Pattern<ControlPatch>

index ​

string | number

Returns ​

Pattern<ControlPatch>

fmrelease() ​

fmrelease(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:448

Seconds for the FM depth to fall to 0 after the gate closes. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

fmsustain() ​

fmsustain(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:443

Fraction (0-1) of the index the FM depth settles to (default 1, or 0 when only fmdecay() is set). Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

fmwave() ​

fmwave(this, type): Pattern<ControlPatch>

Defined in: pattern.ts:461

The modulator's waveform: sine (default), triangle, square, sawtooth, or a shaped wave (halfsine, abssine, pulsesine). Not patternable.

Parameters ​

this ​

Pattern<ControlPatch>

type ​

OscType | ShapedWaveType

Returns ​

Pattern<ControlPatch>

gain() ​

gain(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:348

Peak amplitude (0-1). Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

hpf() ​

hpf(this, hz): Pattern<ControlPatch>

Defined in: pattern.ts:610

Static highpass cutoff in Hz, in series after lpf(). Creates a filter stage; omit entirely to skip it. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

hz ​

string | number

Returns ​

Pattern<ControlPatch>

jux() ​

jux(this, fn): Pattern<ControlPatch>

Defined in: pattern.ts:702

Juxtaposes the pattern with a transformed copy of itself: the original plays hard left, fn(pattern) plays hard right — e.g. pat.jux(rev).

Parameters ​

this ​

Pattern<ControlPatch>

fn ​

(pat) => Pattern<ControlPatch>

Returns ​

Pattern<ControlPatch>

late() ​

late(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:583

Delays every event by seconds — an alias of nudge() under Strudel's name.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

legato() ​

legato(this, fraction): Pattern<ControlPatch>

Defined in: pattern.ts:536

Gate length as a fraction of each event's own length (.legato(0.5) holds half of it, .legato(1) all of it). Gates even in a one-shot play(), and is overridden by an explicit duration(). Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

fraction ​

string | number

Returns ​

Pattern<ControlPatch>

loop() ​

loop(this, options?): LoopHandle

Defined in: pattern.ts:721

Loops the pattern until stop() is called on the returned handle.

Parameters ​

this ​

Pattern<ControlPatch>

options? ​

LoopOptions = {}

Returns ​

LoopHandle

lpa() ​

lpa(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:366

Filter envelope attack time, in seconds. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

lpd() ​

lpd(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:371

Filter envelope decay time, in seconds. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

lpenv() ​

lpenv(this, hzAmount): Pattern<ControlPatch>

Defined in: pattern.ts:361

Hz the filter envelope adds on top of lpf() at its peak. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

hzAmount ​

string | number

Returns ​

Pattern<ControlPatch>

lpf() ​

lpf(this, hz): Pattern<ControlPatch>

Defined in: pattern.ts:356

Base lowpass cutoff in Hz. Creates a filter stage; omit entirely to skip filtering. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

hz ​

string | number

Returns ​

Pattern<ControlPatch>

lpr() ​

lpr(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:384

Filter envelope release time, in seconds. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

lps() ​

lps(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:379

Fraction (0-1) between lpf() and its envelope peak the decay stage settles to. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

nudge() ​

nudge(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:578

Start-time offset in seconds applied to every event when played. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

orbit() ​

orbit(this, n): Pattern<ControlPatch>

Defined in: pattern.ts:664

Which shared effects bus (see effects.ts's getOrbitBus()) this voice's room()/delay() sends target. Default 0. Every voice sending to the same orbit shares one reverb and one delay line, so give a voice its own orbit number when it needs a distinct room size or delay time from its neighbours. Scalar only — not a mini-notation-patterned control.

Parameters ​

this ​

Pattern<ControlPatch>

n ​

number

Returns ​

Pattern<ControlPatch>

pan() ​

pan(this, position): Pattern<ControlPatch>

Defined in: pattern.ts:596

Stereo position, -1 (hard left) to 1 (hard right). Accepts a mini-notation string to pattern it; every literal in the string is range-checked.

Parameters ​

this ​

Pattern<ControlPatch>

position ​

string | number

Returns ​

Pattern<ControlPatch>

pattack() ​

pattack(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:481

Seconds the pitch envelope takes to reach its offset (default 0: it starts there). Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

pdecay() ​

pdecay(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:486

Seconds the pitch envelope takes to return to the note (default 0.1). Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

penv() ​

penv(this, semitones): Pattern<ControlPatch>

Defined in: pattern.ts:476

Pitch envelope depth in semitones (Strudel's penv): each note starts that far from its pitch (negative = below) and returns to it over pdecay(). Rising and falling sweeps alike. Synth voices only. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

semitones ​

string | number

Returns ​

Pattern<ControlPatch>

phaser() ​

phaser(this, rateHz): Pattern<ControlPatch>

Defined in: pattern.ts:618

LFO rate in Hz driving a 4-stage allpass phaser. Creates the phaser stage; omit entirely to skip it. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

rateHz ​

string | number

Returns ​

Pattern<ControlPatch>

pitchsteps() ​

pitchsteps(this, semitones, rateHz?): Pattern<ControlPatch>

Defined in: pattern.ts:497

A frame-stepped pitch curve: semitone offsets from each note, one per frame at rateHz (default 140, the frame rate of classic AdLib effects), holding the last offset. Falling and rising sweeps, wobbles and trills are all just arrays of numbers. Plain data, not patternable. Overrides penv() and slide().

Parameters ​

this ​

Pattern<ControlPatch>

semitones ​

readonly number[]

rateHz? ​

number

Returns ​

Pattern<ControlPatch>

play() ​

play(this, options?): PlaybackHandle

Defined in: pattern.ts:716

Plays one cycle's worth of events as a one-shot. Envelopes are percussive by default (0.1.x SFX behaviour) — pass { gated: true } to hold each event for its own share of the cycle instead, like loop(). Uses a lazily-created shared AudioContext when none is passed — call from a user gesture the first time (autoplay policy).

Parameters ​

this ​

Pattern<ControlPatch>

options? ​

PlayOptions = {}

Returns ​

PlaybackHandle

release() ​

release(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:343

Amplitude envelope release time, in seconds. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

render() ​

render(this, options?): Promise<RenderedAudioBufferLike>

Defined in: pattern.ts:730

Renders the pattern offline to an audio buffer, with no real-time clock and a seeded random source, so the same pattern gives the same samples on the same engine. Pass the result to encodeWav to write a file.

Parameters ​

this ​

Pattern<ControlPatch>

options? ​

RenderOptions = {}

Returns ​

Promise<RenderedAudioBufferLike>

rev() ​

rev(): Pattern<T>

Defined in: pattern.ts:139

Reverses each cycle in time (cycle-local mirror, the classic rev).

Returns ​

Pattern<T>

room() ​

room(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:626

Reverb send level (0-1) to this voice's orbit bus (see orbit()). No send at all when omitted. Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

roomsize() ​

roomsize(this, size): Pattern<ControlPatch>

Defined in: pattern.ts:635

Reverb decay character for the orbit's shared bus, roughly 1 (short) to 10 (long) — see effects.ts's getOrbitBus(). Accepts a mini-notation string.

Parameters ​

this ​

Pattern<ControlPatch>

size ​

string | number

Returns ​

Pattern<ControlPatch>

s() ​

s(this, name): Pattern<ControlPatch>

Defined in: pattern.ts:260

Sets the voice to a synth SoundType or a registered sample name — a synth type behaves exactly like sound(); anything else becomes a sample name (see samples.ts's registerSample()), clearing any previous sample name or synth type respectively so the two never both apply at once.

Parameters ​

this ​

Pattern<ControlPatch>

name ​

string

Returns ​

Pattern<ControlPatch>

scale() ​

scale(this, spec): Pattern<ControlPatch>

Defined in: pattern.ts:276

Resolves scale-degree events from n() into real pitches: spec is a scale string like "D5:minor". Events without a degree (already pitched via note(), or unpitched noise from sound()) pass through unchanged.

Parameters ​

this ​

Pattern<ControlPatch>

spec ​

string

Returns ​

Pattern<ControlPatch>

slide() ​

slide(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:392

Pitch glide (portamento): starts an octave above the target note and slides down. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

slow() ​

slow(factor): Pattern<T>

Defined in: pattern.ts:127

Slows the pattern down: slow(2) stretches one cycle over two.

Parameters ​

factor ​

number

Returns ​

Pattern<T>

sound() ​

sound(this, type): Pattern<ControlPatch>

Defined in: pattern.ts:250

Sets/overrides the oscillator waveform or noise type across all events, clearing any sample name set by .s() — sampleName otherwise takes precedence over soundType in the engine, so without this a prior .s() would keep playing its sample silently through a later .sound() call.

Parameters ​

this ​

Pattern<ControlPatch>

type ​

SoundType

Returns ​

Pattern<ControlPatch>

surround() ​

surround(this, angleDegrees): Pattern<ControlPatch>

Defined in: pattern.ts:694

Places the voice at an angle on the 7.1 speaker ring: 0° front-centre, ±30° front, ±90° sides, ±150° rears, ±180° dead-behind — equal-power panned between the two nearest speakers. Sugar for channels(surroundGains(angle)).

Parameters ​

this ​

Pattern<ControlPatch>

angleDegrees ​

number

Returns ​

Pattern<ControlPatch>

sustain() ​

sustain(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:338

Fraction (0-1) of gain the decay stage settles to before release. Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

velocity() ​

velocity(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:551

Note strength: multiplies the peak amplitude only, so one instrument keeps its timbre from a ghost note (0.3) to an accent (1). Accepts a mini-notation string to pattern it.

Parameters ​

this ​

Pattern<ControlPatch>

level ​

string | number

Returns ​

Pattern<ControlPatch>

voice() ​

voice(this, patch): Pattern<ControlPatch>

Defined in: pattern.ts:194

Applies a whole instrument at once: merges a plain ControlPatch (such as one from fmVoice() or fmPresets, or loaded from saved data) into every event. Fields the patch sets overwrite the events', so call it before the per-note controls you want to win — note('e5 g5').voice(bell).gain(0.2).

Parameters ​

this ​

Pattern<ControlPatch>

patch ​

ControlPatch

Returns ​

Pattern<ControlPatch>

voicing() ​

voicing(this, options?): Pattern<ControlPatch>

Defined in: pattern.ts:297

Expands chord-symbol events from chord() into simultaneous note events — one chord onset becomes N notes sharing the same whole/part, exactly the shape stack()ed chords already produce downstream (the scheduler/engine need no changes at all to play them). Events without a chord (already pitched via note()/n()) pass through unchanged.

Parameters ​

this ​

Pattern<ControlPatch>

options? ​
anchor? ​

string | number

Returns ​

Pattern<ControlPatch>