USER GUIDE
── PATTERN LANGUAGE & SYNTHESIS REFERENCE ──
QUICK START
  1. Press [ EXEC ] to start the clock
  2. Type a pattern in any row — e.g. bd sn hh sn
  3. Press Ctrl + Enter to evaluate it live
  4. Add more rows with + NEW ROW
  5. Adjust BPM with the slider — changes take effect immediately
TIP: You can evaluate a pattern while the clock is running. The change takes effect at the next cycle boundary.

PATTERN SYNTAX
SyntaxMeaningExample
a b c Sequence — items share the cycle equally bd sn hh sn
[ a b ] Group — subdivides one time slot [bd bd] sn
a*n Repeat — fires n times within its slot hh*8
a/n Slow — plays only every n cycles cy/4
a(k,n) Euclidean — k hits spread across n steps bd(3,8)
~ Rest — silence for that time slot bd ~ sn ~

Syntax can be combined freely. Nesting is supported:

ex. [[bd sn] hh] cp ~ cp -- nested group + rest
ex. bd*2 [sn oh] hh(3,8) -- repeat + group + euclidean
ex. bell/2 ~ lead ~ bell/2 -- bell plays every 2nd cycle
EUCLIDEAN RHYTHMS: bd(3,8) spreads 3 hits as evenly as possible across 8 steps — the same algorithm that generates the clave, tresillo, and other rhythms found in world music.

INSTRUMENTS

All sounds are synthesised from scratch using FM (frequency modulation) synthesis — no samples.

Name(s)SoundFM Character
bd   kick Kick drum Pitch envelope 160→42 Hz, high mod index
sn   snare Snare drum FM body + noise burst
hh   hat Closed hihat √2 ratio (inharmonic) → metallic
oh Open hihat Same as hh, longer release
cp   clap Clap 3 staggered FM bursts + noise
cy   ride Cymbal / ride √2 ratio, long FM index decay
tom Tom Pitch envelope 140→80 Hz
bell FM bell 3.5:1 ratio — the DX7 algorithm
bass FM bass 0.5:1 ratio, sub-heavy
lead FM lead 2:1 ratio, bright attack
pad FM pad Dual detuned operators, slow attack
c d e f g a b Note names FM tone at pitch, octave optional
NOTE NAMES: Use c, e4, g#3, bb5 etc. Default octave is 4. Sharps = #, flats = b.

EXAMPLE SESSIONS

Basic drum machine:

d1bd ~ ~ sn ~ ~ bd sn-- kick/snare
d2hh*8-- 8th-note hats
d3cp/2-- clap every 2nd cycle

Polyrhythmic:

d1bd(3,8)-- 3 over 8
d2sn(2,8)-- 2 over 8
d3hh(5,8)-- 5 over 8

Melodic:

d1bd ~ sn ~
d2bell(3,8)
d3c4 ~ e4 g4 ~ a4 ~ g4
d4bass/2

Dense / layered:

d1[bd bd] ~ sn ~
d2hh*4 oh hh*2 oh
d3cp(2,8)
d4pad/4
d5c3 ~ ~ e3 ~ g3 ~ ~

GLOBAL SETTINGS

The settings bar below the header controls global parameters for all patterns. Changes are staged (held in reserve) until you press [ SHIP ].

ControlDescription
KEY Root note for scale quantization. Click to cycle through all 12 chromatic roots (C → C# → D … → B).
SCALE Scale mode. Click to cycle: Major, Minor, Dorian, Phrygian, Lydian, Mixolydian, Locrian, Pentatonic, Diminished, Whole Tone, and more. Note names are snapped to the nearest in-scale degree.
BEATS Beats per cycle — 2, 4, 8, or 16. Controls how many steps a cycle is divided into. 4 = common time, 8 = double-time feel.
VOL Master volume (0–100%). Staged — takes effect on SHIP.
SWING Swing percentage (0–50%). Delays every off-beat 8th note. 0% = straight, 33% = triplet feel, 50% = maximum shuffle. Also adjustable by dragging the canvas centre zone.
REVERB Synthetic reverb mix (0–100%). Uses an exponentially-decaying noise impulse response — no external files.
SWAP Quantisation boundary for thread swaps (1, 2, 4, 8, or 16 cycles). When you evaluate a new pattern while playing, the change queues until the next multiple of this value. See Staged Parameters below.

STAGED PARAMETERS & SHIP

Tidal Waves separates editing from applying. This lets you dial in a complete new state — new key, new scale, adjusted volumes — and then cut to it at exactly the right moment.

  • Move any slider or click any setting → it turns bright white and pulses. The change is staged (queued), not yet live.
  • Press [ SHIP ] to commit all staged changes simultaneously — they all go live in one atomic cut.
  • The SHIP button shows a count of how many parameters are pending: [ SHIP 3 ].
  • Right-click anywhere on the canvas wheel to SHIP from anywhere on screen.
  • Stage mode EXEC/HALT/SHIP buttons are full mirrors — no need to exit stage to ship.
THREAD SWAPPING: Evaluating a pattern while playing queues it to swap at the next cycle boundary (controlled by the SWAP setting). The row label shows ▶4 counting down. When the swap fires, the active indicator flashes.

PER-PATTERN CONTROLS

Each pattern row has an expandable control panel. Click [ CTRL ] on any row to open it.

ControlDescription
GAIN Per-pattern volume (0–100%). Independent of the master VOL. Staged — requires SHIP to apply. The readout shows the live value; if pending, it shows ← 75% (the current live value) beside the staged value.
CHANCE Probability gate (0–100%). At 80%, each event has a 20% chance of being silenced. At 100%, every event fires. Creates live rhythmic variation without editing the pattern.
GAIN vs # gain: The CTRL panel GAIN applies to the whole pattern and goes through the SHIP workflow. The inline # gain 0.5 param applies per-event and takes effect immediately on the next evaluate.

PRESETS (SUBSTRATES)

Press [ PRE ] to open the substrate selector — 12 pre-composed algorithmic patterns ready to play. Each substrate loads a full configuration: BPM, key, scale, swing, reverb, and up to 5 pattern rows. After loading, all patterns are fully editable.

SubstrateCharacter
NEURAL DRIFT76 BPM · A dorian · Heavy reverb · Evolving bell lines
GRID RUNNER134 BPM · C minor · Straight · Fast industrial grid
GHOST PROTOCOL112 BPM · D phrygian · Swing 22% · 8 beats · Polyrhythmic
NEON RAIN100 BPM · D minor · Euclidean kick/snare · Melodic pad
FLATLINE95 BPM · G pentatonic · Swing 38% · Sparse groove
DATA CASCADE122 BPM · F mixolydian · Heavy Euclidean polyrhythm
SECTOR ZERO70 BPM · B locrian · Reverb 58% · Dark ambient pulse
PHOSPHOR BLOOM88 BPM · E lydian · 8 beats · Reverb 80% · Ethereal bell
CHROME RITUAL84 BPM · C whole-tone · Reverb 72% · Ritualistic layers
SUBTERRANEAN92 BPM · A diminished · Swing 16% · Deep sub textures
UPLINK128 BPM · G dorian · Hard techno grid · No reverb
DEAD CHANNEL60 BPM · E phrygian · Reverb 90% · Sparse decay
USE PRESETS AS STARTING POINTS: Load a substrate, press EXEC, then start modifying patterns with Ctrl+Enter. The preset is just a jump-off — the machine responds to you from there.

INLINE PARAMETERS

Append # key val to any pattern to control per-event synthesis parameters. Multiple values cycle across events. Multiple params chain with additional # separators.

ParameterRangeEffect
# gain 0.50 – 2Amplitude multiplier for this pattern
# pitch 1.50.1 – 4Frequency multiplier (1 = normal, 2 = octave up)
# pan -0.5-1 – 1Stereo position (-1 = left, 0 = centre, 1 = right)
# decay 0.50.01 – 4Duration multiplier (shorter/longer notes)
# index 20 – 8FM modulation index multiplier (brightness/timbre)
ex. bd sn # gain 0.4 -- quieter pattern
ex. bell*4 # pitch 1 1.5 2 1.5 -- cycling pitch values
ex. hh*8 # pan -0.8 0.8 # gain 0.6 1 -- panned + alternating gain
ex. c4 e4 g4 # decay 0.25 -- staccato notes
CYCLING: # pitch 1 1.5 2 — event 1 gets 1, event 2 gets 1.5, event 3 gets 2, event 4 wraps back to 1. Works with any number of values.

EVOLUTION OPERATORS

Append ~op (or ~op value) after the pattern to make it evolve automatically over cycles. The pattern lives — it changes itself while you watch.

OperatorEffect
~drift Rotates the pattern by 1 step each cycle (events shift position over time)
~mut 0.1 Each event has N% chance of being silenced or swapped each cycle. Default 10%.
~rev Reverses the pattern direction every 4 cycles (or every N cycles if specified)
~alt Alternates between forward and reversed on odd/even cycles
~mk Markov chain: rewrites the sequence each cycle using token bigram probabilities. Optional arg (0–1) controls randomness.
ex. bd sn hh ~drift -- pattern rotates each cycle
ex. hh*8 ~mut 0.15 -- 15% random variation
ex. c4 e4 g4 b4 ~rev 8 -- reverses every 8 cycles
ex. bd(3,8) ~drift # gain 0.8 -- combine with inline params
COMBINE: Evolution operators work alongside # params. Put ~ops before the # section, or after the pattern before the #.

EFFECTS CHAIN

Three global effects are available in the settings bar, all built using Web Audio API — no plugins, no libraries.

EffectControlDescription
DLY Toggle + wet % Stereo delay with feedback. Slider controls wet mix (how loud the echo is).
FLT Toggle + cutoff Hz Resonant lowpass filter. Slider sweeps cutoff from 200 Hz to 18 kHz.
DST Toggle + drive % Waveshaper distortion. Slider controls both drive amount and wet level.
CHAIN ORDER: Signal flows Distortion → Filter → Delay → Reverb → Output. All three effects can be active simultaneously.

STAGE MODE

Press S (or [ STG ]) to switch to full-screen performance view. The code editor disappears. The cycle wheel fills the screen.

  • A minimal HUD shows the BPM large, plus EXEC / HALT / SHIP controls
  • An oscilloscope waveform strip runs along the bottom of the screen
  • A spectrum analyser fills the centre hub of the wheel
  • Press S or Escape to return to Studio mode

DRAW MODE

Press [ DRAW ] to enter Draw mode — the cycle wheel becomes an instrument you can edit directly.

  • Click empty ring position → adds an event at that beat
  • Click existing dot → removes the event
  • Drag a dot → moves the event to a new beat position
  • Changes immediately update the pattern textarea and the live audio
  • Added events snap to a 1/16th beat grid automatically
TWO VIEWS: The textarea and the canvas wheel are both views of the same pattern. Edit in either place — they stay in sync.

KEYBOARD SHORTCUTS
Ctrl + Enter Evaluate the focused pattern row
S Toggle Stage mode (full-screen visualizer)
Escape Exit Stage mode
Scroll wheel on canvas Adjust BPM ±1
Drag canvas centre Adjust swing (0–50%)
Right-click canvas SHIP pending changes
Click ring on canvas Select that pattern row

HOW IT WORKS
  • Patterns are parsed into events with a position (0–1) and duration within each cycle
  • A lookahead scheduler fires audio ~100ms ahead of time using the Web Audio clock — this prevents jank
  • All audio is synthesised using FM synthesis: a modulator oscillator drives the frequency of a carrier oscillator
  • The modulation index (depth) decays over time, shaping the timbre from bright attack to pure tone
  • Inline # params are resolved per-event using cyclic indexing — no changes to the parser or scheduler
  • Evolution operators mutate the working pattern string each cycle boundary, before it hits the scheduler
  • Effects are vanilla Web Audio nodes (DelayNode, BiquadFilterNode, WaveShaperNode) — zero dependencies
  • The cycle wheel shows all active patterns as concentric rings — the playhead sweeps all of them simultaneously
  • Draw mode reconstructs a beat-quantized pattern string from canvas position, feeding it back to the textarea
  • No files, no samples, no network requests after initial load — everything runs in the browser

INLINE PARAMETERS — EXTENDED

Additional # parameters added to the synthesis engine:

ParameterRangeEffect
# index 20 – 8FM modulation index multiplier (1 = default, 2 = double brightness, 0 = pure tone)
ex. bell*4 # index 1 4 8 4 -- timbre sweeps up and back
ex. lead(3,8) # index 0.5 2 -- alternating bright/mellow

MARKOV EVOLUTION (~mk)

The ~mk operator uses a Markov chain to rewrite the pattern each cycle. Transition probabilities are built from the token bigrams of the original pattern — so the machine follows the pattern's own grammar.

SyntaxEffect
~mkMarkov rewrite with strength 0.7 (default)
~mk 0.3Lower strength = more random (0 = fully random, 1 = fully Markov)
~mk 0.95High strength = closely follows original transitions
ex. bd sn hh oh ~mk -- sequence morphs using its own transitions
ex. c4 e4 g4 b4 ~mk 0.6 -- melodic Markov walk

URL SHARING

Every session is automatically encoded in the URL hash after you evaluate or ship a pattern. Copy the URL from the address bar and share it — anyone who opens it hears exactly what you built.

  • The hash updates silently after every CTRL+ENTER and every SHIP
  • Opening a URL with a hash restores all patterns + global settings automatically
  • No server required — all state is in the URL itself

SAVE / SESSIONS

Save named snapshots of your session to browser storage. Recall them from the preset overlay.

  • [ SAVE ] in the header opens a name input — type a name and press Enter
  • In the [ PRE ] overlay, click the SAVED tab to see your sessions
  • Each saved session stores all patterns, BPM, key, scale, and effects settings
  • Sessions persist until you delete them or clear browser storage

PATTERN LIBRARY (@name)

Save individual patterns with names and reference them using @name syntax.

ActionHow
Save a patternClick [ LIB ] on the row, enter a name when prompted
Load a patternType @name anywhere in a row's pattern field
Combine with params@kick-groove # gain 0.8
ex. @acid-bass # pitch 0.5 -- load library pattern, transposed down

WAV EXPORT

Render N cycles to a WAV file using OfflineAudioContext — no recording, no screen capture.

  • Click [ WAV ] in the header
  • Enter the number of cycles (1–64) and click RENDER
  • Tidal Waves renders the audio at full speed in the background and downloads a stereo 16-bit WAV
  • Maximum render duration is 2 minutes regardless of cycle count
  • The filename includes a timestamp: tidal-waves-{timestamp}.wav

VISUAL CONTROLS
FeatureHow
Instrument label Hover over any dot on the cycle wheel to see the instrument name
Ring radius = gain Drag a ring inward to lower its volume, outward to raise it. Change is immediate (no SHIP needed).
Density heatmap In Stage Mode, rings show a white glow that brightens in regions where events are clustered

4-OPERATOR FM + fm INSTRUMENT

The fm instrument uses a 4-operator FM engine with selectable routing algorithms. Use the [ ALG ] button in a row's [ CTRL ] panel to cycle between algorithms.

AlgorithmCharacter
PARALLELAll three modulators hit the carrier simultaneously — complex, dense timbres
SERIALModulators chain in series — deep, evolving harmonic stacks
FEEDBACKOp3 feeds back into itself before modulating the carrier — metallic, screaming
ex. fm(3,8) # index 2 4 6 # pitch 1 1.5 -- custom FM with cycling params

LFO AS PATTERN

The filter LFO rate can follow a rhythm pattern. In the FLT section of the global bar, the text input next to the cutoff slider accepts a mini-notation pattern string.

  • The LFO rate is set each cycle to events-per-second derived from the pattern
  • Filter must be enabled (FLT:ON) for the LFO to be audible
lfo: hh*4 -- LFO rate follows hihat grid (4 Hz at 60bpm/4beats)
lfo: bd(3,8) -- LFO syncs to Euclidean kick rhythm

NETWORK SESSIONS

Multi-user sessions are implemented but not yet enabled on this deployment. The infrastructure uses a Cloudflare Worker for shared state and server-side clock sync.

ENABLING: Deploy the included Cloudflare Worker, then run node scripts/multiuser.js enable and redeploy. See DEPLOY.md for full instructions.
└─ TIDAL WAVES // USER GUIDE