undertone

Appearance

@liminal-hq/undertone / Pattern

Class: Pattern<T> ​

Defined in: pattern.ts:83

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:84

Parameters ​

query ​

(span) => Hap<T>[]

Returns ​

Pattern<T>

Properties ​

query ​

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

Defined in: pattern.ts:84

Parameters ​

span ​

TimeSpan

Returns ​

Hap<T>[]

Methods ​

attack() ​

attack(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:301

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:243

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:475

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>

decay() ​

decay(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:306

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:441

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:451

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:446

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>

early() ​

early(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:386

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:163

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:142

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:101

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

Parameters ​

factor ​

number

Returns ​

Pattern<T>

fmap() ​

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

Defined in: pattern.ts:87

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

Type Parameters ​

U ​

U

Parameters ​

fn ​

(value) => U

Returns ​

Pattern<U>

gain() ​

gain(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:324

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:408

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:500

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:381

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

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

loop() ​

loop(this, options?): LoopHandle

Defined in: pattern.ts:519

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:342

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:347

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:337

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:332

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:360

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:355

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:376

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:462

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:394

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>

phaser() ​

phaser(this, rateHz): Pattern<ControlPatch>

Defined in: pattern.ts:416

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>

play() ​

play(this, options?): void

Defined in: pattern.ts:514

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 ​

void

release() ​

release(this, seconds): Pattern<ControlPatch>

Defined in: pattern.ts:319

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

Parameters ​

this ​

Pattern<ControlPatch>

seconds ​

string | number

Returns ​

Pattern<ControlPatch>

rev() ​

rev(): Pattern<T>

Defined in: pattern.ts:125

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

Returns ​

Pattern<T>

room() ​

room(this, level): Pattern<ControlPatch>

Defined in: pattern.ts:424

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:433

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:236

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:252

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:368

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:113

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:226

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:492

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:314

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>

voicing() ​

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

Defined in: pattern.ts:273

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>