Skip to content

Pattern signals

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

SDK 1.53.0. Generated from the SDK source and its original JSDoc. See the API index for version and source provenance, or the SDK guide for a first composition.

The signal sources: Strudel’s continuous patterns, pat() and a constant.

export type SignalOp =
| "sine"
| "cosine"
| "saw"
| "isaw"
| "tri"
| "square"
| "rand"
| "perlin"
| "irand"
| "seq"
| "const"
| "self";

One transform, applied in order after the source.

export type SignalTransform =
| readonly ["range" | "rangex", number, number]
| readonly ["slow" | "fast" | "segment" | "early" | "late", number]
| readonly ["add" | "mul", number | PatternSignal]
| readonly ["every", number, readonly SignalTransform[]];

A continuous signal as data: a source (op and args) and transforms (xf). Random sources use DAWN’s versioned coordinate-and-seed hash; song() derives the seed from the track id and bakes automation points.

export declare class PatternSignal {
readonly op: SignalOp;
readonly args: readonly (number | string)[];
readonly xf: readonly SignalTransform[];
readonly kind: "signal";
constructor(
op: SignalOp,
args?: readonly (number | string)[],
xf?: readonly SignalTransform[],
);
private with;
/** Maps 0..1 onto `lo..hi`, as Strudel's `.range`. */
range(lo: number, hi: number): PatternSignal;
/** Maps 0..1 onto `lo..hi` exponentially (both > 0), as `.rangex`. */
rangex(lo: number, hi: number): PatternSignal;
/** `n` times slower: one period spans `n` bars. */
slow(n: number): PatternSignal;
/** `n` times faster. */
fast(n: number): PatternSignal;
/** Holds `n` values per bar, each sampled at its segment's start. */
segment(n: number): PatternSignal;
/** Adds a number or another signal. */
add(value: number | PatternSignal): PatternSignal;
/** Multiplies by a number or another signal. */
mul(value: number | PatternSignal): PatternSignal;
/** Shifts `bars` earlier in time. */
early(bars: number): PatternSignal;
/** Shifts `bars` later in time. */
late(bars: number): PatternSignal;
/**
* Applies `transform` on every `n`th bar, starting with the first, as
* Strudel's `every` (`firstOf`): `sine.every(4, (s) => s.fast(2))`.
*/
every(
n: number,
transform: (signal: PatternSignal) => PatternSignal,
): PatternSignal;
}

True for a PatternSignal, including one rebuilt from plain data.

export declare function isPatternSignal(value: unknown): value is PatternSignal;

A sine 0..1 starting at 0.5 and rising (Strudel sine).

export declare const sine: PatternSignal;

A cosine 0..1: sine a quarter bar early (Strudel cosine).

export declare const cosine: PatternSignal;

A ramp 0..1 each bar (Strudel saw).

export declare const saw: PatternSignal;

A falling ramp 1..0 each bar (Strudel isaw).

export declare const isaw: PatternSignal;

A triangle 0..1..0 each bar (Strudel tri).

export declare const tri: PatternSignal;

0 for the first half of each bar, 1 for the second (Strudel square).

export declare const square: PatternSignal;

DAWN random mapping v2 (SDK 1.48.0): a stateless value in [0,1) keyed by finite cycle and seed, independently; -0 and 0 share a key. There is no fixed cycle period. Re-evaluating older random signals changes their automation; previously baked score points remain unchanged.

export declare const rand: PatternSignal;

Smooth value noise in [0,1): quintic interpolation between rand values at adjacent integer cycles. Endpoints agree with rand for the same seed; both lattice coordinates must be safe integers. SDK 1.48.0 mapping.

export declare const perlin: PatternSignal;

Seeded whole numbers 0..n-1: trunc(rand * n), DAWN mapping v2.

export declare function irand(n: number): PatternSignal;

Numbers in mini-notation, one bar per cycle: pat("0 0.5 1") steps through three values a bar; [a b] subdivides a step, <a b> takes one per bar, x*2 repeats inside its step and x!2 adds steps.

export declare function pat(text: string): PatternSignal;

A constant signal.

export declare function steady(value: number): PatternSignal;

A signal’s value at cycle (bars from the song start). Random sources hash the finite cycle and seed as independent keys (DAWN mapping v2); signalSeed(trackId) is the seed song() uses.

export declare function signalAt(
signal: PatternSignal,
cycle: number,
seed?: number,
): number;

The stable unsigned 32-bit seed of a track id (DAWN mapping v2).

export declare function signalSeed(trackId: string): number;

Automation points for a signal over a song: [tick, value] sampled on a grid of at most 16 points a bar and 256 in all. Ramping signals keep one point per sample (automation ramps between them); stepping signals hold each value until one tick before the next.

export declare function bakeSignal(
signal: PatternSignal,
options: Readonly<{
bars: number;
ticksPerBar: number;
seed: number;
map?: (value: number) => number;
}>,
): readonly Readonly<{
tick: number;
value: number;
}>[];

The lowest and highest values a signal takes over its first 16 bars, sampled 64 times a bar; patches size a signal’s hidden macro from it.

export declare function signalBounds(
signal: PatternSignal,
seed?: number,
): readonly [number, number];

Rebuilds a signal from its plain data ({ kind: "signal", op, args, xf }), checking every field.

export declare function signalFromData(
input: unknown,
depth?: number,
): PatternSignal;

Documentation drafted with AI and checked against the product source.