API reference

Every public helper, the functions fn() accepts, and how playback behaves. Tables are generated from the package, and “Used in” links to pages that call each function.

  • react-strudel-kit
  • react-strudel-kit/react

Entrypoints

ImportContents
react-strudel-kitfn, chain, pattern, patternCallback, the registry, Mini-Notation helpers, validation, serializers and types. Builds patterns without audio.
react-strudel-kit/reactuseStrudel and its types. Browser-only; uses the Strudel browser bundle.

Composing patterns

HelperWhat it does
fn(name, …args)Creates a factory (a new pattern) or a modifier (a setting). Names and argument types are checked against the registry below.
chain(pattern, …modifiers)Returns a new pattern with modifiers appended. The original is not changed, so a part can be reused with different settings.
pattern(root, modifiers?)Builds an expression from a factory call and modifiers.
patternCallback(…modifiers)A callback for off, every and friends, applied to the implicit pattern x. Serializable data, not a JavaScript function.

See them in use: Your first song and the Lead page for callbacks.

Factories

A factory starts a pattern. Use it first in chain, or as an argument to stack and cat.

NameStrudelArgumentsWhat it doesUsed in
samplesMini-NotationPlays sound names: a sample, a synth wave or noise.Drums, Tonal sounds, Four on the floor, Backbeat, Hi-hat accents, Lo-fi loop, House loop, Dance Monkey
soundsoundMini-NotationSame as sample.—
notenoteMini-NotationPlays pitches.Installation, Your first song, Drums, Tonal sounds, A simple melody, Four on the floor, Backbeat, Bass line, Chords and arpeggios, Layer a song, Lo-fi loop, House loop, Dance Monkey
nnnumber | Mini-NotationPlays note numbers.—
stackstackpattern, …patternsPlays patterns at the same time.Make a beat, Add a bass line, Layer the parts, Learn: Control it with React, Drums, Tonal sounds, Four on the floor, Backbeat, Bass line, Chords and arpeggios, Layer a song, Control it with React, Lo-fi loop, House loop, Dance Monkey
layerstackpattern, …patternsSame as stack.—
sequenceseqpattern, …patternsPlays patterns one after another within a cycle.—
catcatpattern, …patternsPlays one pattern per cycle.Tonal sounds, A simple melody, Bass line, Chords and arpeggios, Layer a song, Lo-fi loop, House loop, Dance Monkey
silencesilence—Plays nothing.Learn: Control it with React, Control it with React

Modifiers

A modifier changes a pattern and goes after the factory in chain. “Numeric” accepts a number, a validated Mini-Notation string, or a typed Mini-Notation node, so most settings can be patterns too.

NameStrudelArgumentsWhat it doesUsed in
instrumentsMini-NotationSets the sound of a note pattern.Installation, Your first song, Drums, Tonal sounds, A simple melody, Lo-fi loop, Dance Monkey
attackattacknumericFade-in time, seconds.Tonal sounds, Lo-fi loop, Dance Monkey
decaydecaynumericTime to fall to the sustain level, seconds.Drums, Tonal sounds, Dance Monkey
sustainsustainnumericLevel held while a note lasts, 0–1.Drums, Tonal sounds, Dance Monkey
releasereleasenumericFade-out time after a note ends, seconds.Drums, Tonal sounds, Lo-fi loop, Dance Monkey
pitchEnvelopepenvnumericStart pitch above the note, semitones.Drums, Dance Monkey
pitchDecaypdecaynumericTime for that pitch to fall back, seconds.Drums, Dance Monkey
postGainpostgainnumericOutput level after effects; keeps each gain.Layer the parts, Layer a song, Lo-fi loop, House loop, Dance Monkey
cpmcpmnumberCycles per minute. BPM ÷ 4 for one 4/4 bar per cycle.Installation, Your first song, Make a beat, Add a bass line, Layer the parts, Learn: Control it with React, Drums, Tonal sounds, A simple melody, Four on the floor, Backbeat, Hi-hat accents, Bass line, Chords and arpeggios, Layer a song, Control it with React, Lo-fi loop, House loop, Dance Monkey
gaingainnumericLoudness.Installation, Your first song, Drums, Tonal sounds, A simple melody, Dance Monkey
velocityvelocitynumericScales gain per event, 0–1.Make a beat, Add a bass line, Layer the parts, Drums, Tonal sounds, Hi-hat accents, Layer a song, Lo-fi loop, House loop
panpannumericStereo position: 0 left, 0.5 centre, 1 right.Dance Monkey
orbitorbitnumericEffect bus number.—
lowPasslpfnumericRemoves frequencies above the cutoff, Hz.Drums, Tonal sounds, Dance Monkey
highPasshpfnumericRemoves frequencies below the cutoff, Hz.Drums, Dance Monkey
roomroomnumericReverb amount, 0–1.Tonal sounds, Dance Monkey
sizesizenumericReverb room size, 0–1.Tonal sounds
fastfastnumericSpeeds the pattern up by a factor.—
slowslownumericSlows the pattern down by a factor.—
clipclipnumericNote length as a share of its slot.Tonal sounds, Dance Monkey
compresscompressnumeric, numericSqueezes the pattern into a span of the cycle.—
earlyearlynumericShifts earlier, cycles.—
latelatenumericShifts later, cycles.—
swingswingnumericSwings by subdivision.—
swingByswingBynumeric, numericDelays every second subdivision: amount, subdivisions.Lo-fi loop
revrev—Reverses each cycle.—
degradedegrade—Randomly drops events.—
undegradeundegrade—Keeps the events degrade would drop.—
everyeverycycles, callbackApplies a callback every n cycles.—
firstOffirstOfcycles, callbackApplies a callback on the first of every n cycles.—
lastOflastOfcycles, callbackApplies a callback on the last of every n cycles.—
sometimessometimescallbackApplies a callback to about half the events.—
oftenoftencallbackApplies a callback to most events.—
rarelyrarelycallbackApplies a callback to a few events.—
sometimesBysometimesBynumeric, callbackApplies a callback with a probability.—
insideinsidenumeric, callbackApplies a callback inside subdivided cycles.—
outsideoutsidenumeric, callbackApplies a callback across enlarged cycles.—
offoffnumeric, callbackAdds a time-shifted, transformed copy.Tonal sounds, House loop
whenwhenMini-Notation, callbackApplies a callback while a condition is true.—

Mini-Notation helpers

These build typed Mini-Notation that goes inside a factory, such as fn('note', …). The right-hand column is the notation each one produces.

CallWhat it doesProduces
pitch('c4')A note name with octave. Typed: a typo is a compile error.c4
sample('white')A sound name.white
number(0.5)A number, for control patterns such as velocity.0.5
rest()A silent slot.~
sequence(pitch('c4'), rest())Splits a slot equally between its entries.c4 ~
stack(pitch('c4'), pitch('e4'))Plays entries at once: a chord.c4, e4
weight(pitch('c4'), 2)Gives an entry more shares of its sequence.c4@2
repeat(pitch('c4'), 2)Fits several strikes into one slot.c4*2
fast(sequence(…), 2)Plays a slot’s content faster.[c4 e4]*2
slow(sequence(…), 2)Stretches content over more cycles.[c4 e4]/2
choice(pitch('c4'), pitch('e4'))Picks one entry at random each cycle.c4 | e4
subcycle(sequence(…))Groups entries into one slot.[c4 e4]
polymeter(…)Lanes with different step counts.{c4 e4, g4 b4 d5}
degrade(pitch('c4'), 0.3)Drops the entry with a probability.c4?0.3
raw('c4 [e4 g4]')Unchecked Mini-Notation. An escape hatch.c4 [e4 g4]

Validation and output

FunctionWhat it does
mini(code)Checks Mini-Notation syntax with Strudel’s parser and returns it typed. Throws on invalid syntax.
isMiniNotation(code)The same check as a type guard that returns a boolean.
assertMiniNotation(code)The same check as an assertion function.
toMiniNotation(node)Turns a typed Mini-Notation node into its string.
toStrudelCode(input)Turns a pattern into Strudel code — what every “Strudel output” tab on this site shows. Code strings pass through.

useStrudel

useStrudel() takes no arguments. Every component that calls it shares one transport; no provider is needed.

MemberBehavior
play(input)Starts playback of a code string, a pattern from this package, or a native Strudel pattern. Call it from a click or key press so the browser allows audio. A newer call replaces an older pending one.
update(input)Replaces the running pattern without restarting. Does nothing while stopped. Takes effect in the next scheduling window, not on a bar line.
stop()Stops playback, cancels pending requests and clears the error.
status'idle', 'playing' or 'error'. idle also covers start-up.
errorA StrudelError or null. Playback failures appear here rather than being thrown.

When the last component using the hook unmounts, playback stops. Control it with React shows the full pattern.

Errors

codeMeaning
initializationStrudel could not start. Press Play again to retry.
evaluationA pattern could not be serialized or the code failed to evaluate.
transportResuming audio, preparing a native pattern, starting or stopping failed.
unknownReserved fallback.

Each error has a message and an optional original cause.

Limits

  • Types cover the functions listed here, not all of Strudel. raw() and code strings are not checked.
  • mini() checks syntax only. It cannot tell whether a sample exists or a value makes musical sense.
  • Sample banks are not loaded. Every sound on this site uses built-in synths and noise; see the Strudel sample guide to load your own.
  • Changing cpm with update() rescales against the running clock, so the phrase position can move.
  • Pinned to @strudel/web 1.3.0. See docs/usage.md for the compatibility table.