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.
Entrypoints
| Import | Contents |
|---|---|
react-strudel-kit | fn, chain, pattern, patternCallback, the registry, Mini-Notation helpers, validation, serializers and types. Builds patterns without audio. |
react-strudel-kit/react | useStrudel and its types. Browser-only; uses the Strudel browser bundle. |
Composing patterns
| Helper | What 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.
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.
| Name | Strudel | Arguments | What it does | Used in |
|---|---|---|---|---|
instrument | s | Mini-Notation | Sets the sound of a note pattern. | Installation, Your first song, Drums, Tonal sounds, A simple melody, Lo-fi loop, Dance Monkey |
attack | attack | numeric | Fade-in time, seconds. | Tonal sounds, Lo-fi loop, Dance Monkey |
decay | decay | numeric | Time to fall to the sustain level, seconds. | Drums, Tonal sounds, Dance Monkey |
sustain | sustain | numeric | Level held while a note lasts, 0–1. | Drums, Tonal sounds, Dance Monkey |
release | release | numeric | Fade-out time after a note ends, seconds. | Drums, Tonal sounds, Lo-fi loop, Dance Monkey |
pitchEnvelope | penv | numeric | Start pitch above the note, semitones. | Drums, Dance Monkey |
pitchDecay | pdecay | numeric | Time for that pitch to fall back, seconds. | Drums, Dance Monkey |
postGain | postgain | numeric | Output level after effects; keeps each gain. | Layer the parts, Layer a song, Lo-fi loop, House loop, Dance Monkey |
cpm | cpm | number | Cycles 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 |
gain | gain | numeric | Loudness. | Installation, Your first song, Drums, Tonal sounds, A simple melody, Dance Monkey |
velocity | velocity | numeric | Scales 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 |
pan | pan | numeric | Stereo position: 0 left, 0.5 centre, 1 right. | Dance Monkey |
orbit | orbit | numeric | Effect bus number. | — |
lowPass | lpf | numeric | Removes frequencies above the cutoff, Hz. | Drums, Tonal sounds, Dance Monkey |
highPass | hpf | numeric | Removes frequencies below the cutoff, Hz. | Drums, Dance Monkey |
room | room | numeric | Reverb amount, 0–1. | Tonal sounds, Dance Monkey |
size | size | numeric | Reverb room size, 0–1. | Tonal sounds |
fast | fast | numeric | Speeds the pattern up by a factor. | — |
slow | slow | numeric | Slows the pattern down by a factor. | — |
clip | clip | numeric | Note length as a share of its slot. | Tonal sounds, Dance Monkey |
compress | compress | numeric, numeric | Squeezes the pattern into a span of the cycle. | — |
early | early | numeric | Shifts earlier, cycles. | — |
late | late | numeric | Shifts later, cycles. | — |
swing | swing | numeric | Swings by subdivision. | — |
swingBy | swingBy | numeric, numeric | Delays every second subdivision: amount, subdivisions. | Lo-fi loop |
rev | rev | — | Reverses each cycle. | — |
degrade | degrade | — | Randomly drops events. | — |
undegrade | undegrade | — | Keeps the events degrade would drop. | — |
every | every | cycles, callback | Applies a callback every n cycles. | — |
firstOf | firstOf | cycles, callback | Applies a callback on the first of every n cycles. | — |
lastOf | lastOf | cycles, callback | Applies a callback on the last of every n cycles. | — |
sometimes | sometimes | callback | Applies a callback to about half the events. | — |
often | often | callback | Applies a callback to most events. | — |
rarely | rarely | callback | Applies a callback to a few events. | — |
sometimesBy | sometimesBy | numeric, callback | Applies a callback with a probability. | — |
inside | inside | numeric, callback | Applies a callback inside subdivided cycles. | — |
outside | outside | numeric, callback | Applies a callback across enlarged cycles. | — |
off | off | numeric, callback | Adds a time-shifted, transformed copy. | Tonal sounds, House loop |
when | when | Mini-Notation, callback | Applies 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.
| Call | What it does | Produces |
|---|---|---|
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
| Function | What 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.
| Member | Behavior |
|---|---|
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. |
error | A 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
| code | Meaning |
|---|---|
initialization | Strudel could not start. Press Play again to retry. |
evaluation | A pattern could not be serialized or the code failed to evaluate. |
transport | Resuming audio, preparing a native pattern, starting or stopping failed. |
unknown | Reserved 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
cpmwithupdate()rescales against the running clock, so the phrase position can move. - Pinned to
@strudel/web1.3.0. Seedocs/usage.mdfor the compatibility table.